javadocs

src/net/gmx/nosefish/fishysigns/Log.java

@@ -1,20 +1,36 @@
 package net.gmx.nosefish.fishysigns;
 
-import net.canarymod.logger.CanaryLevel;
 import net.canarymod.logger.Logman;
 import net.canarymod.plugin.Plugin;
 
+/**
+ * Static access to the plugin's logger. 
+ *  
+ * @author Stefan Steinheimer (nosefish)
+ *
+ */
+// FishySigns aren't plugins, so they don't have their own.
+// They don't even know which plugin loads them, so this
+// is a simple way to provide them with logger access.
 public final class Log {
 	private static Logman logger = null;
 
+	/**
+	 * Initializes the class. Called by the plugin.
+	 * 
+	 * @param plugin
+	 */
 	public static void initialize(Plugin plugin) {
 		logger = plugin.getLogman();
-		logger.setLevel(CanaryLevel.PLUGIN_DEBUG);
-		for (java.util.logging.Handler h:logger.getParent().getHandlers()) {
-			h.setLevel(CanaryLevel.ALL);
-		}
+		// TODO: find out how to set log level properly
 	}
 
+	/**
+	 * Gets the FishySigns plugin's <code>Logman</code>.
+	 * 
+	 * @return
+	 *     the <code>Logman</code>
+	 */
 	public static Logman get() {
 		if (logger != null) {
 			return logger;

src/net/gmx/nosefish/fishysigns/activator/Activatable.java

@@ -3,7 +3,13 @@
 import net.gmx.nosefish.fishylib.worldmath.FishyLocationInt;
 
 
-
+/**
+ * Instances can register themselves with the <code>ActivationManager</code>
+ * be "acitvated" by certain events.
+ * 
+ * @author Stefan Steinheimer (nosefish)
+ *
+ */
 public interface Activatable {
 	/**
 	 *  

src/net/gmx/nosefish/fishysigns/activator/Activator.java

@@ -1,5 +1,12 @@
 package net.gmx.nosefish.fishysigns.activator;
 
+/**
+ * Passed to the <code>activate</code> method of
+ * Activatables. Contain event data.
+ * 
+ * @author Stefan Steinheimer (nosefish)
+ *
+ */
 public interface Activator {
 
 }

src/net/gmx/nosefish/fishysigns/activator/ActivatorBlocks.java

@@ -4,17 +4,38 @@
 import java.util.LinkedList;
 import java.util.List;
 
-
+/**
+ * Contains a list of <code>ImmutableBlockStateChange</code> instances.
+ * 
+ * @author Stefan Steinheimer
+ *
+ */
 public class ActivatorBlocks implements Activator {
 	protected final List<ImmutableBlockStateChange> blocks = new LinkedList<ImmutableBlockStateChange>();
 
+	/**
+	 * Constructor
+	 */
 	public ActivatorBlocks() {
 	}
 
+	/**
+	 * Adds a change to the list. 
+	 * To be used by the watcher issuing this.
+	 * 
+	 * @param 
+	 *     change the block state change to add
+	 */
 	public void add(ImmutableBlockStateChange change) {
 		blocks.add(change);
 	}
 
+	/**
+	 * Gets the list of changes.
+	 * To be used by the receiving <code>Activatable</code>
+	 * 
+	 * @return
+	 */
 	public List<ImmutableBlockStateChange> getBlockStateChanges() {
 		return Collections.unmodifiableList(blocks);
 	}

src/net/gmx/nosefish/fishysigns/activator/ActivatorPlayerRightClick.java

@@ -2,19 +2,47 @@
 
 import net.gmx.nosefish.fishysigns.world.ImmutableLocationBlockState;
 
+/**
+ * Contains information about a right mouse button click
+ * performed by a player.
+ * 
+ * @author Stefan Steinheimer (nosefish)
+ *
+ */
 public class ActivatorPlayerRightClick implements Activator {
 	private final String playerName;
 	private final ImmutableLocationBlockState block;
 
+	/**
+	 * Constructor
+	 * 
+	 * @param 
+	 *     name the name of the clicking player
+	 *     
+	 * @param block
+	 *     the block on which the player clicked
+	 */
 	public ActivatorPlayerRightClick(String name, ImmutableLocationBlockState block) {
 		this.playerName = name;
 		this.block = block;
 	}
 
+	/**
+	 * Gets the name of the clicking player.
+	 * 
+	 * @return
+	 *     the player name
+	 */
 	public String getPlayerName() {
 		return playerName;
 	}
 
+	/**
+	 * Gets a thread-safe representation of the block on which the player clicked.
+	 * 
+	 * @return
+	 *    the block
+	 */
 	public ImmutableLocationBlockState getBlockState() {
 		return block;
 	}

src/net/gmx/nosefish/fishysigns/activator/ActivatorRadio.java

@@ -1,5 +1,7 @@
 package net.gmx.nosefish.fishysigns.activator;
 
+//TODO: the generic type argument gets removed by the ActivationManager,
+// resulting in an uncheckd cast for the Activatable. That is just wrong.
 public class ActivatorRadio<T> implements Activator {
 	private final String bandName;
 	private final T signal;
@@ -16,7 +18,4 @@ public String getBandName() {
 	public T getSignal() {
 		return signal;
 	}
-
-
-
 }

src/net/gmx/nosefish/fishysigns/radio/RadioBand.java

@@ -12,7 +12,7 @@
  * 
  * The signal should usually be an immutable type,
  * although there are cases where a thread-safe
- * mutable type is more appropriate.
+ * mutable type is appropriate.
  * 
  * @author Stefan Steinheimer (nosefish)
  *
@@ -24,14 +24,33 @@ public class RadioBand<T> {
 	private final Set<Long> receivers = new TreeSet<Long>();
 	private volatile T signal = null;
 
+	/**
+	 * Constructor
+	 * 
+	 * @param name
+	 *     the name of the radio band
+	 */
 	public RadioBand(String name) {
 		this.name = name;
 	}
 
+	/**
+	 * Gets the most recent broadcast made on this band
+	 * 
+	 * @return
+	 *     the last signal transmitted, or <code>null</code> if there was none
+	 */
 	public T getLastBroadcast() {
 		return signal;
 	}
 
+	/**
+	 * Broadcasts a new signal. Activates all registered
+	 * <code>Activatables</code>
+	 * 
+	 * @param signal
+	 *     the signal to send
+	 */
 	public void newBroadcast(T signal) {
 		this.signal = signal;
 		Long[] toActivate;
@@ -45,24 +64,51 @@ public void newBroadcast(T signal) {
 		ActivationManager.getInstance().activateAll(activator, toActivate);
 	}
 
+	/**
+	 * Registers an <code>Activatable</code> to
+	 * receive transmissions from this band.
+	 * 
+	 * @param receiverID
+	 *     the <code>Activatable.getID()</code>
+	 */
 	public void register(Long receiverID) {
 		synchronized(receivers) {
 			receivers.add(receiverID);
 		}
 	}
 
+	/**
+	 * Removes an <code>Activatable</code>
+	 * from the list of receivers.
+	 * 
+	 * @param receiverID
+	 *     the <code>Activatable.getID()</code>
+	 */
 	public void remove(Long receiverID) {
 		synchronized(receivers) {
 			receivers.remove(receiverID);
 		}
 	}
 
+	/**
+	 * Finds out if anyone is listening
+	 * 
+	 * @return
+	 *     <code>true</code> if <code>Activatables</code> are registered,
+	 *     <code>false</code> if the list of receivers is empty
+	 */
 	public boolean hasListeners() {
 		synchronized (receivers) {
 			return (! receivers.isEmpty());
 		}	
 	}
 
+	/**
+	 * Gets the band name of this RadioBand
+	 * 
+	 * @return
+	 *     the band name
+	 */
 	public String getName() {
 		return name;
 	}

src/net/gmx/nosefish/fishysigns/radio/RadioTower.java

@@ -15,21 +15,57 @@
  *     the type of signals that this tower can broadcast.
  */
 public class RadioTower<T> {
-
+	// used for tuneIn and remove
 	private ReentrantLock receiverLock = new ReentrantLock();
+
 	private ConcurrentMap<String, RadioBand<T>> bands = new ConcurrentHashMap<String, RadioBand<T>>();
 
+	/**
+	 * Broadcast a signal.
+	 * 
+	 * @param bandName
+	 *     the band to transmit on
+	 *     
+	 * @param signal
+	 *     the signal to transmit
+	 */
 	public void broadcast(String bandName, T signal) {
 		bands.putIfAbsent(bandName, new RadioBand<T>(bandName));
 		bands.get(bandName).newBroadcast(signal);
 	}
 
+
+	/**
+	 * Gets the last signal that was sent on the specified band.
+	 * 
+	 * @param bandName
+	 *     the band to check
+	 *     
+	 * @return
+	 *     The most recently transmitted signal. 
+	 *     <code>null</code> if the band does not exist or if nothing has been transmitted yet.
+	 */
 	public T getLastBroadcast(String bandName) {
 		RadioBand<T> band = bands.get(bandName);
 		return (band != null) ?
 				band.getLastBroadcast(): null;
 	}
 
+	/**
+	 * Register an <code>Activatable</code> to receive signals
+	 * that are broadcast over the specified band 
+	 * (as <code>ActivatorRadio</code>). 
+	 * 
+	 * You must register even those <code>Activatables</code>
+	 * that only use getLastBroadcast, because the band will 
+	 * cease to exist when the last receiver is removed.
+	 * 
+	 * @param id
+	 *     the id of the Activatable (use <code>getID</code>)
+	 *     
+	 * @param bandName
+	 *     the bandName
+	 */
 	public void tuneIn(Long id, String bandName) {
 		// we have to lock so that we can't remove a
 		// band while adding a receiver
@@ -42,6 +78,17 @@ public void tuneIn(Long id, String bandName) {
 		}
 	}
 
+	/**
+	 * Remove the activatable from the list of receivers.
+	 * Call this in your <code>remove</code> method for every
+	 * band for which you have previously called <code>tuneIn</code>. 
+	 * 
+	 * @param id
+	 *     the id of the Activatable (use <code>getID</code>)
+	 *     
+	 * @param bandName
+	 *     the band name from which to unregister
+	 */
 	public void stopListening(Long id, String bandName) {
 		RadioBand<T> band = bands.get(bandName);
 		if (band != null) {
@@ -50,6 +97,13 @@ public void stopListening(Long id, String bandName) {
 		}
 	}
 
+	/**
+	 * Remove a band entirely if it has no receivers.
+	 * Don't want memory leaks, however tiny.
+	 * 
+	 * @param band
+	 *     the band to check
+	 */
 	private void removeIfNobodyListens(RadioBand<T> band) {
 		// we have to lock so that we can't remove a
 		// band while adding a receiver