More JavaDoc

This commit is contained in:
Trustin Lee 2008-09-02 12:04:04 +00:00
parent d1be3feefc
commit ed8651701d
5 changed files with 143 additions and 26 deletions

View File

@ -25,12 +25,15 @@ package org.jboss.netty.channel;
import java.io.IOException; import java.io.IOException;
import java.util.Map; import java.util.Map;
import org.jboss.netty.channel.socket.nio.NioSocketChannelConfig;
/** /**
* The configuration properties of a {@link Channel}. * The configuration properties of a {@link Channel}.
* <p> * <p>
* Please down-cast to the transport-specific configuration type or use * Please down-cast to the transport-specific configuration type such as
* {@link #setOptions(Map)} to set the transport-specific properties. * {@link NioSocketChannelConfig} or use {@link #setOptions(Map)} to set the
* transport-specific properties.
* *
* @author The Netty Project (netty-dev@lists.jboss.org) * @author The Netty Project (netty-dev@lists.jboss.org)
* @author Trustin Lee (tlee@redhat.com) * @author Trustin Lee (tlee@redhat.com)
@ -48,25 +51,33 @@ public interface ChannelConfig {
/** /**
* Returns the {@link ChannelPipelineFactory} which will be used when * Returns the {@link ChannelPipelineFactory} which will be used when
* a child channel is created. * a child channel is created. If the {@link Channel} doesn't create
* a child channel, this property is not used at all, and therefore will
* be ignored.
*/ */
ChannelPipelineFactory getPipelineFactory(); ChannelPipelineFactory getPipelineFactory();
/** /**
* Sets the {@link ChannelPipelineFactory} which will be used when * Sets the {@link ChannelPipelineFactory} which will be used when
* a child channel is created. * a child channel is created. If the {@link Channel} doesn't create
* a child channel, this property is not used at all, and therefore will
* be ignored.
*/ */
void setPipelineFactory(ChannelPipelineFactory pipelineFactory); void setPipelineFactory(ChannelPipelineFactory pipelineFactory);
/** /**
* Returns the connect timeout of the channel in milliseconds. * Returns the connect timeout of the channel in milliseconds. If the
* {@link Channel} doesn't support connect operation, this property is not
* used at all, and therefore will be ignored.
* *
* @return the connect timeout in milliseconds. {@code 0} if disabled. * @return the connect timeout in milliseconds. {@code 0} if disabled.
*/ */
int getConnectTimeoutMillis(); int getConnectTimeoutMillis();
/** /**
* Sets the connect timeout of the channel in milliseconds. * Sets the connect timeout of the channel in milliseconds. If the
* {@link Channel} doesn't support connect operation, this property is not
* used at all, and therefore will be ignored.
* *
* @param connectTimeoutMillis the connect timeout in milliseconds. * @param connectTimeoutMillis the connect timeout in milliseconds.
* {@code 0} to disable. * {@code 0} to disable.
@ -76,7 +87,8 @@ public interface ChannelConfig {
/** /**
* Returns the write timeout of the channel in milliseconds. If a write * Returns the write timeout of the channel in milliseconds. If a write
* operation is not done within the write timeout, an {@link IOException} * operation is not done within the write timeout, an {@link IOException}
* will be raised. * will be raised. If the {@link Channel} doesn't support write operation,
* this property is not used at all, and therefore will be ignored.
* *
* @return the write timeout in milliseconds. {@code 0} if disabled. * @return the write timeout in milliseconds. {@code 0} if disabled.
*/ */
@ -85,7 +97,8 @@ public interface ChannelConfig {
/** /**
* Sets the write timeout of the channel in milliseconds. If a write * Sets the write timeout of the channel in milliseconds. If a write
* operation is not done within the write timeout, an {@link IOException} * operation is not done within the write timeout, an {@link IOException}
* will be raised. * will be raised. If the {@link Channel} doesn't support write operation,
* this property is not used at all, and therefore will be ignored.
* *
* @param writeTimeoutMillis the write timeout in milliseconds. * @param writeTimeoutMillis the write timeout in milliseconds.
* {@code 0} to disable. * {@code 0} to disable.

View File

@ -26,14 +26,10 @@ import org.jboss.netty.channel.socket.nio.NioServerSocketChannelFactory;
/** /**
* Creates a new {@link Channel}. * The main interface to a transport that creates a {@link Channel} associated
* <p> * with a certain communication entity such as a network socket. For example,
* {@link ChannelFactory} is the central interface of a transport * the {@link NioServerSocketChannelFactory} creates a channel which has a
* implementation. It creates a {@link Channel} which is associated with a * NIO-based server socket as its underlying communication entity.
* specific communication entity such as a network socket, depending on its
* implementation. For example, the {@link NioServerSocketChannelFactory}
* creates a channel which has a NIO-based server socket as its underlying
* communication entity.
* <p> * <p>
* Once a new {@link Channel} is created, the {@link ChannelPipeline} which * Once a new {@link Channel} is created, the {@link ChannelPipeline} which
* was specified as a parameter in the {@link #newChannel(ChannelPipeline)} * was specified as a parameter in the {@link #newChannel(ChannelPipeline)}

View File

@ -25,9 +25,9 @@ package org.jboss.netty.channel;
import java.util.EventListener; import java.util.EventListener;
/** /**
* Listens to the result of an asynchronous I/O operation. The result of the * Listens to the result of a {@link ChannelFuture}. The result of the
* I/O operation is notified by {@link ChannelFuture} once this listener is * asynchronous {@link Channel} I/O operation is notified once this listener
* added to the future. * is added by calling {@link ChannelFuture#addListener(ChannelFutureListener)}.
* *
* @author The Netty Project (netty-dev@lists.jboss.org) * @author The Netty Project (netty-dev@lists.jboss.org)
* @author Trustin Lee (tlee@redhat.com) * @author Trustin Lee (tlee@redhat.com)

View File

@ -37,6 +37,13 @@ package org.jboss.netty.channel;
* a {@link ChannelEvent} fired by a user via the methods in * a {@link ChannelEvent} fired by a user via the methods in
* the {@link Channel} interface and the {@link Channels} helper class.</li> * the {@link Channel} interface and the {@link Channels} helper class.</li>
* </ul> * </ul>
* <p>
* A {@link ChannelHandler} is provided with a {@link ChannelHandlerContext}
* object. The {@link ChannelHandler} is supposed to interact with the
* {@link ChannelPipeline} it belongs to via the context object. Using the
* context object, the {@link ChannelHandler} can fire events to the next
* or previous handler or modify the behavior of the pipeline by adding or
* removing a handler for example.
* *
* @author The Netty Project (netty-dev@lists.jboss.org) * @author The Netty Project (netty-dev@lists.jboss.org)
* @author Trustin Lee (tlee@redhat.com) * @author Trustin Lee (tlee@redhat.com)

View File

@ -23,6 +23,7 @@
package org.jboss.netty.channel; package org.jboss.netty.channel;
import java.util.Map; import java.util.Map;
import java.util.NoSuchElementException;
import org.jboss.netty.buffer.ChannelBuffer; import org.jboss.netty.buffer.ChannelBuffer;
import org.jboss.netty.handler.execution.ExecutionHandler; import org.jboss.netty.handler.execution.ExecutionHandler;
@ -30,17 +31,13 @@ import org.jboss.netty.handler.ssl.SslHandler;
/** /**
* A list of {@link ChannelHandler}s which handles or intercepts a * A list of {@link ChannelHandler}s which handles or intercepts
* {@link ChannelEvent}. * {@link ChannelEvent}s of a {@link Channel}.
* <p> * <p>
* {@link ChannelPipeline} implements an advanced form of the * {@link ChannelPipeline} implements an advanced form of the
* <a href="http://java.sun.com/blueprints/corej2eepatterns/Patterns/InterceptingFilter.html">Intercepting * <a href="http://java.sun.com/blueprints/corej2eepatterns/Patterns/InterceptingFilter.html">Intercepting
* Filter</a> pattern to give a user full control over how an event is handled * Filter</a> pattern to give a user full control over how an event is handled
* and how {@link ChannelHandler}s in the pipeline interact with each other. * and how the {@link ChannelHandler}s in the pipeline interact with each other.
* <p>
* Every {@link Channel} has its own pipeline instance. Each pipeline is
* created by the {@link ChannelPipelineFactory} specified when a new channel
* is created by the {@link ChannelFactory}.
* <p> * <p>
* A user is supposed to have one or more {@link ChannelHandler}s in a * 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 * pipeline to receive I/O events (e.g. read) and to request I/O operations
@ -131,6 +128,11 @@ public interface ChannelPipeline {
* *
* @param name the name of the handler to insert first * @param name the name of the handler to insert first
* @param handler the handler to insert first * @param handler the handler to insert first
*
* @throws IllegalArgumentException
* if there's an entry with the same name already in the pipeline
* @throws NullPointerException
* if the specified name or handler is {@code null}
*/ */
void addFirst (String name, ChannelHandler handler); void addFirst (String name, ChannelHandler handler);
@ -139,6 +141,11 @@ public interface ChannelPipeline {
* *
* @param name the name of the handler to append * @param name the name of the handler to append
* @param handler the handler to append * @param handler the handler to append
*
* @throws IllegalArgumentException
* if there's an entry with the same name already in the pipeline
* @throws NullPointerException
* if the specified name or handler is {@code null}
*/ */
void addLast (String name, ChannelHandler handler); void addLast (String name, ChannelHandler handler);
@ -149,6 +156,13 @@ public interface ChannelPipeline {
* @param baseName the name of the existing handler * @param baseName the name of the existing handler
* @param name the name of the handler to insert before * @param name the name of the handler to insert before
* @param handler the handler to insert before * @param handler the handler to insert before
*
* @throws NoSuchElementException
* if there's no such entry with the specified {@code baseName}
* @throws IllegalArgumentException
* if there's an entry with the same name already in the pipeline
* @throws NullPointerException
* if the specified baseName, name, or handler is {@code null}
*/ */
void addBefore(String baseName, String name, ChannelHandler handler); void addBefore(String baseName, String name, ChannelHandler handler);
@ -159,11 +173,23 @@ public interface ChannelPipeline {
* @param baseName the name of the existing handler * @param baseName the name of the existing handler
* @param name the name of the handler to insert after * @param name the name of the handler to insert after
* @param handler the handler to insert after * @param handler the handler to insert after
*
* @throws NoSuchElementException
* if there's no such entry with the specified {@code baseName}
* @throws IllegalArgumentException
* if there's an entry with the same name already in the pipeline
* @throws NullPointerException
* if the specified baseName, name, or handler is {@code null}
*/ */
void addAfter (String baseName, String name, ChannelHandler handler); void addAfter (String baseName, String name, ChannelHandler handler);
/** /**
* Removes the specified {@link ChannelHandler} from this pipeline. * Removes the specified {@link ChannelHandler} from this pipeline.
*
* @throws NoSuchElementException
* if there's no such handler in this pipeline
* @throws NullPointerException
* if the specified handler is {@code null}
*/ */
void remove(ChannelHandler handler); void remove(ChannelHandler handler);
@ -172,6 +198,11 @@ public interface ChannelPipeline {
* pipeline. * pipeline.
* *
* @return the removed handler * @return the removed handler
*
* @throws NoSuchElementException
* if there's no such handler with the specified name in this pipeline
* @throws NullPointerException
* if the specified name is {@code null}
*/ */
ChannelHandler remove(String name); ChannelHandler remove(String name);
@ -183,6 +214,11 @@ public interface ChannelPipeline {
* @param handlerType the type of the handler * @param handlerType the type of the handler
* *
* @return the removed handler * @return the removed handler
*
* @throws NoSuchElementException
* if there's no such handler of the specified type in this pipeline
* @throws NullPointerException
* if the specified handler type is {@code null}
*/ */
<T extends ChannelHandler> T remove(Class<T> handlerType); <T extends ChannelHandler> T remove(Class<T> handlerType);
@ -190,6 +226,9 @@ public interface ChannelPipeline {
* Removes the first {@link ChannelHandler} in this pipeline. * Removes the first {@link ChannelHandler} in this pipeline.
* *
* @return the removed handler * @return the removed handler
*
* @throws NoSuchElementException
* if this pipeline is empty
*/ */
ChannelHandler removeFirst(); ChannelHandler removeFirst();
@ -197,12 +236,24 @@ public interface ChannelPipeline {
* Removes the last {@link ChannelHandler} in this pipeline. * Removes the last {@link ChannelHandler} in this pipeline.
* *
* @return the removed handler * @return the removed handler
*
* @throws NoSuchElementException
* if this pipeline is empty
*/ */
ChannelHandler removeLast(); ChannelHandler removeLast();
/** /**
* Replaces the specified {@link ChannelHandler} with a new handler in * Replaces the specified {@link ChannelHandler} with a new handler in
* this pipeline. * this pipeline.
*
* @throws NoSuchElementException
* if the specified old handler doesn't exist in this pipeline
* @throws IllegalArgumentException
* if a handler with the specified new name already exists in this
* pipeline, except for the handler to be replaced
* @throws NullPointerException
* if the specified old handler, new name, or new handler is
* {@code null}
*/ */
void replace(ChannelHandler oldHandler, String newName, ChannelHandler newHandler); void replace(ChannelHandler oldHandler, String newName, ChannelHandler newHandler);
@ -211,6 +262,15 @@ public interface ChannelPipeline {
* handler in this pipeline. * handler in this pipeline.
* *
* @return the removed handler * @return the removed handler
*
* @throws NoSuchElementException
* if the handler with the specified old name doesn't exist in this pipeline
* @throws IllegalArgumentException
* if a handler with the specified new name already exists in this
* pipeline, except for the handler to be replaced
* @throws NullPointerException
* if the specified old handler, new name, or new handler is
* {@code null}
*/ */
ChannelHandler replace(String oldName, String newName, ChannelHandler newHandler); ChannelHandler replace(String oldName, String newName, ChannelHandler newHandler);
@ -219,46 +279,75 @@ public interface ChannelPipeline {
* handler in this pipeline. * handler in this pipeline.
* *
* @return the removed handler * @return the removed handler
*
* @throws NoSuchElementException
* if the handler of the specified old handler type doesn't exist
* in this pipeline
* @throws IllegalArgumentException
* if a handler with the specified new name already exists in this
* pipeline, except for the handler to be replaced
* @throws NullPointerException
* if the specified old handler, new name, or new handler is
* {@code null}
*/ */
<T extends ChannelHandler> T replace(Class<T> oldHandlerType, String newName, ChannelHandler newHandler); <T extends ChannelHandler> T replace(Class<T> oldHandlerType, String newName, ChannelHandler newHandler);
/** /**
* Returns the first {@link ChannelHandler} in this pipeline. * Returns the first {@link ChannelHandler} in this pipeline.
*
* @return the first handler. {@code null} if this pipeline is empty.
*/ */
ChannelHandler getFirst(); ChannelHandler getFirst();
/** /**
* Returns the last {@link ChannelHandler} in this pipeline. * Returns the last {@link ChannelHandler} in this pipeline.
*
* @return the last handler. {@code null} if this pipeline is empty.
*/ */
ChannelHandler getLast(); ChannelHandler getLast();
/** /**
* Returns the {@link ChannelHandler} with the specified name in this * Returns the {@link ChannelHandler} with the specified name in this
* pipeline. * pipeline.
*
* @return the handler with the specified name.
* {@code null} if there's no such handler in this pipeline.
*/ */
ChannelHandler get(String name); ChannelHandler get(String name);
/** /**
* Returns the {@link ChannelHandler} of the specified type in this * Returns the {@link ChannelHandler} of the specified type in this
* pipeline. * pipeline.
*
* @return the handler of the specified handler type.
* {@code null} if there's no such handler in this pipeline.
*/ */
<T extends ChannelHandler> T get(Class<T> handlerType); <T extends ChannelHandler> T get(Class<T> handlerType);
/** /**
* Returns the context object of the specified {@link ChannelHandler} in * Returns the context object of the specified {@link ChannelHandler} in
* this pipeline. * this pipeline.
*
* @return the context object of the specified handler.
* {@code null} if there's no such handler in this pipeline.
*/ */
ChannelHandlerContext getContext(ChannelHandler handler); ChannelHandlerContext getContext(ChannelHandler handler);
/** /**
* Returns the context object of the {@link ChannelHandler} with the * Returns the context object of the {@link ChannelHandler} with the
* specified name in this pipeline. * specified name in this pipeline.
*
* @return the context object of the handler with the specified name.
* {@code null} if there's no such handler in this pipeline.
*/ */
ChannelHandlerContext getContext(String name); ChannelHandlerContext getContext(String name);
/** /**
* Returns the context object of the {@link ChannelHandler} of the * Returns the context object of the {@link ChannelHandler} of the
* specified type in this pipeline. * specified type in this pipeline.
*
* @return the context object of the handler of the specified type.
* {@code null} if there's no such handler in this pipeline.
*/ */
ChannelHandlerContext getContext(Class<? extends ChannelHandler> handlerType); ChannelHandlerContext getContext(Class<? extends ChannelHandler> handlerType);
@ -266,22 +355,32 @@ public interface ChannelPipeline {
/** /**
* Fires the specified {@link ChannelEvent} to the first * Fires the specified {@link ChannelEvent} to the first
* {@link ChannelUpstreamHandler} in this pipeline. * {@link ChannelUpstreamHandler} in this pipeline.
*
* @throws NullPointerException
* if the specified event is {@code null}
*/ */
void sendUpstream(ChannelEvent e); void sendUpstream(ChannelEvent e);
/** /**
* Fires the specified {@link ChannelEvent} to the last * Fires the specified {@link ChannelEvent} to the last
* {@link ChannelDownstreamHandler} in this pipeline. * {@link ChannelDownstreamHandler} in this pipeline.
*
* @throws NullPointerException
* if the specified event is {@code null}
*/ */
void sendDownstream(ChannelEvent e); void sendDownstream(ChannelEvent e);
/** /**
* Returns the {@link Channel} that this pipeline is attached to. * Returns the {@link Channel} that this pipeline is attached to.
*
* @return the channel. {@code null} if this pipeline is not attached yet.
*/ */
Channel getChannel(); Channel getChannel();
/** /**
* Returns the {@link ChannelSink} that this pipeline is attached to. * Returns the {@link ChannelSink} that this pipeline is attached to.
*
* @return the sink. {@code null} if this pipeline is not attached yet.
*/ */
ChannelSink getSink(); ChannelSink getSink();
@ -289,6 +388,8 @@ public interface ChannelPipeline {
* Attaches this pipeline to the specified {@link Channel} and * Attaches this pipeline to the specified {@link Channel} and
* {@link ChannelSink}. Once a pipeline is attached, it can't be detached * {@link ChannelSink}. Once a pipeline is attached, it can't be detached
* nor attached again. * nor attached again.
*
* @throws IllegalStateException if this pipeline is attached already
*/ */
void attach(Channel channel, ChannelSink sink); void attach(Channel channel, ChannelSink sink);