Comment clean up as advised
This commit is contained in:
parent
09ef8e8964
commit
7123581038
@ -44,7 +44,7 @@ import org.jboss.netty.channel.ExceptionEvent;
|
|||||||
import org.jboss.netty.channel.SimpleChannelHandler;
|
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.
|
* connection attempt.
|
||||||
*
|
*
|
||||||
* <h3>Configuring a channel</h3>
|
* <h3>Configuring a channel</h3>
|
||||||
@ -83,7 +83,7 @@ import org.jboss.netty.channel.SimpleChannelHandler;
|
|||||||
*
|
*
|
||||||
* {@linkplain #setPipelineFactory(ChannelPipelineFactory) The second approach}
|
* {@linkplain #setPipelineFactory(ChannelPipelineFactory) The second approach}
|
||||||
* is to specify a {@link ChannelPipelineFactory} by yourself and have full
|
* 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>
|
* <pre>
|
||||||
* ClientBootstrap b = ...;
|
* ClientBootstrap b = ...;
|
||||||
|
@ -117,7 +117,7 @@ import org.jboss.netty.channel.SimpleChannelHandler;
|
|||||||
*
|
*
|
||||||
* {@linkplain #setPipelineFactory(ChannelPipelineFactory) The second approach}
|
* {@linkplain #setPipelineFactory(ChannelPipelineFactory) The second approach}
|
||||||
* is to specify a {@link ChannelPipelineFactory} by yourself and have full
|
* 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>
|
* <pre>
|
||||||
* ServerBootstrap b = ...;
|
* ServerBootstrap b = ...;
|
||||||
|
@ -86,7 +86,7 @@ import java.net.SocketAddress;
|
|||||||
* <p>
|
* <p>
|
||||||
* You might want to refer to {@link ChannelUpstreamHandler} to see how a
|
* You might want to refer to {@link ChannelUpstreamHandler} to see how a
|
||||||
* {@link ChannelEvent} is interpreted when going upstream. Also, please refer
|
* {@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
|
* and a downstream event are and what fundamental differences they have, if
|
||||||
* you didn't read yet.
|
* you didn't read yet.
|
||||||
*
|
*
|
||||||
|
@ -32,17 +32,17 @@ package org.jboss.netty.channel;
|
|||||||
*
|
*
|
||||||
* <h3>Upstream events and downstream events, and their interpretation</h3>
|
* <h3>Upstream events and downstream events, and their interpretation</h3>
|
||||||
* <p>
|
* <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
|
* 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
|
* 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
|
* the first handler in a {@link ChannelPipeline}, we call it a downstream
|
||||||
* event and say <strong>"an event goes downstream."</strong> (Please refer
|
* event and say <strong>"an event goes downstream."</strong> (Please refer
|
||||||
* to the diagram in {@link ChannelPipeline} for more explanation.)
|
* to the diagram in {@link ChannelPipeline} for more explanation.)
|
||||||
* <p>
|
* <p>
|
||||||
* A {@link ChannelEvent} is interpreted differently by a {@link ChannelHandler}
|
* A {@link ChannelEvent} is interpreted differently by a {@link ChannelHandler}
|
||||||
* depending on whether the event is a upstream event or a downstream event.
|
* depending on whether the event is an upstream event or a downstream event.
|
||||||
* A upstream event represents the notification of what happened in the past.
|
* An upstream event represents the notification of what happened in the past.
|
||||||
* By contrast, a downstream event represents the request of what should happen
|
* By contrast, a downstream event represents the request of what should happen
|
||||||
* in the future. For example, a {@link MessageEvent} represents the
|
* in the future. For example, a {@link MessageEvent} represents the
|
||||||
* notification of a received message when it goes upstream, while it
|
* 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.
|
* 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.
|
* {@link SucceededChannelFuture} because the event has occurred already.
|
||||||
* If this event is a downstream event (i.e. I/O request), the returned
|
* 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.
|
* 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>
|
* <h3>Sub-types</h3>
|
||||||
* <p>
|
* <p>
|
||||||
* This is a tag interface. There are two sub-interfaces which processes
|
* This is a tag interface. There are two sub-interfaces which process a
|
||||||
* a received event actually, one for upstream events and the other for
|
* received event, one for upstream events and the other for downstream events:
|
||||||
* downstream events:
|
|
||||||
* <ul>
|
* <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>
|
* <li>{@link ChannelDownstreamHandler} handles and intercepts a downstream {@link ChannelEvent}.</li>
|
||||||
* </ul>
|
* </ul>
|
||||||
*
|
*
|
||||||
* You will also find more detailed explanation from the documentation of
|
* 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.
|
* downstream respectively.
|
||||||
*
|
*
|
||||||
* <h3>The context object</h3>
|
* <h3>The context object</h3>
|
||||||
|
@ -26,7 +26,7 @@ package org.jboss.netty.channel;
|
|||||||
* Provides the properties and operations which are specific to the
|
* Provides the properties and operations which are specific to the
|
||||||
* {@link ChannelHandler} and the {@link ChannelPipeline} it belongs to.
|
* {@link ChannelHandler} and the {@link ChannelPipeline} it belongs to.
|
||||||
* Via a {@link ChannelHandlerContext}, a {@link ChannelHandler} can send
|
* 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}.
|
* {@link ChannelHandler} in the {@link ChannelPipeline}.
|
||||||
*
|
*
|
||||||
* <pre>
|
* <pre>
|
||||||
|
@ -55,7 +55,7 @@ import org.jboss.netty.handler.ssl.SslHandler;
|
|||||||
* or {@link ChannelHandlerContext#sendDownstream(ChannelEvent)}. The meaning
|
* or {@link ChannelHandlerContext#sendDownstream(ChannelEvent)}. The meaning
|
||||||
* of the event is interpreted somewhat differently depending on whether it is
|
* of the event is interpreted somewhat differently depending on whether it is
|
||||||
* going upstream or going downstream. Please refer to {@link ChannelEvent} for
|
* going upstream or going downstream. Please refer to {@link ChannelEvent} for
|
||||||
* more explanation.
|
* more information.
|
||||||
*
|
*
|
||||||
* <pre>
|
* <pre>
|
||||||
*
|
*
|
||||||
@ -94,7 +94,7 @@ import org.jboss.netty.handler.ssl.SslHandler;
|
|||||||
* | I/O Threads (Transport Implementation) |
|
* | I/O Threads (Transport Implementation) |
|
||||||
* +------------------------------------------------------------------+
|
* +------------------------------------------------------------------+
|
||||||
* </pre>
|
* </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
|
* 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
|
* flows from the last downstream handler to the first downstream handler
|
||||||
* (i.e. to the previous).
|
* (i.e. to the previous).
|
||||||
@ -130,7 +130,7 @@ import org.jboss.netty.handler.ssl.SslHandler;
|
|||||||
* <p>
|
* <p>
|
||||||
* A {@link ChannelHandler} can be added or removed at any time because a
|
* 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 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.
|
* and remove it after the exchange.
|
||||||
*
|
*
|
||||||
* @author The Netty Project (netty-dev@lists.jboss.org)
|
* @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}
|
* 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
|
* 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
|
* 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.
|
* fundamental differences they have.
|
||||||
*
|
*
|
||||||
* @author The Netty Project (netty-dev@lists.jboss.org)
|
* @author The Netty Project (netty-dev@lists.jboss.org)
|
||||||
|
@ -38,7 +38,7 @@ import org.jboss.netty.handler.execution.OrderedMemoryAwareThreadPoolExecutor;
|
|||||||
*
|
*
|
||||||
* <h3>Upstream events</h3>
|
* <h3>Upstream events</h3>
|
||||||
* <p>
|
* <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}.
|
* first handler to the last handler in the {@link ChannelPipeline}.
|
||||||
* For example, all events initiated by an I/O thread are upstream events, and
|
* For example, all events initiated by an I/O thread are upstream events, and
|
||||||
* they have the following meaning:
|
* they have the following meaning:
|
||||||
@ -117,14 +117,14 @@ import org.jboss.netty.handler.execution.OrderedMemoryAwareThreadPoolExecutor;
|
|||||||
* <p>
|
* <p>
|
||||||
* You might want to refer to {@link ChannelDownstreamHandler} to see how a
|
* You might want to refer to {@link ChannelDownstreamHandler} to see how a
|
||||||
* {@link ChannelEvent} is interpreted when going downstream. Also, please
|
* {@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,
|
* event and a downstream event are and what fundamental differences they have,
|
||||||
* if you didn't read yet.
|
* if you didn't read yet.
|
||||||
*
|
*
|
||||||
* <h3>{@link SimpleChannelHandler}</h3>
|
* <h3>{@link SimpleChannelHandler}</h3>
|
||||||
* <p>
|
* <p>
|
||||||
* In most cases, you will get to use a {@link SimpleChannelHandler} to
|
* 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
|
* 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
|
* directly though if you want to handle various types of events in more
|
||||||
* generic way.
|
* generic way.
|
||||||
|
@ -25,7 +25,7 @@ package org.jboss.netty.channel;
|
|||||||
/**
|
/**
|
||||||
* A {@link ChannelEvent} which represents the notification of the state of
|
* A {@link ChannelEvent} which represents the notification of the state of
|
||||||
* a child {@link Channel}. This event is for going upstream only. Please
|
* 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.
|
* event and a downstream event are and what fundamental differences they have.
|
||||||
*
|
*
|
||||||
* @author The Netty Project (netty-dev@lists.jboss.org)
|
* @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
|
* A {@link ChannelEvent} which represents the notification of an exception
|
||||||
* raised by a {@link ChannelHandler} or an I/O thread. This event is for
|
* raised by a {@link ChannelHandler} or an I/O thread. This event is for
|
||||||
* going upstream only. Please refer to the {@link ChannelEvent} documentation
|
* 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.
|
* fundamental differences they have.
|
||||||
*
|
*
|
||||||
* @author The Netty Project (netty-dev@lists.jboss.org)
|
* @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
|
* A {@link ChannelEvent} which represents the transmission or reception of a
|
||||||
* message. It can mean the notification of a received message or the request
|
* 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}
|
* 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.
|
* and what fundamental differences they have.
|
||||||
*
|
*
|
||||||
* @author The Netty Project (netty-dev@lists.jboss.org)
|
* @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>
|
* <h3>Life cycle of threads and graceful shutdown</h3>
|
||||||
* <p>
|
* <p>
|
||||||
* All threads are acquired from the {@link Executor}s which were specified
|
* 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
|
* acquired from the {@code bossExecutor}, and worker threads are acquired from
|
||||||
* the {@code workerExecutor}. Therefore, you should make sure the specified
|
* the {@code workerExecutor}. Therefore, you should make sure the specified
|
||||||
* {@link Executor}s are able to lend the sufficient number of threads.
|
* {@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>
|
* <h3>Life cycle of threads and graceful shutdown</h3>
|
||||||
* <p>
|
* <p>
|
||||||
* All threads are acquired from the {@link Executor}s which were specified
|
* 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
|
* acquired from the {@code bossExecutor}, and worker threads are acquired from
|
||||||
* the {@code workerExecutor}. Therefore, you should make sure the specified
|
* the {@code workerExecutor}. Therefore, you should make sure the specified
|
||||||
* {@link Executor}s are able to lend the sufficient number of threads.
|
* {@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
|
* Returns the maximum loop count for a write operation until
|
||||||
* {@link WritableByteChannel#write(ByteBuffer)} returns a non-zero value.
|
* {@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
|
* It improves memory utilization and write throughput depending on
|
||||||
* the platform that JVM runs on. The default value is {@code 16}.
|
* 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
|
* Sets the maximum loop count for a write operation until
|
||||||
* {@link WritableByteChannel#write(ByteBuffer)} returns a non-zero value.
|
* {@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
|
* It improves memory utilization and write throughput depending on
|
||||||
* the platform that JVM runs on. The default value is {@code 16}.
|
* 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>
|
* <h3>Life cycle of threads and graceful shutdown</h3>
|
||||||
* <p>
|
* <p>
|
||||||
* Worker threads are acquired from the {@link Executor} which was specified
|
* 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
|
* Therefore, you should make sure the specified {@link Executor} is able to
|
||||||
* lend the sufficient number of threads.
|
* lend the sufficient number of threads.
|
||||||
* <p>
|
* <p>
|
||||||
|
@ -61,7 +61,7 @@ import org.jboss.netty.channel.socket.ServerSocketChannelFactory;
|
|||||||
* <h3>Life cycle of threads and graceful shutdown</h3>
|
* <h3>Life cycle of threads and graceful shutdown</h3>
|
||||||
* <p>
|
* <p>
|
||||||
* All threads are acquired from the {@link Executor}s which were specified
|
* 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
|
* acquired from the {@code bossExecutor}, and worker threads are acquired from
|
||||||
* the {@code workerExecutor}. Therefore, you should make sure the specified
|
* the {@code workerExecutor}. Therefore, you should make sure the specified
|
||||||
* {@link Executor}s are able to lend the sufficient number of threads.
|
* {@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;
|
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>
|
* <p>
|
||||||
* You can implement various thread model by adding this handler to a
|
* You can implement various thread model by adding this handler to a
|
||||||
* {@link ChannelPipeline}. The most common use case of this handler is to
|
* {@link ChannelPipeline}. The most common use case of this handler is to
|
||||||
|
Loading…
Reference in New Issue
Block a user