From c05a337d7475e4a66da6563ebb339addc5a10356 Mon Sep 17 00:00:00 2001 From: Trustin Lee Date: Tue, 2 Sep 2008 14:12:56 +0000 Subject: [PATCH] Added some links into the example code --- .../netty/bootstrap/ClientBootstrap.java | 7 ++--- .../netty/bootstrap/ServerBootstrap.java | 7 ++--- .../channel/ChannelDownstreamHandler.java | 22 +++++++++++----- .../org/jboss/netty/channel/ChannelEvent.java | 2 ++ .../jboss/netty/channel/ChannelHandler.java | 17 ++++++++---- .../jboss/netty/channel/ChannelPipeline.java | 13 ++++++++++ .../netty/channel/ChannelUpstreamHandler.java | 26 ++++++++++++------- .../netty/channel/SimpleChannelHandler.java | 3 +-- .../netty/logging/InternalLoggerFactory.java | 2 +- 9 files changed, 69 insertions(+), 30 deletions(-) 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}. + * + *

Downstream events

*

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

Additional resources worth reading

+ *

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

Firing an event to the previous or next handler

*

@@ -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(...));
  *     ...
  * }
  * 
+ * + *

Using the helper class to fire an event

*

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

Additional resources worth reading

*

* 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}. + * + *

Sub-types

*

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

+ * + *

The context object

*

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

Additional resources worth reading

+ *

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

Building a pipeline

*

* 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());
+ * 
+ * *

Thread safety

*

* 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}. + * + *

Upstream events

*

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

* * * @@ -94,7 +96,7 @@ import org.jboss.netty.handler.execution.OrderedMemoryAwareThreadPoolExecutor; *

* These two additional event types are used only for a parent channel which * can have a child channel (e.g. {@link ServerSocketChannel}). - * + *

*

Event nameEvent type and conditionMeaning
* * @@ -110,12 +112,16 @@ import org.jboss.netty.handler.execution.OrderedMemoryAwareThreadPoolExecutor; * * *
Event nameEvent type and conditionMeaninga child {@link Channel} was closed (e.g. the accepted connection was closed.)
+ * + *

Additional resources worth reading

*

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

{@link SimpleChannelHandler}

*

* 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(...));
  *     ...
  * }
  * 
+ * + *

Using the helper class to fire an event

*

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