From 7ad38e8c8c69bb0dea3b27d06b0f6a8ffa32e77a Mon Sep 17 00:00:00 2001
From: Trustin Lee <trustin@gmail.com>
Date: Tue, 28 Apr 2009 12:36:06 +0000
Subject: [PATCH] Javadoc

---
 .../netty/channel/ChannelDownstreamHandler.java      | 12 +++++++-----
 .../java/org/jboss/netty/channel/ChannelEvent.java   |  3 ++-
 .../java/org/jboss/netty/channel/ChannelFactory.java |  9 +++++++--
 .../org/jboss/netty/channel/ChannelPipeline.java     |  6 +++---
 .../jboss/netty/channel/ChannelUpstreamHandler.java  | 12 +++++++-----
 .../socket/nio/NioClientSocketChannelFactory.java    |  4 +++-
 .../socket/nio/NioServerSocketChannelFactory.java    |  4 +++-
 .../socket/oio/OioClientSocketChannelFactory.java    |  4 +++-
 .../socket/oio/OioDatagramChannelFactory.java        |  4 +++-
 .../socket/oio/OioServerSocketChannelFactory.java    | 11 ++++-------
 10 files changed, 42 insertions(+), 27 deletions(-)

diff --git a/src/main/java/org/jboss/netty/channel/ChannelDownstreamHandler.java b/src/main/java/org/jboss/netty/channel/ChannelDownstreamHandler.java
index 7722e00c40..5422a5cd8d 100644
--- a/src/main/java/org/jboss/netty/channel/ChannelDownstreamHandler.java
+++ b/src/main/java/org/jboss/netty/channel/ChannelDownstreamHandler.java
@@ -86,16 +86,16 @@ import java.net.SocketAddress;
  * <p>
  * You might want to refer to {@link ChannelUpstreamHandler} to see how a
  * {@link ChannelEvent} is interpreted when going upstream.  Also, please refer
- * to the {@link ChannelEvent} documentation to find out what an upstream event
- * and a downstream event are and what fundamental differences they have, if
- * you didn't read yet.
+ * to the {@link ChannelEvent} and {@link ChannelPipeline} documentation to find
+ * out what an upstream event and a downstream event are, what fundamental
+ * differences they have, and how they flow in a pipeline.
  *
  * <h3>Firing an event to the previous or next handler</h3>
  * <p>
  * You can forward the received event downstream or upstream.  In most cases,
  * {@link ChannelDownstreamHandler} will pass the event to the previous
- * handler (downstream) although it is absolutely normal to pass the event
- * to the next handler (upstream):
+ * handler (downstream) although it is legal to pass the event to the next
+ * handler (upstream):
  *
  * <pre>
  * // Sending the event forward (downstream)
@@ -132,6 +132,8 @@ import java.net.SocketAddress;
  * @author Trustin Lee (tlee@redhat.com)
  *
  * @version $Rev$, $Date$
