diff --git a/src/main/java/org/jboss/netty/bootstrap/Bootstrap.java b/src/main/java/org/jboss/netty/bootstrap/Bootstrap.java index a4ccad2a1b..b995111876 100644 --- a/src/main/java/org/jboss/netty/bootstrap/Bootstrap.java +++ b/src/main/java/org/jboss/netty/bootstrap/Bootstrap.java @@ -37,10 +37,10 @@ import org.jboss.netty.channel.ChannelPipelineFactory; import org.jboss.netty.util.MapUtil; /** - * Helper class which helps a user initialize a {@link Channel}. This class - * provides the common data structure for its subclasses which implement an - * actual channel initialization from the common data structure. Please refer - * to {@link ClientBootstrap} and {@link ServerBootstrap} for client side and + * A helper class which initializes a {@link Channel}. This class provides + * the common data structure for its subclasses which implement an actual + * channel initialization from the common data structure. Please refer to + * {@link ClientBootstrap} and {@link ServerBootstrap} for client side and * server-side channel initialization respectively. * * @author The Netty Project (netty-dev@lists.jboss.org) diff --git a/src/main/java/org/jboss/netty/bootstrap/ClientBootstrap.java b/src/main/java/org/jboss/netty/bootstrap/ClientBootstrap.java index bc7ceb245a..f5e73a611e 100644 --- a/src/main/java/org/jboss/netty/bootstrap/ClientBootstrap.java +++ b/src/main/java/org/jboss/netty/bootstrap/ClientBootstrap.java @@ -42,8 +42,8 @@ import org.jboss.netty.channel.ExceptionEvent; import org.jboss.netty.channel.SimpleChannelHandler; /** - * Helper class which helps a user create a new client-side {@link Channel} - * and make a connection attempt. + * A helper class which creates a new client-side {@link Channel} and make a + * connection attempt. * *

Configuring a channel

* diff --git a/src/main/java/org/jboss/netty/bootstrap/ServerBootstrap.java b/src/main/java/org/jboss/netty/bootstrap/ServerBootstrap.java index b75932acae..97492e9122 100644 --- a/src/main/java/org/jboss/netty/bootstrap/ServerBootstrap.java +++ b/src/main/java/org/jboss/netty/bootstrap/ServerBootstrap.java @@ -47,8 +47,8 @@ import org.jboss.netty.channel.ExceptionEvent; import org.jboss.netty.channel.SimpleChannelHandler; /** - * Helper class which helps a user create a new server-side {@link Channel} - * and accept incoming connections. + * A helper class which creates a new server-side {@link Channel} and accept + * incoming connections. * *

Parent channel and its children

* diff --git a/src/main/java/org/jboss/netty/buffer/AbstractChannelBuffer.java b/src/main/java/org/jboss/netty/buffer/AbstractChannelBuffer.java index b26150a5d9..a3351bfd11 100644 --- a/src/main/java/org/jboss/netty/buffer/AbstractChannelBuffer.java +++ b/src/main/java/org/jboss/netty/buffer/AbstractChannelBuffer.java @@ -32,7 +32,7 @@ import java.util.NoSuchElementException; /** - * Skeletal implementation of a buffer. + * A skeletal implementation of a buffer. * * @author The Netty Project (netty-dev@lists.jboss.org) * @author Trustin Lee (tlee@redhat.com) @@ -535,6 +535,11 @@ public abstract class AbstractChannelBuffer implements ChannelBuffer { ')'; } + /** + * Throws an {@link IndexOutOfBoundsException} is the current + * {@linkplain #readableBytes() readable bytes} of this buffer is less + * than the specified value. + */ protected void checkReadableBytes(int minimumReadableBytes) { if (readableBytes() < minimumReadableBytes) { throw new IndexOutOfBoundsException(); diff --git a/src/main/java/org/jboss/netty/buffer/BigEndianHeapChannelBuffer.java b/src/main/java/org/jboss/netty/buffer/BigEndianHeapChannelBuffer.java index 867c8c49e7..46a7cd73e0 100644 --- a/src/main/java/org/jboss/netty/buffer/BigEndianHeapChannelBuffer.java +++ b/src/main/java/org/jboss/netty/buffer/BigEndianHeapChannelBuffer.java @@ -26,7 +26,9 @@ import java.nio.ByteOrder; /** - * Big-endian Java heap buffer. + * A big-endian Java heap buffer. It is recommended to use {@link ChannelBuffers#buffer(int)} + * and {@link ChannelBuffers#wrappedBuffer(byte[])} instead of calling the + * constructor explicitly. * * @author The Netty Project (netty-dev@lists.jboss.org) * @author Trustin Lee (tlee@redhat.com) @@ -35,10 +37,20 @@ import java.nio.ByteOrder; */ public class BigEndianHeapChannelBuffer extends HeapChannelBuffer { + /** + * Creates a new big-endian heap buffer with a newly allocated byte array. + * + * @param length the length of the new byte array + */ public BigEndianHeapChannelBuffer(int length) { super(length); } + /** + * Creates a new big-endian heap buffer with an existing byte array. + * + * @param array the byte array to wrap + */ public BigEndianHeapChannelBuffer(byte[] array) { super(array); } diff --git a/src/main/java/org/jboss/netty/buffer/ByteBufferBackedChannelBuffer.java b/src/main/java/org/jboss/netty/buffer/ByteBufferBackedChannelBuffer.java index a8cb7332be..76e5d77f93 100644 --- a/src/main/java/org/jboss/netty/buffer/ByteBufferBackedChannelBuffer.java +++ b/src/main/java/org/jboss/netty/buffer/ByteBufferBackedChannelBuffer.java @@ -33,7 +33,9 @@ import java.nio.channels.ScatteringByteChannel; import java.nio.charset.UnsupportedCharsetException; /** - * NIO direct buffer based buffer. + * A NIO {@link ByteBuffer} based buffer. It is recommended to use {@link ChannelBuffers#directBuffer(int)} + * and {@link ChannelBuffers#wrappedBuffer(ByteBuffer)} instead of calling the + * constructor explicitly. * * @author The Netty Project (netty-dev@lists.jboss.org) * @author Trustin Lee (tlee@redhat.com) @@ -46,6 +48,9 @@ public class ByteBufferBackedChannelBuffer extends AbstractChannelBuffer { private final ByteBuffer buffer; private final int capacity; + /** + * Creates a new buffer which wraps the specified buffer's slice. + */ public ByteBufferBackedChannelBuffer(ByteBuffer buffer) { if (buffer == null) { throw new NullPointerException("buffer"); diff --git a/src/main/java/org/jboss/netty/buffer/ChannelBuffer.java b/src/main/java/org/jboss/netty/buffer/ChannelBuffer.java index 39ecdf907f..55ebe68d3c 100644 --- a/src/main/java/org/jboss/netty/buffer/ChannelBuffer.java +++ b/src/main/java/org/jboss/netty/buffer/ChannelBuffer.java @@ -33,7 +33,7 @@ import java.nio.charset.UnsupportedCharsetException; import java.util.NoSuchElementException; /** - * Random and sequential accessible sequence of zero or more bytes (octets). + * A random and sequential accessible sequence of zero or more bytes (octets). * This interface provides an abstract view for one or more primitive byte * arrays ({@code byte[]}) and {@linkplain ByteBuffer NIO buffers}. * diff --git a/src/main/java/org/jboss/netty/buffer/ChannelBufferInputStream.java b/src/main/java/org/jboss/netty/buffer/ChannelBufferInputStream.java index 00eba2c980..8d732c5889 100644 --- a/src/main/java/org/jboss/netty/buffer/ChannelBufferInputStream.java +++ b/src/main/java/org/jboss/netty/buffer/ChannelBufferInputStream.java @@ -29,7 +29,7 @@ import java.io.IOException; import java.io.InputStream; /** - * {@link InputStream} which reads data from a {@link ChannelBuffer}. + * An {@link InputStream} which reads data from a {@link ChannelBuffer}. *

* A read operation against this stream will occur at the {@code readerIndex} * of its underlying buffer and the {@code readerIndex} will increase during diff --git a/src/main/java/org/jboss/netty/buffer/ChannelBufferOutputStream.java b/src/main/java/org/jboss/netty/buffer/ChannelBufferOutputStream.java index 46a6cd72ec..ee8da57964 100644 --- a/src/main/java/org/jboss/netty/buffer/ChannelBufferOutputStream.java +++ b/src/main/java/org/jboss/netty/buffer/ChannelBufferOutputStream.java @@ -28,7 +28,7 @@ import java.io.IOException; import java.io.OutputStream; /** - * {@link OutputStream} which writes data to a {@link ChannelBuffer}. + * An {@link OutputStream} which writes data to a {@link ChannelBuffer}. *

* A write operation against this stream will occur at the {@code writerIndex} * of its underlying buffer and the {@code writerIndex} will increase during diff --git a/src/main/java/org/jboss/netty/buffer/CompositeChannelBuffer.java b/src/main/java/org/jboss/netty/buffer/CompositeChannelBuffer.java index 065985ea69..d1f8223cc8 100644 --- a/src/main/java/org/jboss/netty/buffer/CompositeChannelBuffer.java +++ b/src/main/java/org/jboss/netty/buffer/CompositeChannelBuffer.java @@ -36,7 +36,9 @@ import java.util.List; /** - * Virtual buffer which shows multiple buffers as a single merged buffer. + * A virtual buffer which shows multiple buffers as a single merged buffer. It + * is recommended to use {@link ChannelBuffers#wrappedBuffer(ChannelBuffer...)} + * instead of calling the constructor explicitly. * * @author The Netty Project (netty-dev@lists.jboss.org) * @author Trustin Lee (tlee@redhat.com) diff --git a/src/main/java/org/jboss/netty/buffer/DuplicatedChannelBuffer.java b/src/main/java/org/jboss/netty/buffer/DuplicatedChannelBuffer.java index 083c19aaf5..da4f4c951f 100644 --- a/src/main/java/org/jboss/netty/buffer/DuplicatedChannelBuffer.java +++ b/src/main/java/org/jboss/netty/buffer/DuplicatedChannelBuffer.java @@ -32,8 +32,9 @@ import java.nio.channels.ScatteringByteChannel; /** - * Derived buffer which simply forwards all data access requests to its - * parent. + * A derived buffer which simply forwards all data access requests to its + * parent. It is recommended to use {@link ChannelBuffer#duplicate()} instead + * of calling the constructor explicitly. * * @author The Netty Project (netty-dev@lists.jboss.org) * @author Trustin Lee (tlee@redhat.com) diff --git a/src/main/java/org/jboss/netty/buffer/DynamicChannelBuffer.java b/src/main/java/org/jboss/netty/buffer/DynamicChannelBuffer.java index 3670950238..f125309c0d 100644 --- a/src/main/java/org/jboss/netty/buffer/DynamicChannelBuffer.java +++ b/src/main/java/org/jboss/netty/buffer/DynamicChannelBuffer.java @@ -32,7 +32,9 @@ import java.nio.channels.ScatteringByteChannel; /** - * Dynamic capacity buffer which increases its capacity as needed. + * A dynamic capacity buffer which increases its capacity as needed. It is + * recommended to use {@link ChannelBuffers#dynamicBuffer(int)} instead of + * calling the constructor explicitly. * * @author The Netty Project (netty-dev@lists.jboss.org) * @author Trustin Lee (tlee@redhat.com) diff --git a/src/main/java/org/jboss/netty/buffer/HeapChannelBuffer.java b/src/main/java/org/jboss/netty/buffer/HeapChannelBuffer.java index abdbdd8364..64b486562d 100644 --- a/src/main/java/org/jboss/netty/buffer/HeapChannelBuffer.java +++ b/src/main/java/org/jboss/netty/buffer/HeapChannelBuffer.java @@ -32,7 +32,7 @@ import java.nio.channels.ScatteringByteChannel; import java.nio.charset.UnsupportedCharsetException; /** - * Skeletal implementation for Java heap buffers. + * A skeletal implementation for Java heap buffers. * * @author The Netty Project (netty-dev@lists.jboss.org) * @author Trustin Lee (tlee@redhat.com) @@ -41,16 +41,36 @@ import java.nio.charset.UnsupportedCharsetException; */ public abstract class HeapChannelBuffer extends AbstractChannelBuffer { + /** + * The underlying heap byte array that this buffer is wrapping. + */ protected final byte[] array; + /** + * Creates a new heap buffer with a newly allocated byte array. + * + * @param length the length of the new byte array + */ public HeapChannelBuffer(int length) { this(new byte[length], 0, 0); } + /** + * Creates a new heap buffer with an existing byte array. + * + * @param array the byte array to wrap + */ public HeapChannelBuffer(byte[] array) { this(array, 0, array.length); } + /** + * Creates a new heap buffer with an existing byte array. + * + * @param array the byte array to wrap + * @param readerIndex the initial reader index of this buffer + * @param writerIndex the initial writer index of this buffer + */ protected HeapChannelBuffer(byte[] array, int readerIndex, int writerIndex) { if (array == null) { throw new NullPointerException("array"); diff --git a/src/main/java/org/jboss/netty/buffer/LittleEndianHeapChannelBuffer.java b/src/main/java/org/jboss/netty/buffer/LittleEndianHeapChannelBuffer.java index 4f35c46954..cc760fcdfd 100644 --- a/src/main/java/org/jboss/netty/buffer/LittleEndianHeapChannelBuffer.java +++ b/src/main/java/org/jboss/netty/buffer/LittleEndianHeapChannelBuffer.java @@ -26,7 +26,9 @@ import java.nio.ByteOrder; /** - * Little-endian Java heap buffer. + * A little-endian Java heap buffer. It is recommended to use {@link ChannelBuffers#buffer(ByteOrder, int)} + * and {@link ChannelBuffers#wrappedBuffer(ByteOrder, byte[])} instead of + * calling the constructor explicitly. * * @author The Netty Project (netty-dev@lists.jboss.org) * @author Trustin Lee (tlee@redhat.com) @@ -35,10 +37,20 @@ import java.nio.ByteOrder; */ public class LittleEndianHeapChannelBuffer extends HeapChannelBuffer { + /** + * Creates a new little-endian heap buffer with a newly allocated byte array. + * + * @param length the length of the new byte array + */ public LittleEndianHeapChannelBuffer(int length) { super(length); } + /** + * Creates a new little-endian heap buffer with an existing byte array. + * + * @param array the byte array to wrap + */ public LittleEndianHeapChannelBuffer(byte[] array) { super(array); } diff --git a/src/main/java/org/jboss/netty/buffer/ReadOnlyChannelBuffer.java b/src/main/java/org/jboss/netty/buffer/ReadOnlyChannelBuffer.java index 29f6cf5711..1b093ae96b 100644 --- a/src/main/java/org/jboss/netty/buffer/ReadOnlyChannelBuffer.java +++ b/src/main/java/org/jboss/netty/buffer/ReadOnlyChannelBuffer.java @@ -31,7 +31,9 @@ import java.nio.channels.GatheringByteChannel; import java.nio.channels.ScatteringByteChannel; /** - * Derived buffer which forbids any write requests to its parent. + * A derived buffer which forbids any write requests to its parent. It is + * recommended to use {@link ChannelBuffers#unmodifiableBuffer(ChannelBuffer)} + * instead of calling the constructor explicitly. * * @author The Netty Project (netty-dev@lists.jboss.org) * @author Trustin Lee (tlee@redhat.com) diff --git a/src/main/java/org/jboss/netty/buffer/SlicedChannelBuffer.java b/src/main/java/org/jboss/netty/buffer/SlicedChannelBuffer.java index fdbac0155a..5ebe660e1f 100644 --- a/src/main/java/org/jboss/netty/buffer/SlicedChannelBuffer.java +++ b/src/main/java/org/jboss/netty/buffer/SlicedChannelBuffer.java @@ -32,7 +32,10 @@ import java.nio.channels.ScatteringByteChannel; /** - * Derived buffer which exposes its parent's sub-region only. + * A derived buffer which exposes its parent's sub-region only. It is + * recommended to use {@link ChannelBuffer#slice()} and + * {@link ChannelBuffer#slice(int, int)} instead of calling the constructor + * explicitly. * * @author The Netty Project (netty-dev@lists.jboss.org) * @author Trustin Lee (tlee@redhat.com) diff --git a/src/main/java/org/jboss/netty/buffer/TruncatedChannelBuffer.java b/src/main/java/org/jboss/netty/buffer/TruncatedChannelBuffer.java index fae1d8a268..00ac439ad8 100644 --- a/src/main/java/org/jboss/netty/buffer/TruncatedChannelBuffer.java +++ b/src/main/java/org/jboss/netty/buffer/TruncatedChannelBuffer.java @@ -32,7 +32,10 @@ import java.nio.channels.ScatteringByteChannel; /** - * Derived buffer which hides its parent's tail data beyond a certain index. + * A derived buffer which hides its parent's tail data beyond a certain index. + * It is recommended to use {@link ChannelBuffer#slice()} and + * {@link ChannelBuffer#slice(int, int)} instead of calling the constructor + * explicitly. * * @author The Netty Project (netty-dev@lists.jboss.org) * @author Trustin Lee (tlee@redhat.com) diff --git a/src/main/java/org/jboss/netty/buffer/WrappedChannelBuffer.java b/src/main/java/org/jboss/netty/buffer/WrappedChannelBuffer.java index 754064e4c0..cb3abd0700 100644 --- a/src/main/java/org/jboss/netty/buffer/WrappedChannelBuffer.java +++ b/src/main/java/org/jboss/netty/buffer/WrappedChannelBuffer.java @@ -23,7 +23,7 @@ package org.jboss.netty.buffer; /** - * Common interface for buffer wrappers and derived buffers. Most users won't + * The common interface for buffer wrappers and derived buffers. Most users won't * need to use this interface. It's used internally in most cases. * * @author The Netty Project (netty-dev@lists.jboss.org) diff --git a/src/main/java/org/jboss/netty/channel/AbstractChannel.java b/src/main/java/org/jboss/netty/channel/AbstractChannel.java index f899efedd8..539af8663d 100644 --- a/src/main/java/org/jboss/netty/channel/AbstractChannel.java +++ b/src/main/java/org/jboss/netty/channel/AbstractChannel.java @@ -29,6 +29,7 @@ import java.util.concurrent.atomic.AtomicBoolean; import org.jboss.netty.util.TimeBasedUuidGenerator; /** + * A skeletal {@link Channel} implementation. * * @author The Netty Project (netty-dev@lists.jboss.org) * @author Trustin Lee (tlee@redhat.com) @@ -50,6 +51,19 @@ public abstract class AbstractChannel implements Channel, Comparable { /** Cache for the string representation of this channel */ private String strVal; + /** + * Creates a new instance. + * + * @param parent + * the parent of this channel. {@code null} if there's no parent. + * @param factory + * the factory which created this channel + * @param pipeline + * the pipeline which is going to be attached to this channel + * @param sink + * the sink which will receive downstream events from the pipeline + * and send upstream events to the pipeline + */ protected AbstractChannel( Channel parent, ChannelFactory factory, ChannelPipeline pipeline, ChannelSink sink) { @@ -76,24 +90,42 @@ public abstract class AbstractChannel implements Channel, Comparable { return pipeline; } + /** + * Returns the cached {@link SucceededChannelFuture} instance. + */ protected ChannelFuture getSucceededFuture() { return succeededFuture; } + /** + * Returns the {@link FailedChannelFuture} whose cause is a + * {@link UnsupportedOperationException}. + */ protected ChannelFuture getUnsupportedOperationFuture() { return new FailedChannelFuture(this, new UnsupportedOperationException()); } + /** + * Returns the {@linkplain System#identityHashCode(Object) identity hash code} + * of this channel. + */ @Override public final int hashCode() { return System.identityHashCode(this); } + /** + * Returns if and only if the specified object is identical with this + * channel (i.e. {@code this == o}). + */ @Override public final boolean equals(Object o) { return this == o; } + /** + * Compares the {@linkplain #getId() ID} of the two channel. + */ public final int compareTo(Channel o) { return getId().compareTo(o.getId()); } @@ -102,6 +134,14 @@ public abstract class AbstractChannel implements Channel, Comparable { return !closed.get(); } + /** + * Marks this channel as closed. This method is intended to be called by + * an internal component - please do not call it unless you know what you + * are doing. + * + * @return {@code true} if and only if this channel was not marked as + * closed yet + */ protected boolean setClosed() { return closed.compareAndSet(false, true); } @@ -130,6 +170,11 @@ public abstract class AbstractChannel implements Channel, Comparable { return Channels.setInterestOps(this, interestOps); } + /** + * Sets the {@link #getInterestOps() interestOps} property of this channel + * immediately. This method is intended to be called by an internal + * component - please do not call it unless you know what you are doing. + */ protected void setInterestOpsNow(int interestOps) { this.interestOps = interestOps; } @@ -158,6 +203,12 @@ public abstract class AbstractChannel implements Channel, Comparable { return Channels.write(this, message, remoteAddress); } + /** + * Returns the {@link String} representation of this channel. The returned + * string contains the {@linkplain #getId() ID}, {@linkplain #getLocalAddress() local address}, + * and {@linkplain #getRemoteAddress() remote address} of this channel for + * easier identification. + */ @Override public String toString() { if (strVal != null) { diff --git a/src/main/java/org/jboss/netty/channel/AbstractChannelSink.java b/src/main/java/org/jboss/netty/channel/AbstractChannelSink.java index 34f358181e..a15bf52465 100644 --- a/src/main/java/org/jboss/netty/channel/AbstractChannelSink.java +++ b/src/main/java/org/jboss/netty/channel/AbstractChannelSink.java @@ -25,6 +25,7 @@ package org.jboss.netty.channel; import static org.jboss.netty.channel.Channels.*; /** + * A skeletal {@link ChannelSink} implementation. * * @author The Netty Project (netty-dev@lists.jboss.org) * @author Trustin Lee (tlee@redhat.com) @@ -33,6 +34,20 @@ import static org.jboss.netty.channel.Channels.*; */ public abstract class AbstractChannelSink implements ChannelSink { + /** + * Creates a new instance. + */ + protected AbstractChannelSink() { + super(); + } + + /** + * Fires an {@link ExceptionEvent} upstream with the specified {@code cause}. + * + * @param event the {@link ChannelEvent} which caused a + * {@link ChannelHandler} to raise an exception + * @param cause the exception raised by a {@link ChannelHandler} + */ public void exceptionCaught(ChannelPipeline pipeline, ChannelEvent event, ChannelPipelineException cause) throws Exception { Throwable actualCause = cause.getCause(); diff --git a/src/main/java/org/jboss/netty/channel/AbstractServerChannel.java b/src/main/java/org/jboss/netty/channel/AbstractServerChannel.java index b760cfa9c3..49f375ceab 100644 --- a/src/main/java/org/jboss/netty/channel/AbstractServerChannel.java +++ b/src/main/java/org/jboss/netty/channel/AbstractServerChannel.java @@ -24,9 +24,19 @@ package org.jboss.netty.channel; import java.net.SocketAddress; - - /** + * A skeletal server-side {@link Channel} implementation. A server-side + * {@link Channel} doesn't allow the following operations: + *

+ * * @author The Netty Project (netty-dev@lists.jboss.org) * @author Trustin Lee (tlee@redhat.com) * @@ -35,6 +45,17 @@ import java.net.SocketAddress; */ public abstract class AbstractServerChannel extends AbstractChannel { + /** + * Creates a new instance. + * + * @param factory + * the factory which created this channel + * @param pipeline + * the pipeline which is going to be attached to this channel + * @param sink + * the sink which will receive downstream events from the pipeline + * and send upstream events to the pipeline + */ protected AbstractServerChannel( ChannelFactory factory, ChannelPipeline pipeline, diff --git a/src/main/java/org/jboss/netty/channel/Channel.java b/src/main/java/org/jboss/netty/channel/Channel.java index e54793981a..442dd4572a 100644 --- a/src/main/java/org/jboss/netty/channel/Channel.java +++ b/src/main/java/org/jboss/netty/channel/Channel.java @@ -27,6 +27,17 @@ import java.util.UUID; /** + * A nexus to a network socket or a component which is capable of predefined + * I/O operations such as read, write, connect, and bind. + *

+ * A channel provides a user: + *

* * @author The Netty Project (netty-dev@lists.jboss.org) * @author Trustin Lee (tlee@redhat.com) @@ -38,35 +49,217 @@ import java.util.UUID; * @apiviz.composedOf org.jboss.netty.channel.ChannelPipeline */ public interface Channel { + + /** + * The {@link #getInterestOps() interestOps} value which tells that the + * I/O thread will not read a message from the channel but will perform + * the requested write operation immediately. + */ static int OP_NONE = 0; + + /** + * The {@link #getInterestOps() interestOps} value which tells that the + * I/O thread will read a message from the channel and will perform the + * requested write operation immediately. + */ static int OP_READ = 1; + + /** + * The {@link #getInterestOps() interestOps} value which tells that the + * I/O thread will not read a message from the channel and will not perform + * the requested write operation immediately. Any write requests made when + * {@link #OP_WRITE} flag is set are queued until the I/O thread is ready + * to process the queued write requests. + */ static int OP_WRITE = 4; + + /** + * The {@link #getInterestOps() interestOps} value which tells that the + * I/O thread will read a message from the channel but will not perform + * the requested write operation immediately. Any write requests made when + * {@link #OP_WRITE} flag is set are queued until the I/O thread is ready + * to process the queued write requests. + */ static int OP_READ_WRITE = OP_READ | OP_WRITE; + /** + * Returns the {@link UUID} of this channel. + */ UUID getId(); + + /** + * Returns the {@link ChannelFactory} which created this channel. + */ ChannelFactory getFactory(); + + /** + * Returns the parent of this channel. + * + * @return the parent channel. + * {@code null} if this channel doesn't have a parent channel. + */ Channel getParent(); + + /** + * Returns the configuration of this channel. + */ ChannelConfig getConfig(); + + /** + * Returns the {@link ChannelPipeline} which handles {@link ChannelEvent}s + * associated with this channel. + */ ChannelPipeline getPipeline(); + /** + * Return {@code true} if and only if this channel is open. + */ boolean isOpen(); + + /** + * Return {@code true} if and only if this channel is bound to a + * {@linkplain #getLocalAddress() local address}. + */ boolean isBound(); + + /** + * Return {@code true} if and only if this channel is connected to a + * {@linkplain #getRemoteAddress() remote address}. + */ boolean isConnected(); + /** + * Returns the local address where this channel is bound to. + * + * @return the local address of this channel. + * {@code null} if this channel is not bound. + */ SocketAddress getLocalAddress(); + + /** + * Returns the remote address where this channel is connected to. + * + * @return the remote address of this channel. + * {@code null} if this channel is not connected. + */ SocketAddress getRemoteAddress(); + /** + * Sends a message to this channel asynchronously. + * + * @param message the message to write + * + * @return the {@link ChannelFuture} which will be notified when the + * write request succeeds or fails + */ ChannelFuture write(Object message); + + /** + * Sends a message to this channel asynchronously. It has an additional + * parameter that allows a user to specify where to send the specified + * message instead of this channel's current remote address. + * + * @param message the message to write + * @param remoteAddress where to send the specified message + * + * @return the {@link ChannelFuture} which will be notified when the + * write request succeeds or fails + */ ChannelFuture write(Object message, SocketAddress remoteAddress); + /** + * Binds this channel to the specified local address asynchronously. + * + * @param localAddress where to bind + * + * @return the {@link ChannelFuture} which will be notified when the + * bind request succeeds or fails + */ ChannelFuture bind(SocketAddress localAddress); + + /** + * Connects this channel to the specified remote address asynchronously. + * + * @param remoteAddress where to connect + * + * @return the {@link ChannelFuture} which will be notified when the + * connection request succeeds or fails + */ ChannelFuture connect(SocketAddress remoteAddress); + + /** + * Disconnects this channel from the current remote address asynchronously. + * + * @return the {@link ChannelFuture} which will be notified when the + * disconnection request succeeds or fails + */ ChannelFuture disconnect(); + + /** + * Closes this channel asynchronously. If this channel is bound or + * connected, it will be disconnected and unbound first. + * + * @return the {@link ChannelFuture} which will be notified when the + * close request succeeds or fails + */ ChannelFuture close(); + /** + * Returns the current {@code interestOps} of this channel. + * + * @return {@link #OP_NONE}, {@link #OP_READ}, {@link #OP_WRITE}, or + * {@link #OP_READ_WRITE} + */ int getInterestOps(); + + /** + * Returns {@code true} if and only if the I/O thread will read a message + * from this channel. This method is a shortcut to the following code: + * 
+     * return (getInterestOps() & OP_READ) != 0;
+     *
+ */ boolean isReadable(); + + /** + * Returns {@code true} if and only if the I/O thread will perform the + * requested write operation immediately. Any write requests made when + * this method returns {@code false} are queued until the I/O thread is + * ready to process the queued write requests. This method is a shortcut + * to the following code: + * 
+     * return (getInterestOps() & OP_WRITE) != 0;
+     *
+ */ boolean isWritable(); + + /** + * Changes the {@code interestOps} of this channel asynchronously. + * + * @param interestOps the new {@code interestOps} + * + * @return the {@link ChannelFuture} which will be notified when the + * {@code interestOps} change request succeeds or fails + */ ChannelFuture setInterestOps(int interestOps); + + /** + * Suspends or resumes the read operation of the I/O thread asynchronously. + * This method is a shortcut to the following code: + * 
+     * int interestOps = getInterestOps();
+     * if (readable) {
+     *     setInterestOps(interestOps | OP_READ);
+     * } else {
+     *     setInterestOps(interestOps & ~OP_READ);
+     * }
+     *
+ * + * @param readable {@code true} to resume the read operation and + * {@code false} to suspend the read operation + * + * @return the {@link ChannelFuture} which will be notified when the + * {@code interestOps} change request succeeds or fails + */ ChannelFuture setReadable(boolean readable); } diff --git a/src/main/java/org/jboss/netty/channel/ChannelConfig.java b/src/main/java/org/jboss/netty/channel/ChannelConfig.java index b74e2a147c..60b154785e 100644 --- a/src/main/java/org/jboss/netty/channel/ChannelConfig.java +++ b/src/main/java/org/jboss/netty/channel/ChannelConfig.java @@ -22,10 +22,15 @@ */ package org.jboss.netty.channel; +import java.io.IOException; import java.util.Map; /** + * The configuration properties of a {@link Channel}. + *

+ * Please down-cast to the transport-specific configuration type 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) @@ -35,11 +40,55 @@ import java.util.Map; * @apiviz.has org.jboss.netty.channel.ChannelPipelineFactory */ public interface ChannelConfig { + + /** + * Sets the configuration properties from the specified {@link Map}. + */ void setOptions(Map options); + + /** + * Returns the {@link ChannelPipelineFactory} which will be used when + * a child channel is created. + */ ChannelPipelineFactory getPipelineFactory(); + + /** + * Sets the {@link ChannelPipelineFactory} which will be used when + * a child channel is created. + */ void setPipelineFactory(ChannelPipelineFactory pipelineFactory); + + /** + * Returns the connect timeout of the channel in milliseconds. + * + * @return the connect timeout in milliseconds. {@code 0} if disabled. + */ int getConnectTimeoutMillis(); + + /** + * Sets the connect timeout of the channel in milliseconds. + * + * @param connectTimeoutMillis the connect timeout in milliseconds. + * {@code 0} to disable. + */ void setConnectTimeoutMillis(int connectTimeoutMillis); + + /** + * 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. + * + * @return the write timeout in milliseconds. {@code 0} if disabled. + */ int getWriteTimeoutMillis(); + + /** + * 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. + * + * @param writeTimeoutMillis the write timeout in milliseconds. + * {@code 0} to disable. + */ void setWriteTimeoutMillis(int writeTimeoutMillis); } diff --git a/src/main/java/org/jboss/netty/channel/ChannelDownstreamHandler.java b/src/main/java/org/jboss/netty/channel/ChannelDownstreamHandler.java index c45e867265..6dd16ab908 100644 --- a/src/main/java/org/jboss/netty/channel/ChannelDownstreamHandler.java +++ b/src/main/java/org/jboss/netty/channel/ChannelDownstreamHandler.java @@ -22,6 +22,8 @@ */ package org.jboss.netty.channel; +import java.net.SocketAddress; + /** * Handles or intercepts a downstream {@link ChannelEvent}, and fires a @@ -34,7 +36,42 @@ package org.jboss.netty.channel; * events. *

* In most common use case of this interface is to intercept an I/O request - * such as {@link Channel#write(Object)} and {@link Channel#close()}. + * such as {@link Channel#write(Object)} and {@link Channel#close()}. The + * reveived {@link ChannelEvent} object is interpreted as described in the + * following table: + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
Event type and conditionInterperatation
{@link MessageEvent}Send a message to the {@link Channel}.
{@link ChannelStateEvent}
(state={@link ChannelState#BOUND}, value={@link SocketAddress})		Bind the {@link Channel} to the specified local address.
{@link ChannelStateEvent}
(state={@link ChannelState#BOUND}, value={@code null})		Unbind the {@link Channel} from the current local address.
{@link ChannelStateEvent}
(state={@link ChannelState#CONNECTED}, value={@link SocketAddress})		Connect the {@link Channel} to the specified remote address.
{@link ChannelStateEvent}
(state={@link ChannelState#CONNECTED}, value={@code null})		Disconnect the {@link Channel} from the current remote address.
{@link ChannelStateEvent}
(state={@link ChannelState#OPEN}, value={@code false})		Close the {@link Channel}.
+ *

+ * Other event types and conditions which were not addressed here will be + * ignored and discarded. You also might want to refer to {@link SimpleChannelHandler} + * to see how a {@link ChannelEvent} is interpreted when going upstream. * *

Firing an event to the previous or next handler

*

@@ -70,6 +107,9 @@ package org.jboss.netty.channel; * proper synchronization in the handler implementation. Also, please refer to * the {@link ChannelPipelineCoverage} annotation to understand the * relationship between a handler and its stateful properties. + *

+ * Also, please refer to the {@link ChannelPipelineCoverage} annotation to + * understand the relationship between a handler and its stateful properties. * * @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/ChannelHandler.java b/src/main/java/org/jboss/netty/channel/ChannelHandler.java index 8a5a88ef0b..e70bd59628 100644 --- a/src/main/java/org/jboss/netty/channel/ChannelHandler.java +++ b/src/main/java/org/jboss/netty/channel/ChannelHandler.java @@ -35,7 +35,7 @@ package org.jboss.netty.channel; * a {@link ChannelEvent} fired by an I/O thread. *

  • {@link ChannelDownstreamHandler} handles and intercepts * a {@link ChannelEvent} fired by a user via the methods in - * the {@link Channel} interface and the {@link Channels} utility class.
    • + * the {@link Channel} interface and the {@link Channels} helper class. * * * @author The Netty Project (netty-dev@lists.jboss.org) diff --git a/src/main/java/org/jboss/netty/channel/ChannelState.java b/src/main/java/org/jboss/netty/channel/ChannelState.java index 18035faaff..ccca3580ea 100644 --- a/src/main/java/org/jboss/netty/channel/ChannelState.java +++ b/src/main/java/org/jboss/netty/channel/ChannelState.java @@ -22,7 +22,42 @@ */ package org.jboss.netty.channel; +import java.net.SocketAddress; + /** + * Represents the current state of a {@link Channel} combined with the + * {@linkplain ChannelStateEvent#getValue() value} of a {@link ChannelStateEvent}. + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
    StateValueDescription
    {@link #OPEN}{@code true}The channel is open.
    {@link #OPEN}{@code false}The channel is closed.
    {@link #BOUND}{@link SocketAddress}The channel is bound to a local address.
    {@link #BOUND}{@code null}The channel is unbound to a local address.
    {@link #CONNECTED}{link SocketAddress}The channel is connected to a remote address.
    {@link #CONNECTED}{@code null}The channel is disconnected from a remote address.
    {@link #INTEREST_OPS}an integerThe channel interestOps has been changed.
    + *

    + * To see how a {@link ChannelEvent} is interpreted further, please refer to + * {@link SimpleChannelHandler} and {@link ChannelDownstreamHandler}. + * * * @author The Netty Project (netty-dev@lists.jboss.org) * @author Trustin Lee (tlee@redhat.com) @@ -30,8 +65,25 @@ package org.jboss.netty.channel; * @version $Rev$, $Date$ */ public enum ChannelState { + /** + * Represents a {@link Channel}'s {@link Channel#isOpen() open} property + */ OPEN, + + /** + * Represents a {@link Channel}'s {@link Channel#isBound() bound} property + */ BOUND, + + /** + * Represents a {@link Channel}'s {@link Channel#isConnected() connected} + * property + */ CONNECTED, + + /** + * Represents a {@link Channel}'s {@link Channel#getInterestOps() interestOps} + * property + */ INTEREST_OPS, } diff --git a/src/main/java/org/jboss/netty/channel/ChannelUpstreamHandler.java b/src/main/java/org/jboss/netty/channel/ChannelUpstreamHandler.java index 814b6605fb..56b7d22e76 100644 --- a/src/main/java/org/jboss/netty/channel/ChannelUpstreamHandler.java +++ b/src/main/java/org/jboss/netty/channel/ChannelUpstreamHandler.java @@ -77,7 +77,7 @@ import org.jboss.netty.handler.execution.OrderedMemoryAwareThreadPoolExecutor; * Please note that this doesn't necessarily mean that there's a dedicated * thread per {@link Channel}; the I/O thread of some transport can serve more * than one {@link Channel} (e.g. NIO transport), while the I/O thread of - * others can serve only one (e.g. OIO transport). + * other transports can serve only one (e.g. OIO transport). *

    * If an {@link ExecutionHandler} is added in the {@link ChannelPipeline}, * {@link #handleUpstream(ChannelHandlerContext, ChannelEvent) handleUpstream} diff --git a/src/main/java/org/jboss/netty/channel/Channels.java b/src/main/java/org/jboss/netty/channel/Channels.java index 8e6717f368..dfeef8a5af 100644 --- a/src/main/java/org/jboss/netty/channel/Channels.java +++ b/src/main/java/org/jboss/netty/channel/Channels.java @@ -27,6 +27,8 @@ import java.util.Map; /** + * Provides various factory methods related with {@link Channel} and + * {@link ChannelPipeline}, and fires an I/O event and request. * * @author The Netty Project (netty-dev@lists.jboss.org) * @author Trustin Lee (tlee@redhat.com) @@ -39,10 +41,19 @@ public class Channels { // pipeline factory methods + /** + * Creates a new {@link ChannelPipeline}. + */ public static ChannelPipeline pipeline() { return new DefaultChannelPipeline(); } + /** + * Creates a new {@link ChannelPipeline} which contains the same entries + * with the specified {@code pipeline}. Please note that only the names + * and the references of the {@link ChannelHandler}s will be copied; a new + * {@link ChannelHandler} instance will never be created. + */ public static ChannelPipeline pipeline(ChannelPipeline pipeline) { ChannelPipeline newPipeline = pipeline(); for (Map.Entry e: pipeline.toMap().entrySet()) { @@ -51,6 +62,13 @@ public class Channels { return newPipeline; } + /** + * Creates a new {@link ChannelPipelineFactory} which creates a new + * {@link ChannelPipeline} which contains the same entries with the + * specified {@code pipeline}. Please note that only the names and the + * references of the {@link ChannelHandler}s will be copied; a new + * {@link ChannelHandler} instance will never be created. + */ public static ChannelPipelineFactory pipelineFactory( final ChannelPipeline pipeline) { return new ChannelPipelineFactory() { @@ -62,14 +80,28 @@ public class Channels { // future factory methods + /** + * Creates a new uncancellable {@link ChannelFuture} for the specified + * {@link Channel}. + */ public static ChannelFuture future(Channel channel) { return future(channel, false); } + /** + * Creates a new {@link ChannelFuture} for the specified {@link Channel}. + * + * @param cancellable {@code true} if and only if the returned future + * can be canceled by {@link ChannelFuture#cancel()} + */ public static ChannelFuture future(Channel channel, boolean cancellable) { return new DefaultChannelFuture(channel, cancellable); } + /** + * Creates a new {@link ChannelFuture} which is already succeeded for the + * specified {@link Channel}. + */ public static ChannelFuture succeededFuture(Channel channel) { if (channel instanceof AbstractChannel) { return ((AbstractChannel) channel).getSucceededFuture(); @@ -78,22 +110,56 @@ public class Channels { } } + /** + * Creates a new {@link ChannelFuture} which is already failed for the + * specified {@link Channel}. + * + * @param cause the cause of the failure + */ public static ChannelFuture failedFuture(Channel channel, Throwable cause) { return new FailedChannelFuture(channel, cause); } // event factory methods + /** + * Creates a new {@link MessageEvent} + * + * @param channel the channel which is associated with the event + * @param future the future which will be notified when a message is sent + * (only meaningful when the event is sent downstream) + * @param message the received or sent message object + * ('received' when the event is sent upstream, and + * 'sent' when the event is sent downstream) + */ public static MessageEvent messageEvent(Channel channel, ChannelFuture future, Object message) { return messageEvent(channel, future, message, null); } + /** + * Creates a new {@link MessageEvent} + * + * @param channel the channel which is associated with the event + * @param future the future which will be notified when a message is sent + * (only meaningful when the event is sent downstream) + * @param message the received or sent message object + * ('received' when the event is sent upstream, and + * 'sent' when the event is sent downstream) + * @param remoteAddress the source or destination address of the message + * ('source' when the event is sent upstream, and + * 'destination' when the event is sent downstream) + */ public static MessageEvent messageEvent(Channel channel, ChannelFuture future, Object message, SocketAddress remoteAddress) { return new DefaultMessageEvent(channel, future, message, remoteAddress); } // event emission methods + /** + * Fires a {@link SimpleChannelHandler channelOpen} event to the specified + * {@link Channel}. If the specified channel has a parent, a + * {@link SimpleChannelHandler childChannelOpen} event will be fired too. + */ public static void fireChannelOpen(Channel channel) { if (channel.getParent() != null) { fireChildChannelStateChanged(channel.getParent(), channel); @@ -104,6 +170,12 @@ public class Channels { ChannelState.OPEN, Boolean.TRUE)); } + /** + * Fires a {@link SimpleChannelHandler channelOpen} event to the specified + * {@link ChannelHandlerContext}. Please note that this method doesn't + * fire a {@link SimpleChannelHandler childChannelOpen} event unlike + * {@link #fireChannelOpen(Channel)} method. + */ public static void fireChannelOpen( ChannelHandlerContext ctx, Channel channel) { @@ -112,6 +184,13 @@ public class Channels { ChannelState.OPEN, Boolean.TRUE)); } + /** + * Fires a {@link SimpleChannelHandler channelBound} event to the specified + * {@link Channel}. + * + * @param localAddress + * the local address where the specified channel is bound + */ public static void fireChannelBound(Channel channel, SocketAddress localAddress) { channel.getPipeline().sendUpstream( new DefaultChannelStateEvent( @@ -119,6 +198,13 @@ public class Channels { ChannelState.BOUND, localAddress)); } + /** + * Fires a {@link SimpleChannelHandler channelBound} event to the specified + * {@link Channel}. + * + * @param localAddress + * the local address where the specified channel is bound + */ public static void fireChannelBound( ChannelHandlerContext ctx, Channel channel, SocketAddress localAddress) { @@ -336,6 +422,13 @@ public class Channels { channel, future, ChannelState.CONNECTED, null)); } + /** + * Sends a close request to the specified {@link Channel}. + * + * @param channel the channel to close + * + * @return the future which will be notified on closure + */ public static ChannelFuture close(Channel channel) { ChannelFuture future = future(channel); channel.getPipeline().sendDownstream(new DefaultChannelStateEvent( @@ -343,6 +436,18 @@ public class Channels { return future; } + /** + * Sends a close request to the specified {@link ChannelHandlerContext}. + * This method is a shortcut to the following code: + * 

    +     * ctx.sendDownstream(new DefaultChannelStateEvent(
+     *         channel, future, ChannelState.OPEN, Boolean.FALSE));
+     *
    + * + * @param ctx the context + * @param channel the channel to close + * @param future the future which will be notified on closure + */ public static void close( ChannelHandlerContext ctx, Channel channel, ChannelFuture future) { ctx.sendDownstream(new DefaultChannelStateEvent( diff --git a/src/main/java/org/jboss/netty/channel/CompleteChannelFuture.java b/src/main/java/org/jboss/netty/channel/CompleteChannelFuture.java index 3f87b5b4c1..fa5297093b 100644 --- a/src/main/java/org/jboss/netty/channel/CompleteChannelFuture.java +++ b/src/main/java/org/jboss/netty/channel/CompleteChannelFuture.java @@ -28,7 +28,7 @@ import org.jboss.netty.logging.InternalLogger; import org.jboss.netty.logging.InternalLoggerFactory; /** - * Skeletal {@link ChannelFuture} implementation which represents a future + * A skeletal {@link ChannelFuture} implementation which represents a future * which is complete (done) already. * * @author The Netty Project (netty-dev@lists.jboss.org) diff --git a/src/main/java/org/jboss/netty/channel/DefaultChannelEvent.java b/src/main/java/org/jboss/netty/channel/DefaultChannelEvent.java index 1a0fda46be..3d36bcdbf9 100644 --- a/src/main/java/org/jboss/netty/channel/DefaultChannelEvent.java +++ b/src/main/java/org/jboss/netty/channel/DefaultChannelEvent.java @@ -22,6 +22,15 @@ */ package org.jboss.netty.channel; +/** + * The default {@link ChannelEvent} implementation. + * + * @author The Netty Project (netty-dev@lists.jboss.org) + * @author Trustin Lee (tlee@redhat.com) + * + * @version $Rev$, $Date$ + * + */ public class DefaultChannelEvent implements ChannelEvent { private final Channel channel; diff --git a/src/main/java/org/jboss/netty/channel/DefaultChannelFuture.java b/src/main/java/org/jboss/netty/channel/DefaultChannelFuture.java index daa0a35f35..17eeed0353 100644 --- a/src/main/java/org/jboss/netty/channel/DefaultChannelFuture.java +++ b/src/main/java/org/jboss/netty/channel/DefaultChannelFuture.java @@ -30,7 +30,10 @@ import org.jboss.netty.logging.InternalLogger; import org.jboss.netty.logging.InternalLoggerFactory; /** - * The default {@link ChannelFuture} implementation. + * The default {@link ChannelFuture} implementation. It is recommended to + * use {@link Channels#future(Channel)} and {@link Channels#future(Channel, boolean)} + * to create a new {@link ChannelFuture} rather than calling the constructor + * explicitly. * * @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/DefaultChannelPipeline.java b/src/main/java/org/jboss/netty/channel/DefaultChannelPipeline.java index 0fb651f40e..dd96dd184e 100644 --- a/src/main/java/org/jboss/netty/channel/DefaultChannelPipeline.java +++ b/src/main/java/org/jboss/netty/channel/DefaultChannelPipeline.java @@ -33,7 +33,17 @@ import java.util.NoSuchElementException; import org.jboss.netty.logging.InternalLogger; import org.jboss.netty.logging.InternalLoggerFactory; - +/** + * The default {@link ChannelPipeline} implementation. It is recommended + * to use {@link Channels#pipeline()} to create a new {@link ChannelPipeline} + * instance rather than calling the constructor directly. + * + * @author The Netty Project (netty-dev@lists.jboss.org) + * @author Trustin Lee (tlee@redhat.com) + * + * @version $Rev$, $Date$ + * + */ public class DefaultChannelPipeline implements ChannelPipeline { static final InternalLogger logger = InternalLoggerFactory.getInstance(DefaultChannelPipeline.class); diff --git a/src/main/java/org/jboss/netty/channel/DefaultChannelStateEvent.java b/src/main/java/org/jboss/netty/channel/DefaultChannelStateEvent.java index 8127702f65..bbcf1c0d53 100644 --- a/src/main/java/org/jboss/netty/channel/DefaultChannelStateEvent.java +++ b/src/main/java/org/jboss/netty/channel/DefaultChannelStateEvent.java @@ -22,6 +22,15 @@ */ package org.jboss.netty.channel; +/** + * The default {@link ChannelStateEvent} implementation. + * + * @author The Netty Project (netty-dev@lists.jboss.org) + * @author Trustin Lee (tlee@redhat.com) + * + * @version $Rev$, $Date$ + * + */ public class DefaultChannelStateEvent extends DefaultChannelEvent implements ChannelStateEvent { diff --git a/src/main/java/org/jboss/netty/channel/DefaultChildChannelStateEvent.java b/src/main/java/org/jboss/netty/channel/DefaultChildChannelStateEvent.java index 6897dda8fb..09c7f7426e 100644 --- a/src/main/java/org/jboss/netty/channel/DefaultChildChannelStateEvent.java +++ b/src/main/java/org/jboss/netty/channel/DefaultChildChannelStateEvent.java @@ -22,6 +22,15 @@ */ package org.jboss.netty.channel; +/** + * The default {@link ChildChannelStateEvent} implementation. + * + * @author The Netty Project (netty-dev@lists.jboss.org) + * @author Trustin Lee (tlee@redhat.com) + * + * @version $Rev$, $Date$ + * + */ public class DefaultChildChannelStateEvent extends DefaultChannelEvent implements ChildChannelStateEvent { diff --git a/src/main/java/org/jboss/netty/channel/DefaultExceptionEvent.java b/src/main/java/org/jboss/netty/channel/DefaultExceptionEvent.java index 91e31ba886..cbeaf68e80 100644 --- a/src/main/java/org/jboss/netty/channel/DefaultExceptionEvent.java +++ b/src/main/java/org/jboss/netty/channel/DefaultExceptionEvent.java @@ -24,7 +24,15 @@ package org.jboss.netty.channel; import org.jboss.netty.util.StackTraceSimplifier; - +/** + * The default {@link ExceptionEvent} implementation. + * + * @author The Netty Project (netty-dev@lists.jboss.org) + * @author Trustin Lee (tlee@redhat.com) + * + * @version $Rev$, $Date$ + * + */ public class DefaultExceptionEvent extends DefaultChannelEvent implements ExceptionEvent { diff --git a/src/main/java/org/jboss/netty/channel/DefaultMessageEvent.java b/src/main/java/org/jboss/netty/channel/DefaultMessageEvent.java index 30adb6eb7b..f55974e9da 100644 --- a/src/main/java/org/jboss/netty/channel/DefaultMessageEvent.java +++ b/src/main/java/org/jboss/netty/channel/DefaultMessageEvent.java @@ -24,6 +24,19 @@ package org.jboss.netty.channel; import java.net.SocketAddress; +/** + * The default {@link MessageEvent} implementation. It is recommended to + * use {@link Channels#messageEvent(Channel, ChannelFuture, Object)} and + * {@link Channels#messageEvent(Channel, ChannelFuture, Object, SocketAddress)} + * to create a new {@link MessageEvent} instance rather than calling the + * constructor explicitly. + * + * @author The Netty Project (netty-dev@lists.jboss.org) + * @author Trustin Lee (tlee@redhat.com) + * + * @version $Rev$, $Date$ + * + */ public class DefaultMessageEvent extends DefaultChannelEvent implements MessageEvent { diff --git a/src/main/java/org/jboss/netty/channel/SimpleChannelHandler.java b/src/main/java/org/jboss/netty/channel/SimpleChannelHandler.java index 93a0c3f439..d637dd424f 100644 --- a/src/main/java/org/jboss/netty/channel/SimpleChannelHandler.java +++ b/src/main/java/org/jboss/netty/channel/SimpleChannelHandler.java @@ -22,6 +22,8 @@ */ package org.jboss.netty.channel; +import java.net.SocketAddress; + import org.jboss.netty.buffer.ChannelBuffer; import org.jboss.netty.channel.socket.ServerSocketChannel; import org.jboss.netty.logging.InternalLogger; @@ -29,14 +31,14 @@ import org.jboss.netty.logging.InternalLoggerFactory; /** - * Generic {@link ChannelUpstreamHandler} implementation that satisfies most + * A generic {@link ChannelUpstreamHandler} implementation that satisfies most * use cases. This handler down-casts the received upstream event into more * meaningful sub-type event and calls an appropriate handler method with the * down-casted event. The following table shows the provided handler methods: * * * - * + * * * * @@ -50,42 +52,37 @@ import org.jboss.netty.logging.InternalLoggerFactory; * * * - * - * - * - * - * - * + * * * * * - * + * * * * * - * + * * * * * - * + * * * * * - * + * * * * * - * + * * * * * - * + * * * *
    Handler methodEvent typeInvoked when ...Handler methodEvent type and conditionInvoked when ...
    {@link #messageReceived(ChannelHandlerContext, MessageEvent) messageReceived}
    {@link #channelOpen(ChannelHandlerContext, ChannelStateEvent) channelOpen}{@link ChannelStateEvent}a {@link Channel} is open, but not bound nor connected
    {@link #channelOpen(ChannelHandlerContext, ChannelStateEvent) channelOpen}{@link ChannelStateEvent}{@link ChannelStateEvent}
    (state={@link ChannelState#OPEN}, value={@code true})    		a {@link Channel} is open, but not bound nor connected
    {@link #channelBound(ChannelHandlerContext, ChannelStateEvent) channelBound}{@link ChannelStateEvent}{@link ChannelStateEvent}
    (state={@link ChannelState#BOUND}, value={@link SocketAddress})    		a {@link Channel} is open and bound to a local address, but not connected
    {@link #channelConnected(ChannelHandlerContext, ChannelStateEvent) channelConnected}{@link ChannelStateEvent}{@link ChannelStateEvent}
    (state={@link ChannelState#CONNECTED}, value={@link SocketAddress})    		a {@link Channel} is open, bound to a local address, and connected to a remote address
    {@link #channelInterestChanged(ChannelHandlerContext, ChannelStateEvent) channelInterestedChanged}{@link ChannelStateEvent}{@link ChannelStateEvent}
    (state={@link ChannelState#INTEREST_OPS}, value=an integer)    		a {@link Channel}'s {@link Channel#getInterestOps() interestOps} was changed
    {@link #channelDisconnected(ChannelHandlerContext, ChannelStateEvent) channelDisconnected}{@link ChannelStateEvent}{@link ChannelStateEvent}
    (state={@link ChannelState#CONNECTED}, value={@code null})    		a {@link Channel} was disconnected from its remote peer
    {@link #channelUnbound(ChannelHandlerContext, ChannelStateEvent) channelUnbound}{@link ChannelStateEvent}{@link ChannelStateEvent}
    (state={@link ChannelState#BOUND}, value={@code null})    		a {@link Channel} was unbound from the current local address
    {@link #channelClosed(ChannelHandlerContext, ChannelStateEvent) channelClosed}{@link ChannelStateEvent}{@link ChannelStateEvent}
    (state={@link ChannelState#OPEN}, value={@code false})    		a {@link Channel} was closed and all its related resources were released
    @@ -93,23 +90,25 @@ import org.jboss.netty.logging.InternalLoggerFactory; *

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

    * * * - * + * * * * - * + * * * * * - * + * * * *
    Handler methodEvent typeInvoked when ...Handler methodEvent type and conditionInvoked when ...
    {@link #childChannelOpen(ChannelHandlerContext, ChildChannelStateEvent) childChannelOpen}{@link ChildChannelStateEvent}{@link ChildChannelStateEvent}
    ({@code childChannel.isOpen() = true})    		a child {@link Channel} was open (e.g. a server channel accepted a connection.)
    {@link #childChannelClosed(ChannelHandlerContext, ChildChannelStateEvent) childChannelClosed}{@link ChildChannelStateEvent}{@link ChildChannelStateEvent}
    ({@code childChannel.isOpen() = false})    		a child {@link Channel} was closed (e.g. the accepted connection was closed.)
    + *

    + * You also might want to refer to {@link ChannelDownstreamHandler} to see + * how a {@link ChannelEvent} is interpreted when going downstream. * *

    Overriding {@link #handleUpstream(ChannelHandlerContext, ChannelEvent) handleUpstream} method

    *