andreacavalli/netty5
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

More JavaDoc

Browse Source
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
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

29
src/main/java/org/jboss/netty/channel/ChannelConfig.java
View File

@ -25,12 +25,15 @@ package org.jboss.netty.channel;
import java.io.IOException;
import java.util.Map;
import org.jboss.netty.channel.socket.nio.NioSocketChannelConfig;
/**
* The configuration properties of a {@link Channel}.
* <p>
* Please down-cast to the transport-specific configuration type or use
* {@link #setOptions(Map)} to set the transport-specific properties.
* Please down-cast to the transport-specific configuration type such as
* {@link NioSocketChannelConfig} or use {@link #setOptions(Map)} to set the
* transport-specific properties.
*
* @author The Netty Project (netty-dev@lists.jboss.org)
* @author Trustin Lee (tlee@redhat.com)
@ -48,25 +51,33 @@ public interface ChannelConfig {
/**
* 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();
/**
* 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);
/**
* 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.
*/
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.
* {@code 0} to disable.
@ -76,7 +87,8 @@ public interface ChannelConfig {
/**
* Returns the write timeout of the channel in milliseconds. If a write
* 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.
*/
@ -85,7 +97,8 @@ public interface ChannelConfig {
/**
* Sets the write timeout of the channel in milliseconds. If a write
* 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.
* {@code 0} to disable.

12
src/main/java/org/jboss/netty/channel/ChannelFactory.java
View File

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

6
src/main/java/org/jboss/netty/channel/ChannelFutureListener.java
View File

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

7
src/main/java/org/jboss/netty/channel/ChannelHandler.java
View File

@ -37,6 +37,13 @@ package org.jboss.netty.channel;
* a {@link ChannelEvent} fired by a user via the methods in
* the {@link Channel} interface and the {@link Channels} helper class.</li>
* </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 Trustin Lee (tlee@redhat.com)

115
src/main/java/org/jboss/netty/channel/ChannelPipeline.java
View File

@ -23,6 +23,7 @@
package org.jboss.netty.channel;
import java.util.Map;
import java.util.NoSuchElementException;
import org.jboss.netty.buffer.ChannelBuffer;
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
* {@link ChannelEvent}.
* A list of {@link ChannelHandler}s which handles or intercepts
* {@link ChannelEvent}s of a {@link Channel}.
* <p>
* {@link ChannelPipeline} implements an advanced form of the
* <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
* and how {@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}.
* and how the {@link ChannelHandler}s in the pipeline interact with each other.
* <p>
* 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
@ -131,6 +128,11 @@ public interface ChannelPipeline {
*
* @param name the name of 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);
@ -139,6 +141,11 @@ public interface ChannelPipeline {
*
* @param name the name of 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);
@ -149,6 +156,13 @@ public interface ChannelPipeline {
* @param baseName the name of the existing handler
* @param name the name of 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);
@ -159,11 +173,23 @@ public interface ChannelPipeline {
* @param baseName the name of the existing handler
* @param name the name of 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);
/**
* 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);
@ -172,6 +198,11 @@ public interface ChannelPipeline {
* pipeline.
*
* @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);
@ -183,6 +214,11 @@ public interface ChannelPipeline {
* @param handlerType the type of the 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);
@ -190,6 +226,9 @@ public interface ChannelPipeline {
* Removes the first {@link ChannelHandler} in this pipeline.
*
* @return the removed handler
*
* @throws NoSuchElementException
* if this pipeline is empty
*/
ChannelHandler removeFirst();
@ -197,12 +236,24 @@ public interface ChannelPipeline {
* Removes the last {@link ChannelHandler} in this pipeline.
*
* @return the removed handler
*
* @throws NoSuchElementException
* if this pipeline is empty
*/
ChannelHandler removeLast();
/**
* Replaces the specified {@link ChannelHandler} with a new handler in
* 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);
@ -211,6 +262,15 @@ public interface ChannelPipeline {
* handler in this pipeline.
*
* @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);
@ -219,46 +279,75 @@ public interface ChannelPipeline {
* handler in this pipeline.
*
* @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);
/**
* Returns the first {@link ChannelHandler} in this pipeline.
*
* @return the first handler. {@code null} if this pipeline is empty.
*/
ChannelHandler getFirst();
/**
* Returns the last {@link ChannelHandler} in this pipeline.
*
* @return the last handler. {@code null} if this pipeline is empty.
*/
ChannelHandler getLast();
/**
* Returns the {@link ChannelHandler} with the specified name in this
* pipeline.
*
* @return the handler with the specified name.
* {@code null} if there's no such handler in this pipeline.
*/
ChannelHandler get(String name);
/**
* Returns the {@link ChannelHandler} of the specified type in this
* 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);
/**
* Returns the context object of the specified {@link ChannelHandler} in
* 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);
/**
* Returns the context object of the {@link ChannelHandler} with the
* 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);
/**
* Returns the context object of the {@link ChannelHandler} of the
* 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);
@ -266,22 +355,32 @@ public interface ChannelPipeline {
/**
* Fires the specified {@link ChannelEvent} to the first
* {@link ChannelUpstreamHandler} in this pipeline.
*
* @throws NullPointerException
* if the specified event is {@code null}
*/
void sendUpstream(ChannelEvent e);
/**
* Fires the specified {@link ChannelEvent} to the last
* {@link ChannelDownstreamHandler} in this pipeline.
*
* @throws NullPointerException
* if the specified event is {@code null}
*/
void sendDownstream(ChannelEvent e);
/**
* Returns the {@link Channel} that this pipeline is attached to.
*
* @return the channel. {@code null} if this pipeline is not attached yet.
*/
Channel getChannel();
/**
* Returns the {@link ChannelSink} that this pipeline is attached to.
*
* @return the sink. {@code null} if this pipeline is not attached yet.
*/
ChannelSink getSink();
@ -289,6 +388,8 @@ public interface ChannelPipeline {
* Attaches this pipeline to the specified {@link Channel} and
* {@link ChannelSink}. Once a pipeline is attached, it can't be detached
* nor attached again.
*
* @throws IllegalStateException if this pipeline is attached already
*/
void attach(Channel channel, ChannelSink sink);