Remove RenderTickets since thir main use can not easily be implemented reliably

Author: TBlueF

src/main/java/de/bluecolored/bluemap/api/BlueMapAPI.java

@@ -27,6 +27,7 @@
 import java.util.ArrayList;
 import java.util.Collection;
 import java.util.Optional;
+import java.util.UUID;
 
 import de.bluecolored.bluemap.api.renderer.BlueMapMap;
 import de.bluecolored.bluemap.api.renderer.BlueMapWorld;
@@ -44,16 +45,36 @@ public abstract class BlueMapAPI {
 
 	/**
 	 * Getter for all {@link BlueMapMap}s loaded by BlueMap.
-	 * @return an immutable collection of all loaded {@link BlueMapMap}s 
+	 * @return an unmodifiable collection of all loaded {@link BlueMapMap}s 
 	 */
 	public abstract Collection<BlueMapMap> getMaps();
 
 	/**
 	 * Getter for all {@link BlueMapWorld}s loaded by BlueMap.
-	 * @return an immutable collection of all loaded {@link BlueMapWorld}s
+	 * @return an unmodifiable collection of all loaded {@link BlueMapWorld}s
 	 */
 	public abstract Collection<BlueMapWorld> getWorlds();
 
+	/**
+	 * Getter for a {@link BlueMapWorld} loaded by BlueMap with the given {@link UUID}.
+	 *
+	 * <p><i>See the documentation of {@link BlueMapWorld#getUuid()} for more information about the nature of the worlds {@link UUID}s!</i></p>  
+	 * 
+	 * @see BlueMapWorld#getUuid()
+	 * 
+	 * @param uuid the {@link UUID} of the world
+	 * 
+	 * @return an {@link Optional} with the {@link BlueMapWorld} if it exists
+	 */
+	public abstract Optional<BlueMapWorld> getWorld(UUID uuid);
+	
+	/**
+	 * Getter for a {@link BlueMapMap} loaded by BlueMap with the given id.
+	 * @param id the map id (equivalent to the id configured in BlueMap's config
+	 * @return an {@link Optional} with the {@link BlueMapMap} if it exists
+	 */
+	public abstract Optional<BlueMapMap> getMap(String id);
+	
 	/**
 	 * Getter for the installed BlueMap version
 	 * @return the version-string
@@ -91,26 +112,30 @@ public static synchronized Optional<BlueMapAPI> getInstance() {
 	 * Used by BlueMap to register the API and call the listeners properly. 
 	 * @param instance {@link BlueMapAPI}-instance
 	 */
-	static synchronized void registerInstance(BlueMapAPI instance) {
-		if (BlueMapAPI.instance != null) throw new IllegalStateException("There already is an API instance registered!");
+	protected static synchronized boolean registerInstance(BlueMapAPI instance) {
+		if (BlueMapAPI.instance != null) return false;
 
 		BlueMapAPI.instance = instance;
 
 		for (BlueMapAPIListener listener : BlueMapAPI.listener) {
 			listener.onEnable(BlueMapAPI.instance);
 		}
+
+		return true;
 	}
 
 	/**
 	 * Used by BlueMap to unregister the API and call the listeners properly.
 	 */
-	static synchronized void unregisterInstance() {
-		if (BlueMapAPI.instance == null) throw new IllegalStateException("There is no API instance registered!");
+	protected static synchronized boolean unregisterInstance(BlueMapAPI instance) {
+		if (BlueMapAPI.instance != instance) return false;
 
 		for (BlueMapAPIListener listener : BlueMapAPI.listener) {
 			listener.onDisable(BlueMapAPI.instance);
 		}	
 
 		BlueMapAPI.instance = null;
+		
+		return true;
 	}
 }

src/main/java/de/bluecolored/bluemap/api/renderer/BlueMapMap.java

@@ -28,6 +28,10 @@
 import com.flowpowered.math.vector.Vector3d;
 import com.flowpowered.math.vector.Vector3i;
 
+/**
+ * This class represents a map that is rendered by BlueMap of a specific world ({@link BlueMapWorld}).
+ * Each map belongs to a map configured in BlueMap's configuration file (in the <code>maps: []</code> list).
+ */
 public interface BlueMapMap {
 
 	/**

src/main/java/de/bluecolored/bluemap/api/renderer/BlueMapWorld.java

@@ -28,22 +28,26 @@
 import java.util.Collection;
 import java.util.UUID;
 
+/**
+ * This class represents a world loaded by BlueMap.
+ */
 public interface BlueMapWorld {
 
 	/**
 	 * <p>Getter for the {@link UUID} of the world.</p>
 	 * <p>
-	 * 	The {@link UUID} of this world is <b>not</b> guaranteed to be consistent across reloads/restarts!
+	 * 	The {@link UUID}s of this worlds are <b>not</b> guaranteed to be consistent across reloads/restarts!
 	 * </p>
 	 * <p>
 	 * 	<b>Implementation notes:</b><br>
 	 * 	The used UUID highly depends on the implementation
 	 * 	<table>
-	 *  	<tr><th>Sponge</th><td>The UUID is equal to the returned UUID by World-Instances of the Sponge-API, so you can just use <code>spongeWorld.getUniqueId()</code><td><tr>
-	 *  	<tr><th>Bukkit</th><td>The UUID is equal to the returned UUID by World-Instances of the Bukkit-API, so you can just use <code>bukkitWorld.getUID()</code><td><tr>
+	 *  	<tr><th>Sponge</th><td>The UUID is equal to the returned UUID by world-instances of the Sponge-API, so you can just use <code>spongeWorld.getUniqueId()</code><td><tr>
+	 *  	<tr><th>Bukkit</th><td>The UUID is equal to the returned UUID by world-instances of the Bukkit-API, so you can just use <code>bukkitWorld.getUID()</code><td><tr>
 	 *  	<tr><th>Forge</th><td>The UUID is randomly generated, and changes on each reload/restart</code><td><tr>
 	 *  	<tr><th>CLI</th><td>The UUID is randomly generated, and changes on each reload/restart</code><td><tr>
 	 *  </table>
+	 * </p>
 	 * 
 	 * @return the {@link UUID} of the world
 	 */
@@ -57,7 +61,7 @@ public interface BlueMapWorld {
 
 	/**
 	 * Getter for all {@link BlueMapMap}s for this world
-	 * @return a {@link Collection} of all {@link BlueMapMap}s for this world
+	 * @return an unmodifiable {@link Collection} of all {@link BlueMapMap}s for this world
 	 */
 	Collection<BlueMapMap> getMaps();
 

src/main/java/de/bluecolored/bluemap/api/renderer/RenderTicket.java

@@ -24,89 +24,110 @@
  */
 package de.bluecolored.bluemap.api.renderer;
 
-import java.util.Collection;
-import java.util.HashSet;
 import java.util.UUID;
 
 import com.flowpowered.math.vector.Vector2i;
 import com.flowpowered.math.vector.Vector3i;
 
+/**
+ * The {@link Renderer} is used to schedule tile-renders and process them on a number of different threads.
+ */
 public interface Renderer {
 
 	/**
-	 * Schedules the map-tile at this block position for all maps of this world and returns the created render-tickets.<br>
-	 * If there already is a render-ticket scheduled for a tile, the existing one is returned instead of creating a new one.
+	 * Schedules the render of the map-tile at this block position for all maps of this world.<br>
+	 * If there already is a render scheduled for one of the tiles, a second one will <b>not</b> be created.
 	 * 
 	 * @param world the {@link UUID} of the {@link BlueMapWorld} to render
 	 * @param blockPosition a {@link Vector3i} for the block-position to render (the whole map-tiles will be rendered not only that block)
 	 * 
-	 * @return a {@link Collection} of the scheduled {@link RenderTicket}s 
+	 * @throws IllegalArgumentException if there is no world loaded with the provided {@link UUID} 
 	 */
-	Collection<RenderTicket> render(UUID world, Vector3i blockPosition);
+	void render(UUID world, Vector3i blockPosition);
 
 	/**
-	 * Schedules the map-tile at this block position for all maps of this world and returns the created render-tickets.<br>
-	 * If there already is a render-ticket scheduled for a tile, the existing one is returned instead of creating a new one.
+	 * Schedules the render of the map-tile at this block position for all maps of this world.<br>
+	 * If there already is a render scheduled for one of the tiles, a second one will <b>not</b> be created.
 	 * 
 	 * @param world the {@link BlueMapWorld} to render
 	 * @param blockPosition a {@link Vector3i} for the block-position to render (the whole map-tiles will be rendered not only that block)
-	 * 
-	 * @return a {@link Collection} of the scheduled {@link RenderTicket}s 
 	 */
-	default Collection<RenderTicket> render(BlueMapWorld world, Vector3i blockPosition) {
-		Collection<RenderTicket> tickets = new HashSet<>();
-		
+	default void render(BlueMapWorld world, Vector3i blockPosition) {
 		for (BlueMapMap map : world.getMaps()) {
-			tickets.add(render(map, blockPosition));
+			render(map, blockPosition);
 		}
-		
-		return tickets;
 	}
 
 	/**
-	 * Schedules the map-tile at this block position and returns the created render-ticket.<br>
-	 * If there already is a render-ticket scheduled for that map-tile, the existing one is returned instead of creating a new one.
+	 * Schedules the render of the map-tile at this block position.<br>
+	 * If there already is a render scheduled for the tile, a second one will <b>not</b> be created.
 	 * 
 	 * @param mapId the id of the {@link BlueMapMap} to render
 	 * @param blockPosition a {@link Vector3i} for the block-position to render (the whole map-tile will be rendered not only that block)
 	 * 
 	 * @return the scheduled {@link RenderTicket}
+	 * 
+	 * @throws IllegalArgumentException if there is no map loaded with the provided mapId
 	 */
-	RenderTicket render(String mapId, Vector3i blockPosition);
+	void render(String mapId, Vector3i blockPosition);
 
 	/**
-	 * Schedules the map-tile at this block position and returns the created render-ticket.<br>
-	 * If there already is a render-ticket scheduled for that map-tile, the existing one is returned instead of creating a new one.
+	 * Schedules the render of map-tile at this block position and returns the created render-ticket.<br>
+	 * If there already is a render scheduled for the tile, a second one will <b>not</b> be created.
 	 * 
 	 * @param map the {@link BlueMapMap}
 	 * @param blockPosition a {@link Vector3i} for the block-position to render (the whole map-tile will be rendered not only that block)
-	 * 
-	 * @return the scheduled {@link RenderTicket}
 	 */
-	default RenderTicket render(BlueMapMap map, Vector3i blockPosition) {
-		return render(map, map.posToTile(blockPosition));
+	default void render(BlueMapMap map, Vector3i blockPosition) {
+		render(map, map.posToTile(blockPosition));
 	}
 
 	/**
-	 * Schedules the map-tile and returns the created render-ticket.<br>
-	 * If there already is a render-ticket scheduled for that map-tile, the existing one is returned instead of creating a new one.
+	 * Schedules the render of the map-tile.<br>
+	 * If there already is a render scheduled for the tile, a second one will <b>not</b> be created.
 	 * 
 	 * @param mapId the id of the {@link BlueMapMap} to render
 	 * @param tile a {@link Vector2i} for the tile-position to render
 	 * 
-	 * @return the scheduled {@link RenderTicket}
+	 * @throws IllegalArgumentException if there is no map loaded with the provided mapId
 	 */
-	RenderTicket render(String mapId, Vector2i tile);
+	void render(String mapId, Vector2i tile);
 
 	/**
-	 * Schedules the map-tile and returns the created render-ticket.<br>
-	 * If there already is a render-ticket scheduled for that map-tile, the existing one is returned instead of creating a new one.
+	 * Schedules the render of the map-tile.<br>
+	 * If there already is a render scheduled for the tile, a second one will <b>not</b> be created.
 	 * 
 	 * @param map the {@link BlueMapMap}
 	 * @param tile a {@link Vector2i} for the tile-position to render
-	 * 
-	 * @return the scheduled {@link RenderTicket}
 	 */
-	RenderTicket render(BlueMapMap map, Vector2i tile);
+	void render(BlueMapMap map, Vector2i tile);
+	
+	/**
+	 * Getter for the current size of the render-queue.
+	 * @return the current size of the render-queue
+	 */
+	int renderQueueSize();
+	
+	/**
+	 * Getter for the count of render threads.
+	 * @return the count of render threads
+	 */
+	int renderThreadCount();
+	
+	/**
+	 * Whether this {@link Renderer} is currently running or paused.
+	 * @return <code>true</code> if this renderer is running
+	 */
+	boolean isRunning();
+	
+	/**
+	 * Starts the renderer if it is not already running.
+	 */
+	void start();
+
+	/**
+	 * Pauses the renderer if it currently is running.
+	 */
+	void pause();
 
 }