svn commit: r1097117 - /wicket/trunk/wicket-core/src/main/java/org/apache/wicket/request/cycle/RequestCycleListenerCollection.java

[da...@apache.org]

Author: dashorst
Date: Wed Apr 27 14:06:58 2011
New Revision: 1097117

URL: http://svn.apache.org/viewvc?rev=1097117&view=rev
Log:
Updated the documentation a bit more
Issue: WICKET-3644

Modified:
    wicket/trunk/wicket-core/src/main/java/org/apache/wicket/request/cycle/RequestCycleListenerCollection.java

Modified: wicket/trunk/wicket-core/src/main/java/org/apache/wicket/request/cycle/RequestCycleListenerCollection.java
URL: http://svn.apache.org/viewvc/wicket/trunk/wicket-core/src/main/java/org/apache/wicket/request/cycle/RequestCycleListenerCollection.java?rev=1097117&r1=1097116&r2=1097117&view=diff
==============================================================================
--- wicket/trunk/wicket-core/src/main/java/org/apache/wicket/request/cycle/RequestCycleListenerCollection.java (original)
+++ wicket/trunk/wicket-core/src/main/java/org/apache/wicket/request/cycle/RequestCycleListenerCollection.java Wed Apr 27 14:06:58 2011
@@ -25,7 +25,21 @@ import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
 /**
- * Special, Wicket internal composite {@link IRequestCycleListener} that
+ * Composite {@link IRequestCycleListener} that notifies all registered listeners with each
+ * IRequestCycleListener event.
+ * <p>
+ * <h3>Order of notification</h3>
+ * <p>
+ * {@link #onBeginRequest(RequestCycle)}, {@link #onRequestHandlerScheduled(IRequestHandler)} and
+ * {@link #onRequestHandlerResolved(IRequestHandler)} are notified in first in, first out order.
+ * <p>
+ * {@link #onEndRequest(RequestCycle)} and {@link #onDetach(RequestCycle)} are notified in last in
+ * first out order (i.e. reversed order). So for these events the collection functions as a stack.
+ * <p>
+ * <h3>Exception handling</h3>
+ * <p>
+ * The {@code RequestCycleListenerCollection} will use the first exception handler that is returned
+ * from all listeners in {@link #onException(RequestCycle, Exception)}
  */
 public class RequestCycleListenerCollection extends ListenerCollection<IRequestCycleListener>
 	implements
@@ -34,6 +48,11 @@ public class RequestCycleListenerCollect
 	private static final Logger logger = LoggerFactory.getLogger(RequestCycleListenerCollection.class);
 	private static final long serialVersionUID = 1L;
 
+	/**
+	 * Notifies all registered listeners of the onBeginRequest event in first in first out order,
+	 * i.e. the listener that is the first element of this collection is the first listener to be
+	 * notified of {@code onBeginRequest}.
+	 */
 	public void onBeginRequest(final RequestCycle cycle)
 	{
 		notify(new INotifier<IRequestCycleListener>()
@@ -45,6 +64,13 @@ public class RequestCycleListenerCollect
 		});
 	}
 
+	/**
+	 * Notifies all registered listeners of the {@code onEndRequest} event in first in last out
+	 * order (i.e. the last listener that received an {@code #onBeginRequest} will be the first to
+	 * get notified of an {@code onEndRequest}.
+	 * 
+	 * @see IRequestCycleListener#onEndRequest(RequestCycle)
+	 */
 	public void onEndRequest(final RequestCycle cycle)
 	{
 		reversedNotify(new INotifier<IRequestCycleListener>()
@@ -57,11 +83,35 @@ public class RequestCycleListenerCollect
 	}
 
 	/**
+	 * Notifies all registered listeners of the {@code onDetach} event in first in last out order
+	 * (i.e. the last listener that received an {@code #onBeginRequest} will be the first to get
+	 * notified of an {@code onDetach}.
+	 * 
+	 * @see IRequestCycleListener#onDetach(RequestCycle)
+	 */
+	public void onDetach(final RequestCycle cycle)
+	{
+		reversedNotify(new INotifier<IRequestCycleListener>()
+		{
+			public void notify(IRequestCycleListener listener)
+			{
+				try
+				{
+					listener.onDetach(cycle);
+				}
+				catch (Exception e)
+				{
+					logger.error("Error detaching request cycle listener: " + listener, e);
+				}
+			}
+		});
+	}
+
+	/**
 	 * Notifies all registered listeners of the exception and calls the first handler that was
 	 * returned by the listeners.
 	 * 
-	 * @see org.apache.wicket.request.cycle.IRequestCycleListener#onException(org.apache.wicket.request.cycle.RequestCycle,
-	 *      java.lang.Exception)
+	 * @see IRequestCycleListener#onException(RequestCycle, Exception)
 	 */
 	public IRequestHandler onException(final RequestCycle cycle, final Exception ex)
 	{
@@ -92,24 +142,6 @@ public class RequestCycleListenerCollect
 		return handlers.get(0);
 	}
 
-	public void onDetach(final RequestCycle cycle)
-	{
-		reversedNotify(new INotifier<IRequestCycleListener>()
-		{
-			public void notify(IRequestCycleListener listener)
-			{
-				try
-				{
-					listener.onDetach(cycle);
-				}
-				catch (Exception e)
-				{
-					logger.error("Error detaching request cycle listener: " + listener, e);
-				}
-			}
-		});
-	}
-
 	public void onRequestHandlerResolved(final IRequestHandler handler)
 	{
 		notify(new INotifier<IRequestCycleListener>()
@@ -143,5 +175,4 @@ public class RequestCycleListenerCollect
 			}
 		});
 	}
-
 }