+ *
+ * @apiviz.exclude ^org\.jboss\.netty\.handler\..*$
  */
 public interface ChannelDownstreamHandler extends ChannelHandler {
 
diff --git a/src/main/java/org/jboss/netty/channel/ChannelEvent.java b/src/main/java/org/jboss/netty/channel/ChannelEvent.java
index acaf101331..87a34e4242 100644
--- a/src/main/java/org/jboss/netty/channel/ChannelEvent.java
+++ b/src/main/java/org/jboss/netty/channel/ChannelEvent.java
@@ -54,7 +54,8 @@ package org.jboss.netty.channel;
  * ({@link ChannelUpstreamHandler} for upstream events and
  *  {@link ChannelDownstreamHandler} for downstream events) to find out how
  * a {@link ChannelEvent} is interpreted depending on the type of the handler
- * more in detail.
+ * more in detail.  Also, please refer to the {@link ChannelPipeline}
+ * documentation to find out how an event flows in a pipeline.
  *
  * @author The Netty Project (netty-dev@lists.jboss.org)
  * @author Trustin Lee (tlee@redhat.com)
diff --git a/src/main/java/org/jboss/netty/channel/ChannelFactory.java b/src/main/java/org/jboss/netty/channel/ChannelFactory.java
index dc8c2238c2..eee3e4445e 100644
--- a/src/main/java/org/jboss/netty/channel/ChannelFactory.java
+++ b/src/main/java/org/jboss/netty/channel/ChannelFactory.java
@@ -24,6 +24,7 @@ package org.jboss.netty.channel;
 
 import java.util.concurrent.Executor;
 
+import org.jboss.netty.channel.group.ChannelGroup;
 import org.jboss.netty.channel.socket.nio.NioServerSocketChannelFactory;
 import org.jboss.netty.util.ExternalResourceReleasable;
 
@@ -44,12 +45,14 @@ import org.jboss.netty.util.ExternalResourceReleasable;
  * To shut down a network application service which is managed by a factory.
  * you should follow the following steps:
  * <ol>
- * <li>close all channels created by the factory and their child channels, and</li>
+ * <li>close all channels created by the factory and their child channels
+ *     usually using {@link ChannelGroup#close()}, and</li>
  * <li>call {@link #releaseExternalResources()}.</li>
  * </ol>
  * <p>
  * For detailed transport-specific information on shutting down a factory,
- * please refer to the Javadoc of {@link ChannelFactory}'s subtypes.
+ * please refer to the Javadoc of {@link ChannelFactory}'s subtypes, such as
+ * {@link NioServerSocketChannelFactory}.
  *
  * @author The Netty Project (netty-dev@lists.jboss.org)
  * @author Trustin Lee (tlee@redhat.com)
@@ -58,6 +61,8 @@ import org.jboss.netty.util.ExternalResourceReleasable;
  *
  * @apiviz.landmark
  * @apiviz.has        org.jboss.netty.channel.Channel oneway - - creates
+ *
+ * @apiviz.exclude ^org\.jboss\.netty\.channel\.([a-z]+\.)+.*ChannelFactory$
  */
 public interface ChannelFactory extends ExternalResourceReleasable {
 
diff --git a/src/main/java/org/jboss/netty/channel/ChannelPipeline.java b/src/main/java/org/jboss/netty/channel/ChannelPipeline.java
index 6f0733b018..109f47655c 100644
--- a/src/main/java/org/jboss/netty/channel/ChannelPipeline.java
+++ b/src/main/java/org/jboss/netty/channel/ChannelPipeline.java
@@ -112,9 +112,9 @@ import org.jboss.netty.handler.ssl.SslHandler;
  * p.addLast("4", new DownstreamHandlerB());
  * p.addLast("5", new UpstreamHandlerX());
  * </pre>
- * The class whose name starts with {@code Upstream} means it is an upstream
- * handler.  The class whose name starts with {@code Downstream} means it is a
- * downstream handler.
+ * In the example above, the class whose name starts with {@code Upstream} means
+ * it is an upstream handler.  The class whose name starts with
+ * {@code Downstream} means it is a downstream handler.
  * <p>
  * In the given example configuration, the handler evaluation order is 1, 2, 3,
  * 4, 5 when an event goes upstream.  When an event goes downstream, the order
diff --git a/src/main/java/org/jboss/netty/channel/ChannelUpstreamHandler.java b/src/main/java/org/jboss/netty/channel/ChannelUpstreamHandler.java
index e71f9476aa..ffb54b4757 100644
--- a/src/main/java/org/jboss/netty/channel/ChannelUpstreamHandler.java
+++ b/src/main/java/org/jboss/netty/channel/ChannelUpstreamHandler.java
@@ -122,9 +122,9 @@ import org.jboss.netty.handler.execution.OrderedMemoryAwareThreadPoolExecutor;
  * <p>
  * You might want to refer to {@link ChannelDownstreamHandler} to see how a
  * {@link ChannelEvent} is interpreted when going downstream.  Also, please
- * refer to the {@link ChannelEvent} documentation to find out what an upstream
- * event and a downstream event are and what fundamental differences they have,
- * if you didn't read yet.
+ * refer to the {@link ChannelEvent} and {@link ChannelPipeline} documentation
+ * to find out what an upstream event and a downstream event are, what
+ * fundamental differences they have, and how they flow in a pipeline.
  *
  * <h3>{@link SimpleChannelHandler}</h3>
  * <p>
@@ -138,8 +138,8 @@ import org.jboss.netty.handler.execution.OrderedMemoryAwareThreadPoolExecutor;
  * <p>
  * You can forward the received event upstream or downstream.  In most cases,
  * {@link ChannelUpstreamHandler} will sent the event to the next handler
- * (upstream) although it is absolutely normal to sent the event to the
- * previous handler (downstream):
+ * (upstream) although it is legal to sent the event to the previous handler
+ * (downstream):
  *
  * <pre>
  * // Sending the event forward (upstream)
@@ -200,6 +200,8 @@ import org.jboss.netty.handler.execution.OrderedMemoryAwareThreadPoolExecutor;
  * @author Trustin Lee (tlee@redhat.com)
  *
  * @version $Rev$, $Date$
+ *
+ * @apiviz.exclude ^org\.jboss\.netty\.handler\..*$
  */
 public interface ChannelUpstreamHandler extends ChannelHandler {
 
diff --git a/src/main/java/org/jboss/netty/channel/socket/nio/NioClientSocketChannelFactory.java b/src/main/java/org/jboss/netty/channel/socket/nio/NioClientSocketChannelFactory.java
index a499f8580e..97dcfe0ced 100644
--- a/src/main/java/org/jboss/netty/channel/socket/nio/NioClientSocketChannelFactory.java
+++ b/src/main/java/org/jboss/netty/channel/socket/nio/NioClientSocketChannelFactory.java
@@ -29,6 +29,7 @@ import java.util.concurrent.RejectedExecutionException;
 
 import org.jboss.netty.channel.Channel;
 import org.jboss.netty.channel.ChannelPipeline;
+import org.jboss.netty.channel.group.ChannelGroup;
 import org.jboss.netty.channel.socket.ClientSocketChannelFactory;
 import org.jboss.netty.channel.socket.SocketChannel;
 import org.jboss.netty.util.internal.ExecutorUtil;
@@ -73,7 +74,8 @@ import org.jboss.netty.util.internal.ExecutorUtil;
  * following:
  *
  * <ol>
- * <li>close all channels created by the factory, and</li>
+ * <li>close all channels created by the factory usually using
+ *     {@link ChannelGroup#close()}, and</li>
  * <li>call {@link #releaseExternalResources()}.</li>
  * </ol>
  *
diff --git a/src/main/java/org/jboss/netty/channel/socket/nio/NioServerSocketChannelFactory.java b/src/main/java/org/jboss/netty/channel/socket/nio/NioServerSocketChannelFactory.java
index b21da0e2b9..c6e6caa5e6 100644
--- a/src/main/java/org/jboss/netty/channel/socket/nio/NioServerSocketChannelFactory.java
+++ b/src/main/java/org/jboss/netty/channel/socket/nio/NioServerSocketChannelFactory.java
@@ -30,6 +30,7 @@ import java.util.concurrent.RejectedExecutionException;
 import org.jboss.netty.channel.Channel;
 import org.jboss.netty.channel.ChannelPipeline;
 import org.jboss.netty.channel.ChannelSink;
+import org.jboss.netty.channel.group.ChannelGroup;
 import org.jboss.netty.channel.socket.ServerSocketChannel;
 import org.jboss.netty.channel.socket.ServerSocketChannelFactory;
 import org.jboss.netty.util.internal.ExecutorUtil;
@@ -77,7 +78,8 @@ import org.jboss.netty.util.internal.ExecutorUtil;
  *
  * <ol>
  * <li>unbind all channels created by the factory,
- * <li>close all child channels accepted by the unbound channels, and</li>
+ * <li>close all child channels accepted by the unbound channels, and
+ *     (these two steps so far is usually done using {@link ChannelGroup#close()})</li>
  * <li>call {@link #releaseExternalResources()}.</li>
  * </ol>
  *
diff --git a/src/main/java/org/jboss/netty/channel/socket/oio/OioClientSocketChannelFactory.java b/src/main/java/org/jboss/netty/channel/socket/oio/OioClientSocketChannelFactory.java
index e95b81a9b7..05d63072d4 100644
--- a/src/main/java/org/jboss/netty/channel/socket/oio/OioClientSocketChannelFactory.java
+++ b/src/main/java/org/jboss/netty/channel/socket/oio/OioClientSocketChannelFactory.java
@@ -27,6 +27,7 @@ import java.util.concurrent.RejectedExecutionException;
 
 import org.jboss.netty.channel.Channel;
 import org.jboss.netty.channel.ChannelPipeline;
+import org.jboss.netty.channel.group.ChannelGroup;
 import org.jboss.netty.channel.socket.ClientSocketChannelFactory;
 import org.jboss.netty.channel.socket.SocketChannel;
 import org.jboss.netty.util.internal.ExecutorUtil;
@@ -60,7 +61,8 @@ import org.jboss.netty.util.internal.ExecutorUtil;
  * you should do the following:
  *
  * <ol>
- * <li>close all channels created by the factory, and</li>
+ * <li>close all channels created by the factory usually using
+ *     {@link ChannelGroup#close()}, and</li>
  * <li>call {@link #releaseExternalResources()}.</li>
  * </ol>
  *
diff --git a/src/main/java/org/jboss/netty/channel/socket/oio/OioDatagramChannelFactory.java b/src/main/java/org/jboss/netty/channel/socket/oio/OioDatagramChannelFactory.java
index 81de9efeaf..eeacac68a1 100644
--- a/src/main/java/org/jboss/netty/channel/socket/oio/OioDatagramChannelFactory.java
+++ b/src/main/java/org/jboss/netty/channel/socket/oio/OioDatagramChannelFactory.java
@@ -27,6 +27,7 @@ import java.util.concurrent.RejectedExecutionException;
 
 import org.jboss.netty.channel.Channel;
 import org.jboss.netty.channel.ChannelPipeline;
+import org.jboss.netty.channel.group.ChannelGroup;
 import org.jboss.netty.channel.socket.DatagramChannel;
 import org.jboss.netty.channel.socket.DatagramChannelFactory;
 import org.jboss.netty.util.internal.ExecutorUtil;
@@ -59,7 +60,8 @@ import org.jboss.netty.util.internal.ExecutorUtil;
  * you should do the following:
  *
  * <ol>
- * <li>close all channels created by the factory, and</li>
+ * <li>close all channels created by the factory usually using
+ *     {@link ChannelGroup#close()}, and</li>
  * <li>call {@link #releaseExternalResources()}.</li>
  * </ol>
  *
diff --git a/src/main/java/org/jboss/netty/channel/socket/oio/OioServerSocketChannelFactory.java b/src/main/java/org/jboss/netty/channel/socket/oio/OioServerSocketChannelFactory.java
index 1144e24061..d2a58452d4 100644
--- a/src/main/java/org/jboss/netty/channel/socket/oio/OioServerSocketChannelFactory.java
+++ b/src/main/java/org/jboss/netty/channel/socket/oio/OioServerSocketChannelFactory.java
@@ -23,13 +23,12 @@
 package org.jboss.netty.channel.socket.oio;
 
 import java.util.concurrent.Executor;
-import java.util.concurrent.ExecutorService;
 import java.util.concurrent.RejectedExecutionException;
-import java.util.concurrent.TimeUnit;
 
 import org.jboss.netty.channel.Channel;
 import org.jboss.netty.channel.ChannelPipeline;
 import org.jboss.netty.channel.ChannelSink;
+import org.jboss.netty.channel.group.ChannelGroup;
 import org.jboss.netty.channel.socket.ServerSocketChannel;
 import org.jboss.netty.channel.socket.ServerSocketChannelFactory;
 import org.jboss.netty.util.internal.ExecutorUtil;
@@ -74,11 +73,9 @@ import org.jboss.netty.util.internal.ExecutorUtil;
  *
  * <ol>
  * <li>unbind all channels created by the factory,
- * <li>close all child channels accepted by the unbound channels,</li>
- * <li>call {@link ExecutorService#shutdownNow()} for all executors which were
- *     specified to create the factory, and</li>
- * <li>call {@link ExecutorService#awaitTermination(long, TimeUnit)}
- *     until it returns {@code true}.</li>
+ * <li>close all child channels accepted by the unbound channels,
+ *     (these two steps so far is usually done using {@link ChannelGroup#close()})</li>
+ * <li>call {@link #releaseExternalResources()}.</li>
  * </ol>
  *
  * Please make sure not to shut down the executor until all channels are