diff --git a/src/main/java/org/jboss/netty/bootstrap/ClientBootstrap.java b/src/main/java/org/jboss/netty/bootstrap/ClientBootstrap.java index f5e73a611e..959557cf97 100644 --- a/src/main/java/org/jboss/netty/bootstrap/ClientBootstrap.java +++ b/src/main/java/org/jboss/netty/bootstrap/ClientBootstrap.java @@ -24,6 +24,7 @@ package org.jboss.netty.bootstrap; import static org.jboss.netty.channel.Channels.*; +import java.net.InetSocketAddress; import java.net.SocketAddress; import java.util.concurrent.BlockingQueue; import java.util.concurrent.LinkedBlockingQueue; @@ -53,7 +54,7 @@ import org.jboss.netty.channel.SimpleChannelHandler; * ClientBootstrap b = ...; * * // Options for a new channel - * b.setOption("remoteAddress", new InetSocketAddress("example.com", 8080)); + * b.setOption("remoteAddress", new {@link InetSocketAddress}("example.com", 8080)); * b.setOption("tcpNoDelay", true); * b.setOption("receiveBufferSize", 1048576); * @@ -68,7 +69,7 @@ import org.jboss.netty.channel.SimpleChannelHandler; * *
* ClientBootstrap b = ...; - * ChannelPipeline p = b.getPipeline(); + * {@link ChannelPipeline} p = b.getPipeline(); * * // Add handlers to the pipeline. * p.addLast("encoder", new EncodingHandler()); @@ -84,7 +85,7 @@ import org.jboss.netty.channel.SimpleChannelHandler; * ClientBootstrap b = ...; * b.setPipelineFactory(new MyPipelineFactory()); * - * public class MyPipelineFactory implements ChannelPipelineFactory { + * public class MyPipelineFactory implements {@link ChannelPipelineFactory} { * // Create a new pipeline for a new channel and configure it here ... * } *diff --git a/src/main/java/org/jboss/netty/bootstrap/ServerBootstrap.java b/src/main/java/org/jboss/netty/bootstrap/ServerBootstrap.java index 97492e9122..10bbea5692 100644 --- a/src/main/java/org/jboss/netty/bootstrap/ServerBootstrap.java +++ b/src/main/java/org/jboss/netty/bootstrap/ServerBootstrap.java @@ -24,6 +24,7 @@ package org.jboss.netty.bootstrap; import static org.jboss.netty.channel.Channels.*; +import java.net.InetSocketAddress; import java.net.SocketAddress; import java.util.HashMap; import java.util.Map; @@ -71,7 +72,7 @@ import org.jboss.netty.channel.SimpleChannelHandler; * ServerBootstrap b = ...; * * // Options for a parent channel - * b.setOption("localAddress", new InetSocketAddress(8080)); + * b.setOption("localAddress", new {@link InetSocketAddress}(8080)); * b.setOption("reuseAddress", true); * * // Options for its children @@ -102,7 +103,7 @@ import org.jboss.netty.channel.SimpleChannelHandler; * *
* ServerBootstrap b = ...; - * ChannelPipeline p = b.getPipeline(); + * {@link ChannelPipeline} p = b.getPipeline(); * * // Add handlers to the pipeline. * p.addLast("encoder", new EncodingHandler()); @@ -118,7 +119,7 @@ import org.jboss.netty.channel.SimpleChannelHandler; * ServerBootstrap b = ...; * b.setPipelineFactory(new MyPipelineFactory()); * - * public class MyPipelineFactory implements ChannelPipelineFactory { + * public class MyPipelineFactory implements {@link ChannelPipelineFactory} { * // Create a new pipeline for a new child channel and configure it here ... * } *diff --git a/src/main/java/org/jboss/netty/channel/ChannelDownstreamHandler.java b/src/main/java/org/jboss/netty/channel/ChannelDownstreamHandler.java index fc08b76f95..2dd5a6e538 100644 --- a/src/main/java/org/jboss/netty/channel/ChannelDownstreamHandler.java +++ b/src/main/java/org/jboss/netty/channel/ChannelDownstreamHandler.java @@ -29,6 +29,8 @@ import java.net.SocketAddress; * Handles or intercepts a downstream {@link ChannelEvent}, and fires a * {@link ChannelEvent} to the previous or next handler in a * {@link ChannelPipeline}. + * + *
* A downstream event is an event which is supposed to be processed from the * last handler to the first handler in the {@link ChannelPipeline}. @@ -70,11 +72,15 @@ import java.net.SocketAddress; * *
* Other event types and conditions which were not addressed here will be - * ignored and discarded. You also 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 a - * upstream event and a downstream event are and what fundamental differences - * they have, if you didn't read yet. + * ignored and discarded. + * + *
+ * 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 a upstream event + * and a downstream event are and what fundamental differences they have, if + * you didn't read yet. * *
@@ -85,19 +91,21 @@ import java.net.SocketAddress; * *
* // Sending the event forward (downstream) - * void handleDownstream(ChannelHandlerContext ctx, ChannelEvent e) throws Exception { + * void handleDownstream({@link ChannelHandlerContext} ctx, {@link ChannelEvent} e) throws Exception { * ... * ctx.sendDownstream(e); * ... * } * * // Sending the event backward (upstream) - * void handleDownstream(ChannelHandlerContext ctx, ChannelEvent e) throws Exception { + * void handleDownstream({@link ChannelHandlerContext} ctx, {@link ChannelEvent} e) throws Exception { * ... * ctx.sendUpstream(new DefaultChannelStateEvent(...)); * ... * } *+ * + *
* You will also find various helper methods in {@link Channels} to be useful * to generate and fire an artificial or manipulated event. diff --git a/src/main/java/org/jboss/netty/channel/ChannelEvent.java b/src/main/java/org/jboss/netty/channel/ChannelEvent.java index 6c524061c9..faf6aa8ede 100644 --- a/src/main/java/org/jboss/netty/channel/ChannelEvent.java +++ b/src/main/java/org/jboss/netty/channel/ChannelEvent.java @@ -46,6 +46,8 @@ package org.jboss.netty.channel; * in the future. For example, a {@link MessageEvent} represents the * notification of a received message when it goes upstream, while it * represents the request of writing a message when it goes downstream. + * + *
* Please refer to the documentation of {@link ChannelHandler} and its sub-types * ({@link ChannelUpstreamHandler} for upstream events and diff --git a/src/main/java/org/jboss/netty/channel/ChannelHandler.java b/src/main/java/org/jboss/netty/channel/ChannelHandler.java index b8f80762da..ee19bbb288 100644 --- a/src/main/java/org/jboss/netty/channel/ChannelHandler.java +++ b/src/main/java/org/jboss/netty/channel/ChannelHandler.java @@ -26,17 +26,18 @@ package org.jboss.netty.channel; * Handles or intercepts a {@link ChannelEvent}, and fires a * {@link ChannelEvent} to the next or previous handler in a * {@link ChannelPipeline}. + * + *
* This is a tag interface. There are two sub-interfaces which processes * a received event actually, one for upstream events and the other for * downstream events: *
* A {@link ChannelHandler} is provided with a {@link ChannelHandlerContext} * object. The {@link ChannelHandler} is supposed to interact with the @@ -45,6 +46,12 @@ package org.jboss.netty.channel; * or previous handler or modify the behavior of the pipeline by adding or * removing a handler for example. * + *
+ * Please refer to the {@link ChannelEvent} documentation to find out what a + * upstream event and a downstream event are and what fundamental differences + * they have, if you didn't read yet. + * * @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/ChannelPipeline.java b/src/main/java/org/jboss/netty/channel/ChannelPipeline.java index daca62abec..f77fef177f 100644 --- a/src/main/java/org/jboss/netty/channel/ChannelPipeline.java +++ b/src/main/java/org/jboss/netty/channel/ChannelPipeline.java @@ -27,6 +27,7 @@ import java.util.NoSuchElementException; import org.jboss.netty.buffer.ChannelBuffer; import org.jboss.netty.handler.execution.ExecutionHandler; +import org.jboss.netty.handler.execution.OrderedMemoryAwareThreadPoolExecutor; import org.jboss.netty.handler.ssl.SslHandler; @@ -38,6 +39,8 @@ import org.jboss.netty.handler.ssl.SslHandler; * Intercepting * Filter pattern to give a user full control over how an event is handled * and how the {@link ChannelHandler}s in the pipeline interact with each other. + * + *
* A user is supposed to have one or more {@link ChannelHandler}s in a * pipeline to receive I/O events (e.g. read) and to request I/O operations @@ -54,6 +57,16 @@ import org.jboss.netty.handler.ssl.SslHandler; * (e.g. database access). * * + * and it could be represented as shown in the following example: + * + *
+ * ChannelPipeline pipeline = {@link Channels#pipeline() Channels.pipeline()}; + * pipeline.addLast("decoder", new MyProtocolDecoder()); + * pipeline.addLast("encoder", new MyProtocolEncoder()); + * pipeline.addLast("executor", new {@link ExecutionHandler}(new {@link OrderedMemoryAwareThreadPoolExecutor}(16, 1048576, 1048576))); + * pipeline.addLast("handler", new MyBusinessLogicHandler()); + *+ * *
* A {@link ChannelHandler} can be added or removed at any time because a diff --git a/src/main/java/org/jboss/netty/channel/ChannelUpstreamHandler.java b/src/main/java/org/jboss/netty/channel/ChannelUpstreamHandler.java index 862ea735eb..2df047249b 100644 --- a/src/main/java/org/jboss/netty/channel/ChannelUpstreamHandler.java +++ b/src/main/java/org/jboss/netty/channel/ChannelUpstreamHandler.java @@ -35,12 +35,14 @@ import org.jboss.netty.handler.execution.OrderedMemoryAwareThreadPoolExecutor; * Handles or intercepts a upstream {@link ChannelEvent}, and fires a * {@link ChannelEvent} to the next or previous handler in a * {@link ChannelPipeline}. + * + *
* A upstream event is an event which is supposed to be processed from the * first handler to the last handler in the {@link ChannelPipeline}. * For example, all events fired by an I/O thread are upstream events, and * they have the following meaning: - * + *
*
Event name | Event type and condition | Meaning | @@ -94,7 +96,7 @@ import org.jboss.netty.handler.execution.OrderedMemoryAwareThreadPoolExecutor; *
---|
Event name | Event type and condition | Meaning | @@ -110,12 +112,16 @@ import org.jboss.netty.handler.execution.OrderedMemoryAwareThreadPoolExecutor; *a child {@link Channel} was closed (e.g. the accepted connection was closed.) | *
---|
- * You also 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 a - * upstream event and a downstream event are and what fundamental differences - * they have, if you didn't read yet. + * 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 a upstream + * event and a downstream event are and what fundamental differences they have, + * if you didn't read yet. + * + *
* In most cases, you will get to use a {@link SimpleChannelHandler} to * implement a upstream handler because it provides an individual handler @@ -132,19 +138,21 @@ import org.jboss.netty.handler.execution.OrderedMemoryAwareThreadPoolExecutor; * *
* // Sending the event forward (upstream) - * void handleUpstream(ChannelHandlerContext ctx, ChannelEvent e) throws Exception { + * void handleUpstream({@link ChannelHandlerContext} ctx, {@link ChannelEvent} e) throws Exception { * ... * ctx.sendUpstream(e); * ... * } * * // Sending the event backward (downstream) - * void handleDownstream(ChannelHandlerContext ctx, ChannelEvent e) throws Exception { + * void handleDownstream({@link ChannelHandlerContext} ctx, {@link ChannelEvent} e) throws Exception { * ... * ctx.sendDownstream(new MessageEvent(...)); * ... * } *+ * + *
* You will also find various helper methods in {@link Channels} to be useful * to generate and fire an artificial or manipulated event. diff --git a/src/main/java/org/jboss/netty/channel/SimpleChannelHandler.java b/src/main/java/org/jboss/netty/channel/SimpleChannelHandler.java index d89d1ca6b7..e81aabbf43 100644 --- a/src/main/java/org/jboss/netty/channel/SimpleChannelHandler.java +++ b/src/main/java/org/jboss/netty/channel/SimpleChannelHandler.java @@ -44,8 +44,7 @@ import org.jboss.netty.logging.InternalLoggerFactory; *
*public class MyChannelHandler extends SimpleChannelHandler { * - * public void handleUpstream( - * ChannelHandlerContext ctx, ChannelEvent e) throws Exception { + * public void handleUpstream({@link ChannelHandlerContext} ctx, {@link ChannelEvent} e) throws Exception { * * // Log all channel state changes. * if (e instanceof ChannelStateEvent) { diff --git a/src/main/java/org/jboss/netty/logging/InternalLoggerFactory.java b/src/main/java/org/jboss/netty/logging/InternalLoggerFactory.java index bc2b9ccf58..70a6f28443 100644 --- a/src/main/java/org/jboss/netty/logging/InternalLoggerFactory.java +++ b/src/main/java/org/jboss/netty/logging/InternalLoggerFactory.java @@ -31,7 +31,7 @@ import org.jboss.netty.util.StackTraceSimplifier; * You can change it to your preferred logging framework before other Netty * classes are loaded: *- * InternalLoggerFactory.setDefaultFactory(new Log4JLoggerFactory()); + * InternalLoggerFactory.setDefaultFactory(new {@link Log4JLoggerFactory}()); ** Please note that the new default factory is effective only for the classes * which were loaded after the default factory is changed. Therefore,