Documented the Event/Listener classes

git-svn-id: svn://sunsvr01.isp.uni-luebeck.de/swproj13/trunk@60 72836036-5685-4462-b002-a69064685172

src/jrummikub/util/Event.java

@@ -2,22 +2,24 @@ package jrummikub.util;
 
 import java.util.HashSet;
 
+/** Simple parameterless event generator */
 public class Event implements IEvent {
-  private HashSet<IListener> listeners = new HashSet<IListener>();
+	private HashSet<IListener> listeners = new HashSet<IListener>();
 
-  @Override
+	@Override
-  public void add(IListener listener) {
+	public void add(IListener listener) {
-    listeners.add(listener);
+		listeners.add(listener);
-  }
+	}
 
-  @Override
+	@Override
-  public void remove(IListener listener) {
+	public void remove(IListener listener) {
-    listeners.remove(listener);
+		listeners.remove(listener);
-  }
+	}
 
-  public void fire() {
+	/** Generate a single event */
-    for (IListener listener : listeners) {
+	public void fire() {
-      listener.fire();
+		for (IListener listener : listeners) {
-    }
+			listener.fire();
-  }
+		}
+	}
 }

src/jrummikub/util/Event1.java

@@ -2,22 +2,34 @@ package jrummikub.util;
 
 import java.util.HashSet;
 
