From fc4b205bc40af225d7f706bad2aac71f5676b877 Mon Sep 17 00:00:00 2001 From: Norman Maurer Date: Sat, 22 Dec 2012 15:53:01 +0100 Subject: [PATCH] More javadocs --- .../handler/codec/MessageToByteEncoder.java | 6 +++ .../handler/codec/MessageToMessageCodec.java | 1 + .../codec/MessageToMessageDecoder.java | 2 +- .../sctp/SctpInboundByteStreamHandler.java | 4 +- .../sctp/SctpOutboundByteStreamHandler.java | 4 +- .../java/io/netty/channel/ChannelConfig.java | 6 +-- .../ChannelInboundMessageHandlerAdapter.java | 48 ++++++++++++++++++- .../java/io/netty/channel/ChannelOption.java | 18 +++++++ 8 files changed, 80 insertions(+), 9 deletions(-) diff --git a/codec/src/main/java/io/netty/handler/codec/MessageToByteEncoder.java b/codec/src/main/java/io/netty/handler/codec/MessageToByteEncoder.java index 9f7035a09c..5a5a8257a1 100644 --- a/codec/src/main/java/io/netty/handler/codec/MessageToByteEncoder.java +++ b/codec/src/main/java/io/netty/handler/codec/MessageToByteEncoder.java @@ -19,7 +19,9 @@ import io.netty.buffer.ByteBuf; import io.netty.buffer.MessageBuf; import io.netty.channel.ChannelFuture; import io.netty.channel.ChannelHandlerContext; +import io.netty.channel.ChannelOutboundMessageHandler; import io.netty.channel.ChannelOutboundMessageHandlerAdapter; +import io.netty.channel.ChannelPipeline; import io.netty.channel.ChannelHandlerUtil; @@ -44,6 +46,10 @@ public abstract class MessageToByteEncoder extends ChannelOutboundMessageHand private final Class[] acceptedMsgTypes; + /** + * The types which will be accepted by the encoder. If a received message is an other type it will be just forwared + * to the next {@link ChannelOutboundMessageHandler} in the {@link ChannelPipeline} + */ protected MessageToByteEncoder(Class... acceptedMsgTypes) { this.acceptedMsgTypes = ChannelHandlerUtil.acceptedMessageTypes(acceptedMsgTypes); } diff --git a/codec/src/main/java/io/netty/handler/codec/MessageToMessageCodec.java b/codec/src/main/java/io/netty/handler/codec/MessageToMessageCodec.java index 770a7b9875..409397b0d4 100644 --- a/codec/src/main/java/io/netty/handler/codec/MessageToMessageCodec.java +++ b/codec/src/main/java/io/netty/handler/codec/MessageToMessageCodec.java @@ -31,6 +31,7 @@ import io.netty.channel.ChannelOutboundMessageHandler; * * Here is an example of a {@link MessageToMessageCodec} which just decode from {@link Integer} to {@link Long} * and encode from {@link Long} to {@link Integer}. + * * 
  *     public class NumberCodec extends
  *             {@link MessageToMessageCodec}<{@link Integer}, {@link Long}, {@link Long}, {@link Integer}> {
diff --git a/codec/src/main/java/io/netty/handler/codec/MessageToMessageDecoder.java b/codec/src/main/java/io/netty/handler/codec/MessageToMessageDecoder.java
index bd546956a8..72b6f2c031 100644
--- a/codec/src/main/java/io/netty/handler/codec/MessageToMessageDecoder.java
+++ b/codec/src/main/java/io/netty/handler/codec/MessageToMessageDecoder.java
@@ -50,7 +50,7 @@ public abstract class MessageToMessageDecoder
     private final Class[] acceptedMsgTypes;
 
     /**
-     * The types which will be accepted by the decoder. If a received message is an other type it will be just forwared
+     * The types which will be accepted by the decoder. If a received message is an other type it will be just forwarded
      * to the next {@link ChannelInboundMessageHandler} in the {@link ChannelPipeline}
      */
     protected MessageToMessageDecoder(Class... acceptedMsgTypes) {
diff --git a/codec/src/main/java/io/netty/handler/codec/sctp/SctpInboundByteStreamHandler.java b/codec/src/main/java/io/netty/handler/codec/sctp/SctpInboundByteStreamHandler.java
index 1a557b2883..d308a3298d 100644
--- a/codec/src/main/java/io/netty/handler/codec/sctp/SctpInboundByteStreamHandler.java
+++ b/codec/src/main/java/io/netty/handler/codec/sctp/SctpInboundByteStreamHandler.java
@@ -23,8 +23,8 @@ import io.netty.channel.socket.SctpMessage;
 import io.netty.handler.codec.CodecException;
 
 /**
- * A ChannelHandler which receives  {@link SctpMessage} belongs to a application protocol form a specific SCTP Stream
- * and decode it as {@link ByteBuf}.
+ * A ChannelHandler which receives {@link SctpMessage}s which belong to a application protocol form a specific
+ * SCTP Stream  and decode it as {@link ByteBuf}.
  */
 public class SctpInboundByteStreamHandler extends ChannelInboundMessageHandlerAdapter {
     private final int protocolIdentifier;
diff --git a/codec/src/main/java/io/netty/handler/codec/sctp/SctpOutboundByteStreamHandler.java b/codec/src/main/java/io/netty/handler/codec/sctp/SctpOutboundByteStreamHandler.java
index dd40207f07..cb44c03b9c 100644
--- a/codec/src/main/java/io/netty/handler/codec/sctp/SctpOutboundByteStreamHandler.java
+++ b/codec/src/main/java/io/netty/handler/codec/sctp/SctpOutboundByteStreamHandler.java
@@ -34,8 +34,8 @@ public class SctpOutboundByteStreamHandler extends ChannelOutboundByteHandlerAda
     private final int protocolIdentifier;
 
     /**
-     * @param streamIdentifier stream number, this should be >=0 or <= max stream number of the association.
-     * @param protocolIdentifier supported application protocol id.
+     * @param streamIdentifier      stream number, this should be >=0 or <= max stream number of the association.
+     * @param protocolIdentifier    supported application protocol id.
      */
     public SctpOutboundByteStreamHandler(int streamIdentifier, int protocolIdentifier) {
         this.streamIdentifier = streamIdentifier;
diff --git a/transport/src/main/java/io/netty/channel/ChannelConfig.java b/transport/src/main/java/io/netty/channel/ChannelConfig.java
index fc30f4f04f..560c6af7b9 100644
--- a/transport/src/main/java/io/netty/channel/ChannelConfig.java
+++ b/transport/src/main/java/io/netty/channel/ChannelConfig.java
@@ -80,12 +80,12 @@ public interface ChannelConfig {
      * Sets a configuration property with the specified name and value.
      * To override this method properly, you must call the super class:
      * 
-     * public boolean setOption(String name, Object value) {
-     *     if (super.setOption(name, value)) {
+     * public boolean setOption(ChannelOption<T> option, T value) {
+     *     if (super.setOption(option, value)) {
      *         return true;
      *     }
      *
-     *     if (name.equals("additionalOption")) {
+     *     if (option.equals(additionalOption)) {
      *         ....
      *         return true;
      *     }
diff --git a/transport/src/main/java/io/netty/channel/ChannelInboundMessageHandlerAdapter.java b/transport/src/main/java/io/netty/channel/ChannelInboundMessageHandlerAdapter.java
index d9846c61fe..b41be8e9ed 100644
--- a/transport/src/main/java/io/netty/channel/ChannelInboundMessageHandlerAdapter.java
+++ b/transport/src/main/java/io/netty/channel/ChannelInboundMessageHandlerAdapter.java
@@ -18,11 +18,37 @@ package io.netty.channel;
 import io.netty.buffer.MessageBuf;
 import io.netty.buffer.Unpooled;
 
+/**
+ * {@link ChannelHandler} which handles inbound messages of a specific type.
+ *
+ * 
+ *     public class StringHandler extends
+ *             {@link ChannelInboundMessageHandlerAdapter}<{@link String}> {
+ *         public StringToIntegerDecoder() {
+ *             super(String.class);
+ *         }
+ *
+ *         {@code @Override}
+ *         public void messageReceived({@link ChannelHandlerContext} ctx, {@link String} message)
+ *                 throws {@link Exception} {
+ *             // Do something with the String
+ *             ...
+ *             ...
+ *         }
+ *     }
+ * 

+ *
+ * @param    The type of the messages to handle
+ */
 public abstract class ChannelInboundMessageHandlerAdapter
         extends ChannelInboundHandlerAdapter implements ChannelInboundMessageHandler {
 
     private final Class[] acceptedMsgTypes;
 
+    /**
+     * The types which will be accepted by the message handler. If a received message is an other type it will be just
+     * forwarded  to the next {@link ChannelInboundMessageHandler} in the {@link ChannelPipeline}.
+     */
     protected ChannelInboundMessageHandlerAdapter(Class... acceptedMsgTypes) {
         this.acceptedMsgTypes = ChannelHandlerUtil.acceptedMessageTypes(acceptedMsgTypes);
     }
@@ -92,10 +118,30 @@ public abstract class ChannelInboundMessageHandlerAdapter
      * This will return {@code true} by default, and may get overriden by sub-classes for
      * special handling.
      */
+    @SuppressWarnings("unused")
     public boolean beginMessageReceived(ChannelHandlerContext ctx) throws Exception {
         return true;
     }
 
+    /**
+     * Is called once a message was received.
+     *
+     * @param ctx           the {@link ChannelHandlerContext} which this {@link ChannelHandler} belongs to
+     * @param msg           the message to handle
+     * @throws Exception    thrown when an error accour
+     */
     public abstract void messageReceived(ChannelHandlerContext ctx, I msg) throws Exception;
-    public void endMessageReceived(ChannelHandlerContext ctx) throws Exception { }
+
+    /**
+     * Is called after all messages of the {@link MessageBuf} was consumed.
+     *
+     * Super-classes may-override this for special handling.
+     *
+     * @param ctx           the {@link ChannelHandlerContext} which this {@link ChannelHandler} belongs to
+     * @throws Exception    thrown when an error accour
+     */
+    @SuppressWarnings("unused")
+    public void endMessageReceived(ChannelHandlerContext ctx) throws Exception {
+        // NOOP
+    }
 }
diff --git a/transport/src/main/java/io/netty/channel/ChannelOption.java b/transport/src/main/java/io/netty/channel/ChannelOption.java
index 903a54cbfe..6eb0dc2876 100644
--- a/transport/src/main/java/io/netty/channel/ChannelOption.java
+++ b/transport/src/main/java/io/netty/channel/ChannelOption.java
@@ -25,6 +25,14 @@ import java.util.List;
 import java.util.concurrent.ConcurrentHashMap;
 import java.util.concurrent.ConcurrentMap;
 
+/**
+ * A {@link ChannelOption} allows to configure a {@link ChannelConfig} in a type-safe
+ * way. Which {@link ChannelOption} is supported depends on the actual implementation
+ * of {@link ChannelConfig} and may depend on the nature of the transport it belongs
+ * to.
+ *
+ * @param    the type of the value which is valid for the {@link ChannelOption}
+ */
 public class ChannelOption extends UniqueName {
 
     private static final ConcurrentMap names = new ConcurrentHashMap();
@@ -103,10 +111,20 @@ public class ChannelOption extends UniqueName {
     public static final ChannelOption AIO_WRITE_TIMEOUT =
             new ChannelOption("AIO_WRITE_TIMEOUT");
 
+    /**
+     * Create a new {@link ChannelOption} with the given name. The name needs to be
+     * unique.
+     *
+     */
     public ChannelOption(String name) {
         super(names, name);
     }
 
+    /**
+     * Validate the value which is set for the {@link ChannelOption}. Sub-classes
+     * may override this for special checks.
+     *
+     */
     public void validate(T value) {
         if (value == null) {
             throw new NullPointerException("value");