From 15a41ec38eaf5baca7c4266de52d1ae86ee9488b Mon Sep 17 00:00:00 2001
From: Jannis Harder <harder@informatik.uni-luebeck.de>
Date: Mon, 2 May 2011 02:28:19 +0200
Subject: 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      | 30 ++++++++++++++------------
 src/jrummikub/util/Event1.java     | 40 ++++++++++++++++++++++------------
 src/jrummikub/util/Event2.java     | 44 ++++++++++++++++++++++++++------------
 src/jrummikub/util/IEvent.java     | 17 +++++++++++++--
 src/jrummikub/util/IEvent1.java    | 22 +++++++++++++++++--
 src/jrummikub/util/IEvent2.java    | 24 +++++++++++++++++++--
 src/jrummikub/util/IListener.java  |  6 +++++-
 src/jrummikub/util/IListener1.java | 15 ++++++++++++-
 src/jrummikub/util/IListener2.java | 19 +++++++++++++++-
 9 files changed, 166 insertions(+), 51 deletions(-)

(limited to 'src')

diff --git a/src/jrummikub/util/Event.java b/src/jrummikub/util/Event.java
index 1a68eac..698e0ed 100644
--- a/src/jrummikub/util/Event.java
+++ b/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
-  public void add(IListener listener) {
-    listeners.add(listener);
-  }
+	@Override
+	public void add(IListener listener) {
+		listeners.add(listener);
+	}
 
-  @Override
-  public void remove(IListener listener) {
-    listeners.remove(listener);
-  }
+	@Override
+	public void remove(IListener listener) {
+		listeners.remove(listener);
+	}
 
-  public void fire() {
-    for (IListener listener : listeners) {
-      listener.fire();
-    }
-  }
+	/** Generate a single event */
+	public void fire() {
+		for (IListener listener : listeners) {
+			listener.fire();
+		}
+	}
 }
diff --git a/src/jrummikub/util/Event1.java b/src/jrummikub/util/Event1.java
index f0595f9..8ddf2a5 100644
--- a/src/jrummikub/util/Event1.java
+++ b/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
-  public void add(IListener1<T> listener) {
-    listeners.add(listener);
-  }
+	@Override
+	public void add(IListener1<T> listener) {
+		listeners.add(listener);
+	}
 
-  @Override
-  public void remove(IListener1<T> listener) {
-    listeners.remove(listener);
-  }
+	@Override
+	public void remove(IListener1<T> listener) {
+		listeners.remove(listener);
+	}
 
-  public void fire(T value) {
-    for (IListener1<T> listener : listeners) {
-      listener.fire(value);
-    }
-  }
+	/**
+	 * Generate a single event
+	 * 
+	 * @param value
+	 *            the event parameter
+	 */
+	public void fire(T value) {
+		for (IListener1<T> listener : listeners) {
+			listener.fire(value);
+		}
+	}
 }
diff --git a/src/jrummikub/util/Event2.java b/src/jrummikub/util/Event2.java
index c7ca8e7..f89446e 100644
--- a/src/jrummikub/util/Event2.java
+++ b/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
-  public void add(IListener2<T1, T2> listener) {
-    listeners.add(listener);
-  }
+	@Override
+	public void add(IListener2<T1, T2> listener) {
+		listeners.add(listener);
+	}
 
-  @Override
-  public void remove(IListener2<T1, T2> listener) {
-    listeners.remove(listener);
-  }
+	@Override
+	public void remove(IListener2<T1, T2> listener) {
+		listeners.remove(listener);
+	}
 
-  public void fire(T1 value1, T2 value2) {
-    for (IListener2<T1, T2> listener : listeners) {
-      listener.fire(value1, value2);
-    }
-  }
+	/**
+	 * Generate a single event
+	 * 
+	 * @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);
+		}
+	}
 }
diff --git a/src/jrummikub/util/IEvent.java b/src/jrummikub/util/IEvent.java
index 2295118..3aa13ba 100644
--- a/src/jrummikub/util/IEvent.java
+++ b/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);
 }
diff --git a/src/jrummikub/util/IEvent1.java b/src/jrummikub/util/IEvent1.java
index 4108078..52b9bf4 100644
--- a/src/jrummikub/util/IEvent1.java
+++ b/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);
 }
diff --git a/src/jrummikub/util/IEvent2.java b/src/jrummikub/util/IEvent2.java
index ac68c4f..967b65c 100644
--- a/src/jrummikub/util/IEvent2.java
+++ b/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);
 }
diff --git a/src/jrummikub/util/IListener.java b/src/jrummikub/util/IListener.java
index 37d79c0..9030f71 100644
--- a/src/jrummikub/util/IListener.java
+++ b/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();
 }
diff --git a/src/jrummikub/util/IListener1.java b/src/jrummikub/util/IListener1.java
index 8dfeaf3..c5e7253 100644
--- a/src/jrummikub/util/IListener1.java
+++ b/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);
 }
diff --git a/src/jrummikub/util/IListener2.java b/src/jrummikub/util/IListener2.java
index b1832c1..1733208 100644
--- a/src/jrummikub/util/IListener2.java
+++ b/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);
 }
-- 
cgit v1.2.3