Javadoc

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
+ * to the {@link ChannelEvent} and {@link ChannelPipeline} documentation to find
- * and a downstream event are and what fundamental differences they have, if
+ * out what an upstream event and a downstream event are, what fundamental
- * you didn't read yet.
+ * 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
+ * handler (downstream) although it is legal to pass the event to the next
- * to the next handler (upstream):
+ * 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 {
 

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)

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 {
 

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
+ * In the example above, the class whose name starts with {@code Upstream} means
- * handler.  The class whose name starts with {@code Downstream} means it is a
+ * it is an upstream handler.  The class whose name starts with
- * downstream handler.
+ * {@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

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
+ * refer to the {@link ChannelEvent} and {@link ChannelPipeline} documentation
- * event and a downstream event are and what fundamental differences they have,
+ * to find out what an upstream event and a downstream event are, what
- * if you didn't read yet.
+ * 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
+ * (upstream) although it is legal to sent the event to the previous handler
- * previous handler (downstream):
+ * (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 {
 

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>
  *

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>
  *

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>
  *

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>
  *

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>close all child channels accepted by the unbound channels,
- * <li>call {@link ExecutorService#shutdownNow()} for all executors which were
+ *     (these two steps so far is usually done using {@link ChannelGroup#close()})</li>
- *     specified to create the factory, and</li>
+ * <li>call {@link #releaseExternalResources()}.</li>
- * <li>call {@link ExecutorService#awaitTermination(long, TimeUnit)}
- *     until it returns {@code true}.</li>
  * </ol>
  *
  * Please make sure not to shut down the executor until all channels are