Comment clean up as advised
This commit is contained in:
Trustin Lee
parent
09ef8e8964
commit
7123581038
@ -44,7 +44,7 @@ import org.jboss.netty.channel.ExceptionEvent;
|
||||
import org.jboss.netty.channel.SimpleChannelHandler;
|
||||
|
||||
/**
|
||||
* A helper class which creates a new client-side {@link Channel} and make a
|
||||
* A helper class which creates a new client-side {@link Channel} and makes a
|
||||
* connection attempt.
|
||||
*
|
||||
* <h3>Configuring a channel</h3>
|
||||
@ -83,7 +83,7 @@ import org.jboss.netty.channel.SimpleChannelHandler;
|
||||
*
|
||||
* {@linkplain #setPipelineFactory(ChannelPipelineFactory) The second approach}
|
||||
* is to specify a {@link ChannelPipelineFactory} by yourself and have full
|
||||
* control over how a new pipeline is created, at the cost of more complexity:
|
||||
* control over how a new pipeline is created. This approach is more complex:
|
||||
*
|
||||
* <pre>
|
||||
* ClientBootstrap b = ...;
|
||||
|
||||
@ -117,7 +117,7 @@ import org.jboss.netty.channel.SimpleChannelHandler;
|
||||
*
|
||||
* {@linkplain #setPipelineFactory(ChannelPipelineFactory) The second approach}
|
||||
* is to specify a {@link ChannelPipelineFactory} by yourself and have full
|
||||
* control over how a new pipeline is created, at the cost of more complexity:
|
||||
* control over how a new pipeline is created. This approach is more complex:
|
||||
*
|
||||
* <pre>
|
||||
* ServerBootstrap b = ...;
|
||||
|
||||
@ -86,7 +86,7 @@ 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 a upstream event
|
||||
* 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.
|
||||
*
|
||||
|
||||
@ -32,17 +32,17 @@ package org.jboss.netty.channel;
|
||||
*
|
||||
* <h3>Upstream events and downstream events, and their interpretation</h3>
|
||||
* <p>
|
||||
* Every event can be either a upstream event or a downstream event.
|
||||
* Every event can be either an upstream event or a downstream event.
|
||||
* If an event flows from the first handler to the last handler in a
|
||||
* {@link ChannelPipeline}, we call it a upstream event and say <strong>"an
|
||||
* {@link ChannelPipeline}, we call it an upstream event and say <strong>"an
|
||||
* event goes upstream."</strong> If an event flows from the last handler to
|
||||
* the first handler in a {@link ChannelPipeline}, we call it a downstream
|
||||
* event and say <strong>"an event goes downstream."</strong> (Please refer
|
||||
* to the diagram in {@link ChannelPipeline} for more explanation.)
|
||||
* <p>
|
||||
* A {@link ChannelEvent} is interpreted differently by a {@link ChannelHandler}
|
||||
* depending on whether the event is a upstream event or a downstream event.
|
||||
* A upstream event represents the notification of what happened in the past.
|
||||
* depending on whether the event is an upstream event or a downstream event.
|
||||
* An upstream event represents the notification of what happened in the past.
|
||||
* By contrast, a downstream event represents the request of what should happen
|
||||
* in the future. For example, a {@link MessageEvent} represents the
|
||||
* notification of a received message when it goes upstream, while it
|
||||
@ -73,7 +73,7 @@ public interface ChannelEvent {
|
||||
|
||||
/**
|
||||
* Returns the {@link ChannelFuture} which is associated with this event.
|
||||
* If this event is a upstream event, this method will always return a
|
||||
* If this event is an upstream event, this method will always return a
|
||||
* {@link SucceededChannelFuture} because the event has occurred already.
|
||||
* If this event is a downstream event (i.e. I/O request), the returned
|
||||
* future will be notified when the I/O request succeeds or fails.
|
||||
|
||||
@ -29,16 +29,15 @@ package org.jboss.netty.channel;
|
||||
*
|
||||
* <h3>Sub-types</h3>
|
||||
* <p>
|
||||
* 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:
|
||||
* This is a tag interface. There are two sub-interfaces which process a
|
||||
* received event, one for upstream events and the other for downstream events:
|
||||
* <ul>
|
||||
* <li>{@link ChannelUpstreamHandler} handles and intercepts a upstream {@link ChannelEvent}.</li>
|
||||
* <li>{@link ChannelUpstreamHandler} handles and intercepts an upstream {@link ChannelEvent}.</li>
|
||||
* <li>{@link ChannelDownstreamHandler} handles and intercepts a downstream {@link ChannelEvent}.</li>
|
||||
* </ul>
|
||||
*
|
||||
* You will also find more detailed explanation from the documentation of
|
||||
* each sub-type about how an event is interpreted when it goes upstream and
|
||||
* each sub-type on how an event is interpreted when it goes upstream and
|
||||
* downstream respectively.
|
||||
*
|
||||
* <h3>The context object</h3>
|
||||
|
||||
@ -26,7 +26,7 @@ package org.jboss.netty.channel;
|
||||
* Provides the properties and operations which are specific to the
|
||||
* {@link ChannelHandler} and the {@link ChannelPipeline} it belongs to.
|
||||
* Via a {@link ChannelHandlerContext}, a {@link ChannelHandler} can send
|
||||
* a upstream or downstream {@link ChannelEvent} to the next or previous
|
||||
* an upstream or downstream {@link ChannelEvent} to the next or previous
|
||||
* {@link ChannelHandler} in the {@link ChannelPipeline}.
|
||||
*
|
||||
* <pre>
|
||||
|
||||
@ -55,7 +55,7 @@ import org.jboss.netty.handler.ssl.SslHandler;
|
||||
* or {@link ChannelHandlerContext#sendDownstream(ChannelEvent)}. The meaning
|
||||
* of the event is interpreted somewhat differently depending on whether it is
|
||||
* going upstream or going downstream. Please refer to {@link ChannelEvent} for
|
||||
* more explanation.
|
||||
* more information.
|
||||
*
|
||||
* <pre>
|
||||
*
|
||||
@ -94,7 +94,7 @@ import org.jboss.netty.handler.ssl.SslHandler;
|
||||
* | I/O Threads (Transport Implementation) |
|
||||
* +------------------------------------------------------------------+
|
||||
* </pre>
|
||||
* Please note that a upstream event flows from the first upstream handler
|
||||
* Please note that an upstream event flows from the first upstream handler
|
||||
* to the last upstream handler (i.e. to the next) and a downstream event
|
||||
* flows from the last downstream handler to the first downstream handler
|
||||
* (i.e. to the previous).
|
||||
@ -130,7 +130,7 @@ import org.jboss.netty.handler.ssl.SslHandler;
|
||||
* <p>
|
||||
* A {@link ChannelHandler} can be added or removed at any time because a
|
||||
* {@link ChannelPipeline} is thread safe. For example, you can insert a
|
||||
* {@link SslHandler} when a sensitive information is about to be exchanged,
|
||||
* {@link SslHandler} when sensitive information is about to be exchanged,
|
||||
* and remove it after the exchange.
|
||||
*
|
||||
* @author The Netty Project (netty-dev@lists.jboss.org)
|
||||
|
||||
@ -26,9 +26,9 @@ package org.jboss.netty.channel;
|
||||
/**
|
||||
* A {@link ChannelEvent} which represents the change of the {@link Channel}
|
||||
* state. It can mean the notification of a change or the request for a
|
||||
* change, depending on whether it is a upstream event or a downstream event
|
||||
* change, depending on whether it is an upstream event or a downstream event
|
||||
* respectively. Please refer to the {@link ChannelEvent} documentation to
|
||||
* find out what a upstream event and a downstream event are and what
|
||||
* find out what an upstream event and a downstream event are and what
|
||||
* fundamental differences they have.
|
||||
*
|
||||
* @author The Netty Project (netty-dev@lists.jboss.org)
|
||||
|
||||
@ -38,7 +38,7 @@ import org.jboss.netty.handler.execution.OrderedMemoryAwareThreadPoolExecutor;
|
||||
*
|
||||
* <h3>Upstream events</h3>
|
||||
* <p>
|
||||
* A upstream event is an event which is supposed to be processed from the
|
||||
* An 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 initiated by an I/O thread are upstream events, and
|
||||
* they have the following meaning:
|
||||
@ -117,14 +117,14 @@ 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 a upstream
|
||||
* 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.
|
||||
*
|
||||
* <h3>{@link SimpleChannelHandler}</h3>
|
||||
* <p>
|
||||
* In most cases, you will get to use a {@link SimpleChannelHandler} to
|
||||
* implement a upstream handler because it provides an individual handler
|
||||
* implement an upstream handler because it provides an individual handler
|
||||
* method for each event type. You might want to implement this interface
|
||||
* directly though if you want to handle various types of events in more
|
||||
* generic way.
|
||||
|
||||
@ -25,7 +25,7 @@ package org.jboss.netty.channel;
|
||||
/**
|
||||
* A {@link ChannelEvent} which represents the notification of the state of
|
||||
* a child {@link Channel}. This event is for going upstream only. Please
|
||||
* refer to the {@link ChannelEvent} documentation to find out what a upstream
|
||||
* refer to the {@link ChannelEvent} documentation to find out what an upstream
|
||||
* event and a downstream event are and what fundamental differences they have.
|
||||
*
|
||||
* @author The Netty Project (netty-dev@lists.jboss.org)
|
||||
|
||||
@ -26,7 +26,7 @@ package org.jboss.netty.channel;
|
||||
* A {@link ChannelEvent} which represents the notification of an exception
|
||||
* raised by a {@link ChannelHandler} or an I/O thread. This event is for
|
||||
* going upstream only. Please refer to the {@link ChannelEvent} documentation
|
||||
* to find out what a upstream event and a downstream event are and what
|
||||
* to find out what an upstream event and a downstream event are and what
|
||||
* fundamental differences they have.
|
||||
*
|
||||
* @author The Netty Project (netty-dev@lists.jboss.org)
|
||||
|
||||
@ -27,9 +27,9 @@ import java.net.SocketAddress;
|
||||
/**
|
||||
* A {@link ChannelEvent} which represents the transmission or reception of a
|
||||
* message. It can mean the notification of a received message or the request
|
||||
* for writing a message, depending on whether it is a upstream event or a
|
||||
* for writing a message, depending on whether it is an upstream event or a
|
||||
* downstream event respectively. Please refer to the {@link ChannelEvent}
|
||||
* documentation to find out what a upstream event and a downstream event are
|
||||
* documentation to find out what an upstream event and a downstream event are
|
||||
* and what fundamental differences they have.
|
||||
*
|
||||
* @author The Netty Project (netty-dev@lists.jboss.org)
|
||||
|
||||
@ -62,7 +62,7 @@ import org.jboss.netty.channel.socket.SocketChannel;
|
||||
* <h3>Life cycle of threads and graceful shutdown</h3>
|
||||
* <p>
|
||||
* All threads are acquired from the {@link Executor}s which were specified
|
||||
* when a {@link NioClientSocketChannelFactory} is created. A boss thread is
|
||||
* when a {@link NioClientSocketChannelFactory} was created. A boss thread is
|
||||
* acquired from the {@code bossExecutor}, and worker threads are acquired from
|
||||
* the {@code workerExecutor}. Therefore, you should make sure the specified
|
||||
* {@link Executor}s are able to lend the sufficient number of threads.
|
||||
|
||||
@ -64,7 +64,7 @@ import org.jboss.netty.channel.socket.ServerSocketChannelFactory;
|
||||
* <h3>Life cycle of threads and graceful shutdown</h3>
|
||||
* <p>
|
||||
* All threads are acquired from the {@link Executor}s which were specified
|
||||
* when a {@link NioServerSocketChannelFactory} is created. Boss threads are
|
||||
* when a {@link NioServerSocketChannelFactory} was created. Boss threads are
|
||||
* acquired from the {@code bossExecutor}, and worker threads are acquired from
|
||||
* the {@code workerExecutor}. Therefore, you should make sure the specified
|
||||
* {@link Executor}s are able to lend the sufficient number of threads.
|
||||
|
||||
@ -62,7 +62,7 @@ public interface NioSocketChannelConfig extends SocketChannelConfig {
|
||||
/**
|
||||
* Returns the maximum loop count for a write operation until
|
||||
* {@link WritableByteChannel#write(ByteBuffer)} returns a non-zero value.
|
||||
* It is similar to what a spin lock is for in concurrency programming.
|
||||
* It is similar to what a spin lock is used for in concurrency programming.
|
||||
* It improves memory utilization and write throughput depending on
|
||||
* the platform that JVM runs on. The default value is {@code 16}.
|
||||
*/
|
||||
@ -71,7 +71,7 @@ public interface NioSocketChannelConfig extends SocketChannelConfig {
|
||||
/**
|
||||
* Sets the maximum loop count for a write operation until
|
||||
* {@link WritableByteChannel#write(ByteBuffer)} returns a non-zero value.
|
||||
* It is similar to what a spin lock is for in concurrency programming.
|
||||
* It is similar to what a spin lock is used for in concurrency programming.
|
||||
* It improves memory utilization and write throughput depending on
|
||||
* the platform that JVM runs on. The default value is {@code 16}.
|
||||
*
|
||||
|
||||
@ -51,7 +51,7 @@ import org.jboss.netty.channel.socket.SocketChannel;
|
||||
* <h3>Life cycle of threads and graceful shutdown</h3>
|
||||
* <p>
|
||||
* Worker threads are acquired from the {@link Executor} which was specified
|
||||
* when a {@link OioClientSocketChannelFactory} is created (i.e. {@code workerExecutor}.)
|
||||
* when a {@link OioClientSocketChannelFactory} was created (i.e. {@code workerExecutor}.)
|
||||
* Therefore, you should make sure the specified {@link Executor} is able to
|
||||
* lend the sufficient number of threads.
|
||||
* <p>
|
||||
|
||||
@ -61,7 +61,7 @@ import org.jboss.netty.channel.socket.ServerSocketChannelFactory;
|
||||
* <h3>Life cycle of threads and graceful shutdown</h3>
|
||||
* <p>
|
||||
* All threads are acquired from the {@link Executor}s which were specified
|
||||
* when a {@link OioServerSocketChannelFactory} is created. Boss threads are
|
||||
* when a {@link OioServerSocketChannelFactory} was created. Boss threads are
|
||||
* acquired from the {@code bossExecutor}, and worker threads are acquired from
|
||||
* the {@code workerExecutor}. Therefore, you should make sure the specified
|
||||
* {@link Executor}s are able to lend the sufficient number of threads.
|
||||
|
||||
@ -31,7 +31,7 @@ import org.jboss.netty.channel.ChannelPipelineCoverage;
|
||||
import org.jboss.netty.channel.ChannelUpstreamHandler;
|
||||
|
||||
/**
|
||||
* Forwards a upstream {@link ChannelEvent} to an {@link Executor}.
|
||||
* Forwards an upstream {@link ChannelEvent} to an {@link Executor}.
|
||||
* <p>
|
||||
* You can implement various thread model by adding this handler to a
|
||||
* {@link ChannelPipeline}. The most common use case of this handler is to
|
||||
|
||||
Loading…
Reference in New Issue
Block a user