+/**
+ * Simple single parameter event generator
+ * 
+ * @param <T>
+ *            type of the event parameter
+ */
 public class Event1<T> implements IEvent1<T> {
-  private HashSet<IListener1<T>> listeners = new HashSet<IListener1<T>>();
+	private HashSet<IListener1<T>> listeners = new HashSet<IListener1<T>>();
 
-  @Override
+	@Override
-  public void add(IListener1<T> listener) {
+	public void add(IListener1<T> listener) {
-    listeners.add(listener);
+		listeners.add(listener);
-  }
+	}
 
-  @Override
+	@Override
-  public void remove(IListener1<T> listener) {
+	public void remove(IListener1<T> listener) {
-    listeners.remove(listener);
+		listeners.remove(listener);
-  }
+	}
 
-  public void fire(T value) {
+	/**
-    for (IListener1<T> listener : listeners) {
+	 * Generate a single event
-      listener.fire(value);
+	 * 
-    }
+	 * @param value
-  }
+	 *            the event parameter
+	 */
+	public void fire(T value) {
+		for (IListener1<T> listener : listeners) {
+			listener.fire(value);
+		}
+	}
 }

src/jrummikub/util/Event2.java

@@ -2,22 +2,38 @@ package jrummikub.util;
 
 import java.util.HashSet;
 
+/**
+ * Simple single parameter event generator
+ * 
+ * @param <T1>
+ *            type of the first event parameter
+ * @param <T2>
+ *            type of the second event parameter
+ */
 public class Event2<T1, T2> implements IEvent2<T1, T2> {
-  private HashSet<IListener2<T1, T2>> listeners = new HashSet<IListener2<T1, T2>>();
+	private HashSet<IListener2<T1, T2>> listeners = new HashSet<IListener2<T1, T2>>();
 
-  @Override
+	@Override
-  public void add(IListener2<T1, T2> listener) {
+	public void add(IListener2<T1, T2> listener) {
-    listeners.add(listener);
+		listeners.add(listener);
-  }
+	}
 
-  @Override
+	@Override
-  public void remove(IListener2<T1, T2> listener) {
+	public void remove(IListener2<T1, T2> listener) {
-    listeners.remove(listener);
+		listeners.remove(listener);
-  }
+	}
 
-  public void fire(T1 value1, T2 value2) {
+	/**
-    for (IListener2<T1, T2> listener : listeners) {
+	 * Generate a single event
-      listener.fire(value1, value2);
+	 * 
-    }
+	 * @param value1
-  }
+	 *            the first event parameter
+	 * @param value2
+	 *            the second event parameter
+	 */
+	public void fire(T1 value1, T2 value2) {
+		for (IListener2<T1, T2> listener : listeners) {
+			listener.fire(value1, value2);
+		}
+	}
 }

src/jrummikub/util/IEvent.java

@@ -1,7 +1,20 @@
 package jrummikub.util;
 
+/** Interface for classes that can generate parameterless events */
 public interface IEvent {
-  public void add(IListener listener);
+	/**
+	 * Start to publish all events to a given listener
+	 * 
+	 * @param listener
+	 *            target listener
+	 */
+	public void add(IListener listener);
 
-  public void remove(IListener listener);
+	/**
+	 * Stop publishing events to a given listener
+	 * 
+	 * @param listener
+	 *            target listener
+	 */
+	public void remove(IListener listener);
 }

src/jrummikub/util/IEvent1.java

@@ -1,7 +1,25 @@
 package jrummikub.util;
 
+/**
+ * Interface for classes that can generate events having a single parameter
+ * 
+ * @param <T>
+ *            type of the event parameter
+ */
 public interface IEvent1<T> {
-  public void add(IListener1<T> listener);
+	/**
+	 * Start to publish all events to a given listener
+	 * 
+	 * @param listener
+	 *            target listener
+	 */
+	public void add(IListener1<T> listener);
 
-  public void remove(IListener1<T> listener);
+	/**
+	 * Stop publishing events to a given listener
+	 * 
+	 * @param listener
+	 *            target listener
+	 */
+	public void remove(IListener1<T> listener);
 }

src/jrummikub/util/IEvent2.java

@@ -1,7 +1,27 @@
 package jrummikub.util;
 
+/**
+ * Interface for classes that can generate events having a two parameters
+ * 
+ * @param <T1>
+ *            type of the first event parameter
+ * @param <T2>
+ *            type of the second event parameter
+ */
 public interface IEvent2<T1, T2> {
-  public void add(IListener2<T1, T2> listener);
+	/**
+	 * Start to publish all events to a given listener
+	 * 
+	 * @param listener
+	 *            target listener
+	 */
+	public void add(IListener2<T1, T2> listener);
 
-  public void remove(IListener2<T1, T2> listener);
+	/**
+	 * Stop publishing events to a given listener
+	 * 
+	 * @param listener
+	 *            target listener
+	 */
+	public void remove(IListener2<T1, T2> listener);
 }

src/jrummikub/util/IListener.java

@@ -1,5 +1,9 @@
 package jrummikub.util;
 
+/**
+ * Interface for classes that can receive parameterless events
+ */
 public interface IListener {
-  public void fire();
+	/** This method is called whenever a class we're listening to emits an event */
+	public void fire();
 }

src/jrummikub/util/IListener1.java

@@ -1,5 +1,18 @@
 package jrummikub.util;
 
+/**
+ * Interface for classes that can receive parameterless events having a single
+ * parameter
+ * 
+ * @param <T>
+ *            type of the event parameter
+ */
 public interface IListener1<T> {
-  public void fire(T value);
+	/**
+	 * This method is called whenever a class we're listening to emits an event
+	 * 
+	 * @param value
+	 *            the event parameter
+	 */
+	public void fire(T value);
 }

src/jrummikub/util/IListener2.java

@@ -1,5 +1,22 @@
 package jrummikub.util;
 
+/**
+ * Interface for classes that can receive parameterless events having a two
+ * parameters
+ * 
+ * @param <T1>
+ *            type of the first event parameter
+ * @param <T2>
+ *            type of the first event parameter
+ */
 public interface IListener2<T1, T2> {
-  public void fire(T1 value1, T2 value2);
+	/**
+	 * This method is called whenever a class we're listening to emits an event
+	 * 
+	 * @param value1
+	 *            the first event parameter
+	 * @param value2
+	 *            the second event parameter
+	 */
+	public void fire(T1 value1, T2 value2);
 }