From ea3d3042061e18bcb01980b45903f9631c6d0d3f Mon Sep 17 00:00:00 2001 From: Norman Maurer Date: Tue, 28 Aug 2012 01:14:05 +0200 Subject: [PATCH] Some javadocs love --- .../main/java/io/netty/channel/Channel.java | 82 ++++++++++++ .../java/io/netty/channel/ChannelConfig.java | 6 + .../netty/channel/ChannelFutureFactory.java | 20 +++ .../java/io/netty/channel/ChannelHandler.java | 22 ++++ .../netty/channel/ChannelHandlerContext.java | 118 ++++++++++++++++++ .../io/netty/channel/ChannelHandlerType.java | 7 ++ .../channel/ChannelInboundByteHandler.java | 4 + .../ChannelInboundByteHandlerAdapter.java | 15 +++ .../netty/channel/ChannelInboundHandler.java | 6 + .../channel/ChannelInboundHandlerAdapter.java | 4 + .../channel/ChannelInboundMessageHandler.java | 7 ++ .../io/netty/channel/ChannelStateHandler.java | 11 ++ 12 files changed, 302 insertions(+) diff --git a/transport/src/main/java/io/netty/channel/Channel.java b/transport/src/main/java/io/netty/channel/Channel.java index ea4c6ad448..87dce2ef7f 100755 --- a/transport/src/main/java/io/netty/channel/Channel.java +++ b/transport/src/main/java/io/netty/channel/Channel.java @@ -26,6 +26,8 @@ import java.net.InetSocketAddress; import java.net.SocketAddress; import java.nio.channels.SelectionKey; +import sun.awt.windows.ThemeReader; + /** * A nexus to a network socket or a component which is capable of I/O @@ -113,6 +115,9 @@ public interface Channel extends AttributeMap, ChannelOutboundInvoker, ChannelFu */ Integer id(); + /** + * Return the {@link EventLoop} this {@link Channel} was registered too. + */ EventLoop eventLoop(); /** @@ -138,6 +143,9 @@ public interface Channel extends AttributeMap, ChannelOutboundInvoker, ChannelFu boolean isRegistered(); boolean isActive(); + /** + * Return the {@link ChannelMetadata} of the {@link Channel} which describe the nature of the {@link Channel}. + */ ChannelMetadata metadata(); ByteBuf outboundByteBuffer(); @@ -176,25 +184,99 @@ public interface Channel extends AttributeMap, ChannelOutboundInvoker, ChannelFu */ ChannelFuture closeFuture(); + /** + * Caution for transport implementations use only! + */ Unsafe unsafe(); + /** + * Unsafe operations that should never be called + * from user-code. These methods are only provided to implement the actual transport. + */ interface Unsafe { + /** + * Return the {@link ChannelHandlerContext} which is directly connected to the outbound of the + * underlying transport. + */ ChannelHandlerContext directOutboundContext(); + + /** + * Return a {@link VoidChannelFuture}. This method always return the same instance. + */ ChannelFuture voidFuture(); + /** + * Return the {@link SocketAddress} to which is bound local or + * null if none. + */ SocketAddress localAddress(); + + /** + * Return the {@link SocketAddress} to which is bound remote or + * null if none is bound yet. + */ SocketAddress remoteAddress(); + /** + * Register the {@link Channel} of the {@link ChannelFuture} with the {@link EventLoop} and notify + * the {@link ChannelFuture} once the registration was complete. + */ void register(EventLoop eventLoop, ChannelFuture future); + + /** + * Bind the {@link SocketAddress} to the {@link Channel} of the {@link ChannelFuture} and notify + * it once its done. + */ void bind(SocketAddress localAddress, ChannelFuture future); + + /** + * Connect the {@link Channel} of the given {@link ChannelFuture} with the given remote {@link SocketAddress}. + * If a specific local {@link SocketAddress} should be used it need to be given as argument. Otherwise just + * pass null to it. + * + * The {@link ChannelFuture} will get notified once the connect operation was complete. + */ void connect(SocketAddress remoteAddress, SocketAddress localAddress, ChannelFuture future); + + /** + * Disconnect the {@link Channel} of the {@link ChannelFuture} and notify the {@link ChannelFuture} once the + * operation was complete. + */ void disconnect(ChannelFuture future); + + /** + * Close the {@link Channel} of the {@link ChannelFuture} and notify the {@link ChannelFuture} once the + * operation was complete. + */ void close(ChannelFuture future); + + /** + * Deregister the {@link Channel} of the {@link ChannelFuture} from {@link EventLoop} and notify the + * {@link ChannelFuture} once the operation was complete. + */ void deregister(ChannelFuture future); + /** + * Flush out all data that was buffered in the buffer of the {@link #directOutboundContext()} and was not + * flushed out yet. After that is done the {@link ChannelFuture} will get notified + */ void flush(ChannelFuture future); + + /** + * Flush out all data now. + */ void flushNow(); + + /** + * Suspend reads from the underlying transport, which basicly has the effect of no new data that will + * get dispatched. + */ void suspendRead(); + + /** + * Resume reads from the underlying transport. If {@link #suspendRead()} was not called before, this + * has no effect. + */ void resumeRead(); } } diff --git a/transport/src/main/java/io/netty/channel/ChannelConfig.java b/transport/src/main/java/io/netty/channel/ChannelConfig.java index a015eacb94..f732780ab4 100644 --- a/transport/src/main/java/io/netty/channel/ChannelConfig.java +++ b/transport/src/main/java/io/netty/channel/ChannelConfig.java @@ -60,6 +60,9 @@ import java.util.Map; */ public interface ChannelConfig { + /** + * Return all set {@link ChannelOption}'s. + */ Map, Object> getOptions(); /** @@ -67,6 +70,9 @@ public interface ChannelConfig { */ boolean setOptions(Map, ?> options); + /** + * Return the value of the given {@link ChannelOption} + */ T getOption(ChannelOption option); /** diff --git a/transport/src/main/java/io/netty/channel/ChannelFutureFactory.java b/transport/src/main/java/io/netty/channel/ChannelFutureFactory.java index 5e46bc9a0d..5157c93385 100644 --- a/transport/src/main/java/io/netty/channel/ChannelFutureFactory.java +++ b/transport/src/main/java/io/netty/channel/ChannelFutureFactory.java @@ -15,8 +15,28 @@ */ package io.netty.channel; +/** + * Factory which is responsible to create new {@link ChannelFuture}'s + * + */ public interface ChannelFutureFactory { + + /** + * Create a new {@link ChannelFuture} + */ ChannelFuture newFuture(); + + /** + * Create a new {@link ChannelFuture} which is marked as successes already. So {@link ChannelFuture#isSuccess()} + * will return true. All {@link ChannelFutureListener} added to it will be notified directly. Also + * every call of blocking methods will just return without blocking. + */ ChannelFuture newSucceededFuture(); + + /** + * Create a new {@link ChannelFuture} which is marked as fakued already. So {@link ChannelFuture#isSuccess()} + * will return false. All {@link ChannelFutureListener} added to it will be notified directly. Also + * every call of blocking methods will just return without blocking. + */ ChannelFuture newFailedFuture(Throwable cause); } diff --git a/transport/src/main/java/io/netty/channel/ChannelHandler.java b/transport/src/main/java/io/netty/channel/ChannelHandler.java index f5c8d78f74..358c413d90 100644 --- a/transport/src/main/java/io/netty/channel/ChannelHandler.java +++ b/transport/src/main/java/io/netty/channel/ChannelHandler.java @@ -208,12 +208,34 @@ import java.nio.channels.Channels; */ public interface ChannelHandler { + /** + * Gets called before the {@link ChannelHandler} is added to the actual context. + */ void beforeAdd(ChannelHandlerContext ctx) throws Exception; + + /** + * Gets called after the {@link ChannelHandler} was added to the actual context. + */ void afterAdd(ChannelHandlerContext ctx) throws Exception; + + /** + * Gets called before the {@link ChannelHandler} is removed from the actual context. + */ void beforeRemove(ChannelHandlerContext ctx) throws Exception; + + /** + * Gets called after the {@link ChannelHandler} was removed from the actual context. + */ void afterRemove(ChannelHandlerContext ctx) throws Exception; + /** + * Gets called if a {@link Throwable} was thrown. + */ void exceptionCaught(ChannelHandlerContext ctx, Throwable cause) throws Exception; + + /** + * Gets called if an user event was triggered. + */ void userEventTriggered(ChannelHandlerContext ctx, Object evt) throws Exception; /** diff --git a/transport/src/main/java/io/netty/channel/ChannelHandlerContext.java b/transport/src/main/java/io/netty/channel/ChannelHandlerContext.java index 209ce06275..85750c7ada 100755 --- a/transport/src/main/java/io/netty/channel/ChannelHandlerContext.java +++ b/transport/src/main/java/io/netty/channel/ChannelHandlerContext.java @@ -128,34 +128,152 @@ import java.util.Set; public interface ChannelHandlerContext extends AttributeMap, ChannelFutureFactory, ChannelInboundInvoker, ChannelOutboundInvoker { + + /** + * Return the {@link Channel} which is bound to the {@link ChannelHandlerContext}. + */ Channel channel(); + + /** + * Return the {@link ChannelPipeline} which belongs this {@link ChannelHandlerContext}. + */ ChannelPipeline pipeline(); + + /** + * The {@link EventExecutor} that is used to dispatch the events. This can also be used to directly + * submit tasks that get executed in the event loop. For more informations please refer to the + * {@link EventExecutor} javadocs. + */ EventExecutor executor(); + /** + * The unique name of the {@link ChannelHandlerContext}.The name was used when then {@link ChannelHandler} + * was added to the {@link ChannelPipeline}. This name can also be used to access the registered + * {@link ChannelHandler} from the {@link ChannelPipeline}. + */ String name(); + + /** + * The {@link ChannelHandler} that is bound this {@link ChannelHandlerContext}. + */ ChannelHandler handler(); Set type(); + /** + * Return true if the {@link ChannelHandlerContext} has an {@link ByteBuf} bound for inbound + * which can be used. + */ boolean hasInboundByteBuffer(); + + /** + * Return true if the {@link ChannelHandlerContext} has a {@link MessageBuf} bound for inbound + * which can be used. + */ boolean hasInboundMessageBuffer(); + + /** + * Return the bound {@link ByteBuf} for inbound data if {@link #hasInboundByteBuffer()} returned + * true. If {@link #hasInboundByteBuffer()} returned false it will throw a + * {@link UnsupportedOperationException} + */ ByteBuf inboundByteBuffer(); + + /** + * Return the bound {@link MessageBuf} for inbound data if {@link #hasInboundMessageBuffer()} returned + * true. If {@link #hasInboundMessageBuffer()} returned false it will throw a + * {@link UnsupportedOperationException}. + */ MessageBuf inboundMessageBuffer(); + /** + * Return true if the {@link ChannelHandlerContext} has an {@link ByteBuf} bound for outbound + * data which can be used. + * + */ boolean hasOutboundByteBuffer(); + + /** + * Return true if the {@link ChannelHandlerContext} has a {@link MessageBuf} bound for outbound + * which can be used. + */ boolean hasOutboundMessageBuffer(); + + /** + * Return the bound {@link ByteBuf} for outbound data if {@link #hasOutboundByteBuffer()} returned + * true. If {@link #hasOutboundByteBuffer()} returned false it will throw + * a {@link UnsupportedOperationException}. + */ ByteBuf outboundByteBuffer(); + + /** + * Return the bound {@link MessageBuf} for outbound data if {@link #hasOutboundMessageBuffer()} returned + * true. If {@link #hasOutboundMessageBuffer()} returned false it will throw a + * {@link UnsupportedOperationException} + */ MessageBuf outboundMessageBuffer(); + /** + * Return true if the next {@link ChannelHandlerContext} has a {@link ByteBuf} for handling + * inbound data. + */ boolean hasNextInboundByteBuffer(); + + /** + * Return true if the next {@link ChannelHandlerContext} has a {@link MessageBuf} for handling + * inbound data. + */ boolean hasNextInboundMessageBuffer(); + + /** + * Return the {@link ByteBuf} of the next {@link ChannelHandlerContext} if {@link #hasNextInboundByteBuffer()} + * returned true, otherwise a {@link UnsupportedOperationException} is thrown. + */ ByteBuf nextInboundByteBuffer(); + + /** + * Return the {@link MessageBuf} of the next {@link ChannelHandlerContext} if + * {@link #hasNextInboundMessageBuffer()} returned true, otherwise a + * {@link UnsupportedOperationException} is thrown. + */ MessageBuf nextInboundMessageBuffer(); + /** + * Return true if the next {@link ChannelHandlerContext} has a {@link ByteBuf} for handling outbound + * data. + */ boolean hasNextOutboundByteBuffer(); + + /** + * Return true if the next {@link ChannelHandlerContext} has a {@link MessageBuf} for handling + * outbound data. + */ boolean hasNextOutboundMessageBuffer(); + + /** + * Return the {@link ByteBuf} of the next {@link ChannelHandlerContext} if {@link #hasNextOutboundByteBuffer()} + * returned true, otherwise a {@link UnsupportedOperationException} is thrown. + */ ByteBuf nextOutboundByteBuffer(); + + /** + * Return the {@link MessageBuf} of the next {@link ChannelHandlerContext} if + * {@link #hasNextOutboundMessageBuffer()} returned true, otherwise a + * {@link UnsupportedOperationException} is thrown. + */ MessageBuf nextOutboundMessageBuffer(); + /** + * Return true if the {@link ChannelHandlerContext} was marked as readable. This basically means + * that once its not readable anymore no new data will be read from the transport and passed down the + * {@link ChannelPipeline}. + * + * Only if all {@link ChannelHandlerContext}'s {@link #isReadable()} return true, the data is + * passed again down the {@link ChannelPipeline}. + */ boolean isReadable(); + + /** + * Mark the {@link ChannelHandlerContext} as readable or suspend it. See {@link #isReadable()} + */ void readable(boolean readable); } diff --git a/transport/src/main/java/io/netty/channel/ChannelHandlerType.java b/transport/src/main/java/io/netty/channel/ChannelHandlerType.java index 6ac2f07116..fe037825ba 100644 --- a/transport/src/main/java/io/netty/channel/ChannelHandlerType.java +++ b/transport/src/main/java/io/netty/channel/ChannelHandlerType.java @@ -15,6 +15,10 @@ */ package io.netty.channel; +/** + * Define the type of a {@link ChannelHandler} + * + */ public enum ChannelHandlerType { STATE(0), INBOUND(0), @@ -24,6 +28,9 @@ public enum ChannelHandlerType { final int direction; // 0 - up (inbound), 1 - down (outbound) ChannelHandlerType(int direction) { + if (direction != 0 && direction != 1) { + throw new IllegalArgumentException("direction must be either 0 or 1"); + } this.direction = direction; } } diff --git a/transport/src/main/java/io/netty/channel/ChannelInboundByteHandler.java b/transport/src/main/java/io/netty/channel/ChannelInboundByteHandler.java index b9d42d0ea1..ec0afbab3c 100644 --- a/transport/src/main/java/io/netty/channel/ChannelInboundByteHandler.java +++ b/transport/src/main/java/io/netty/channel/ChannelInboundByteHandler.java @@ -17,6 +17,10 @@ package io.netty.channel; import io.netty.buffer.ByteBuf; +/** + * {@link ChannelInboundHandler} which offers a {@link ByteBuf} to store inbound data in. + * + */ public interface ChannelInboundByteHandler extends ChannelInboundHandler { @Override ByteBuf newInboundBuffer(ChannelHandlerContext ctx) throws Exception; diff --git a/transport/src/main/java/io/netty/channel/ChannelInboundByteHandlerAdapter.java b/transport/src/main/java/io/netty/channel/ChannelInboundByteHandlerAdapter.java index 85aaafbe10..dfc71df31a 100644 --- a/transport/src/main/java/io/netty/channel/ChannelInboundByteHandlerAdapter.java +++ b/transport/src/main/java/io/netty/channel/ChannelInboundByteHandlerAdapter.java @@ -19,9 +19,19 @@ import io.netty.buffer.ByteBuf; import io.netty.buffer.Unpooled; +/** + * Abstract base class for {@link ChannelInboundHandlerAdapter} which should be extended by the user to + * get notified once more data is ready to get consumed from the inbound {@link ByteBuf}. + * + * This implementation is a good starting point for must users. + */ public abstract class ChannelInboundByteHandlerAdapter extends ChannelInboundHandlerAdapter implements ChannelInboundByteHandler { + /** + * Create a new unpooled {@link ByteBuf} by default. Sub-classes may override this to offer a more + * optimized implementation. + */ @Override public ByteBuf newInboundBuffer(ChannelHandlerContext ctx) throws Exception { return Unpooled.buffer(); @@ -39,5 +49,10 @@ public abstract class ChannelInboundByteHandlerAdapter } } + /** + * Callback which will get notifed once the given {@link ByteBuf} received more data to read. What will be done + * with the data at this point is up to the implementation. + * Implementations may choose to read it or just let it in the buffer to read it later. + */ public abstract void inboundBufferUpdated(ChannelHandlerContext ctx, ByteBuf in) throws Exception; } diff --git a/transport/src/main/java/io/netty/channel/ChannelInboundHandler.java b/transport/src/main/java/io/netty/channel/ChannelInboundHandler.java index 3980f2c6c1..4efe1e96ee 100644 --- a/transport/src/main/java/io/netty/channel/ChannelInboundHandler.java +++ b/transport/src/main/java/io/netty/channel/ChannelInboundHandler.java @@ -17,6 +17,12 @@ package io.netty.channel; import io.netty.buffer.ChannelBuf; +/** + * {@link ChannelStateHandler} which handles inbound data. + */ public interface ChannelInboundHandler extends ChannelStateHandler { + /** + * Return the {@link ChannelBuf} which will be used for inbound data for the given {@link ChannelHandlerContext}. + */ ChannelBuf newInboundBuffer(ChannelHandlerContext ctx) throws Exception; } diff --git a/transport/src/main/java/io/netty/channel/ChannelInboundHandlerAdapter.java b/transport/src/main/java/io/netty/channel/ChannelInboundHandlerAdapter.java index 8f4c81763f..bdb6b6855a 100644 --- a/transport/src/main/java/io/netty/channel/ChannelInboundHandlerAdapter.java +++ b/transport/src/main/java/io/netty/channel/ChannelInboundHandlerAdapter.java @@ -18,6 +18,10 @@ package io.netty.channel; public abstract class ChannelInboundHandlerAdapter extends ChannelStateHandlerAdapter implements ChannelInboundHandler { + + /** + * Does nothing by default. Sub-classes may override this if needed. + */ @Override public abstract void inboundBufferUpdated(ChannelHandlerContext ctx) throws Exception; } diff --git a/transport/src/main/java/io/netty/channel/ChannelInboundMessageHandler.java b/transport/src/main/java/io/netty/channel/ChannelInboundMessageHandler.java index 344041b563..5217fdb958 100644 --- a/transport/src/main/java/io/netty/channel/ChannelInboundMessageHandler.java +++ b/transport/src/main/java/io/netty/channel/ChannelInboundMessageHandler.java @@ -17,7 +17,14 @@ package io.netty.channel; import io.netty.buffer.MessageBuf; +/** + * Special {@link ChannelInboundHandler} which store the inbound data in a {@link MessageBuf} for futher processing. + */ public interface ChannelInboundMessageHandler extends ChannelInboundHandler { + + /** + * Return the {@link MessageBuf} which will be used for inbound data to store. + */ @Override MessageBuf newInboundBuffer(ChannelHandlerContext ctx) throws Exception; } diff --git a/transport/src/main/java/io/netty/channel/ChannelStateHandler.java b/transport/src/main/java/io/netty/channel/ChannelStateHandler.java index d9d1823e11..f955279d93 100755 --- a/transport/src/main/java/io/netty/channel/ChannelStateHandler.java +++ b/transport/src/main/java/io/netty/channel/ChannelStateHandler.java @@ -15,12 +15,23 @@ */ package io.netty.channel; +/** + * {@link ChannelHandler} which adds callbacks for state changes. This allows the user + * to hook in to state changes easily. + */ public interface ChannelStateHandler extends ChannelHandler { + void channelRegistered(ChannelHandlerContext ctx) throws Exception; void channelUnregistered(ChannelHandlerContext ctx) throws Exception; void channelActive(ChannelHandlerContext ctx) throws Exception; void channelInactive(ChannelHandlerContext ctx) throws Exception; + /** + * The inbound buffer of the {@link ChannelHandlerContext} was updated with new data. + * This means something may be ready to get processed by the actual {@link ChannelStateHandler} + * implementation. It's up to the implementation to consume it or keep it in the buffer + * to wait for more data and consume it later. + */ void inboundBufferUpdated(ChannelHandlerContext ctx) throws Exception; }