Javadoc

src/main/java/org/jboss/netty/handler/codec/embedder/AbstractCodecEmbedder.java

@@ -42,6 +42,8 @@ import org.jboss.netty.channel.ExceptionEvent;
 import org.jboss.netty.channel.MessageEvent;
 
 /**
+ * A skeletal {@link CodecEmbedder} implementation.
+ *
  * @author The Netty Project (netty-dev@lists.jboss.org)
  * @author Trustin Lee (tlee@redhat.com)
  * @version $Rev$, $Date$
@@ -54,6 +56,10 @@ public abstract class AbstractCodecEmbedder<T> implements CodecEmbedder<T> {
 
     final Queue<Object> productQueue = new LinkedList<Object>();
 
+    /**
+     * Creates a new embedder whose pipeline is composed of the specified
+     * handlers.
+     */
     protected AbstractCodecEmbedder(ChannelHandler... handlers) {
         pipeline = new EmbeddedChannelPipeline();
         configurePipeline(handlers);
@@ -61,6 +67,13 @@ public abstract class AbstractCodecEmbedder<T> implements CodecEmbedder<T> {
         fireInitialEvents();
     }
 
+    /**
+     * Creates a new embedder whose pipeline is composed of the specified
+     * handlers.
+     *
+     * @param bufferFactory the {@link ChannelBufferFactory} to be used when
+     *                      creating a new buffer.
+     */
     protected AbstractCodecEmbedder(ChannelBufferFactory bufferFactory, ChannelHandler... handlers) {
         this(handlers);
         getChannel().getConfig().setBufferFactory(bufferFactory);
@@ -101,10 +114,18 @@ public abstract class AbstractCodecEmbedder<T> implements CodecEmbedder<T> {
         return !productQueue.isEmpty();
     }
 
+    /**
+     * Returns the virtual {@link Channel} which will be used as a mock
+     * during encoding and decoding.
+     */
     protected final Channel getChannel() {
         return channel;
     }
 
+    /**
+     * Returns {@code true} if and only if the produce queue is empty and
+     * therefore {@link #poll()} will return {@code null}.
+     */
     protected final boolean isEmpty() {
         return productQueue.isEmpty();
     }

src/main/java/org/jboss/netty/handler/codec/embedder/CodecEmbedder.java

@@ -22,15 +22,51 @@
  */
 package org.jboss.netty.handler.codec.embedder;
 
-
 /**
+ * A helper that wraps an encoder or a decoder (codec) so that they can be used
+ * without doing actual I/O in unit tests or higher level codecs.  Please refer
+ * to {@link EncoderEmbedder} and {@link DecoderEmbedder} for more information.
+ *
  * @author The Netty Project (netty-dev@lists.jboss.org)
  * @author Trustin Lee (tlee@redhat.com)
  * @version $Rev$, $Date$
  */
 public interface CodecEmbedder<T> {
+    /**
+     * Offers an input object to the pipeline of this embedder.
+     *
+     * @return {@code true} if and only if there is something to read in the
+     *         product queue (see {@link #poll()} and {@link #peek()})
+     */
     boolean offer(Object input);
+
+    /**
+     * Signals the pipeline that the encoding or decoding has been finished and
+     * no more data will be offered.
+     *
+     * @return {@code true} if and only if there is something to read in the
+     *         product queue (see {@link #poll()} and {@link #peek()})
+     */
     boolean finish();
+
+    /**
+     * Consumes an encoded or decoded output from the product queue. The output
+     * object is generated by the offered input objects.
+     *
+     * @return an encoded or decoded object.
+     *         {@code null} if and only if there is no output object left in the
+     *         product queue.
+     */
     T poll();
+
+    /**
+     * Reads an encoded or decoded output from the head of the product queue.
+     * The difference from {@link #poll()} is that it does not remove the
+     * retrieved object from the product queue.
+     *
+     * @return an encoded or decoded object.
+     *         {@code null} if and only if there is no output object left in the
+     *         product queue.
+     */
     T peek();
 }

src/main/java/org/jboss/netty/handler/codec/embedder/CodecEmbedderException.java

@@ -23,6 +23,9 @@
 package org.jboss.netty.handler.codec.embedder;
 
 /**
+ * A {@link RuntimeException} which is thrown when a {@link CodecEmbedder}
+ * failed to encode or decode the specified input.
+ *
  * @author The Netty Project (netty-dev@lists.jboss.org)
  * @author Trustin Lee (tlee@redhat.com)
  * @version $Rev$, $Date$
@@ -33,18 +36,30 @@ public class CodecEmbedderException extends RuntimeException {
 
     private static final long serialVersionUID = -6283302594160331474L;
 
+    /**
+     * Creates a new instance.
+     */
     public CodecEmbedderException() {
         super();
     }
 
+    /**
+     * Creates a new instance.
+     */
     public CodecEmbedderException(String message, Throwable cause) {
         super(message, cause);
     }
 
+    /**
+     * Creates a new instance.
+     */
     public CodecEmbedderException(String message) {
         super(message);
     }
 
+    /**
+     * Creates a new instance.
+     */
     public CodecEmbedderException(Throwable cause) {
         super(cause);
     }

src/main/java/org/jboss/netty/handler/codec/embedder/DecoderEmbedder.java

@@ -24,10 +24,31 @@ package org.jboss.netty.handler.codec.embedder;
 
 import static org.jboss.netty.channel.Channels.*;
 
+import org.jboss.netty.buffer.ChannelBuffer;
 import org.jboss.netty.buffer.ChannelBufferFactory;
+import org.jboss.netty.channel.ChannelPipeline;
 import org.jboss.netty.channel.ChannelUpstreamHandler;
+import org.jboss.netty.handler.codec.base64.Base64Decoder;
+import org.jboss.netty.handler.codec.string.StringDecoder;
 
 /**
+ * A helper that wraps a decoder so that it can be used without doing actual
+ * I/O in unit tests or higher level codecs.  For example, you can decode a
+ * Base64-encoded {@link ChannelBuffer} with {@link Base64Decoder} and
+ * {@link StringDecoder} without setting up the {@link ChannelPipeline} and
+ * other mock objects by yourself:
+ * <pre>
+ * ChannelBuffer base64Data = ChannelBuffer.copiedBuffer("Zm9vYmFy", "ASCII");
+ *
+ * DecoderEmbedder&lt;String&gt; embedder = new DecoderEmbedder&lt;String&gt;(
+ *         new Base64Decoder(), new StringDecoder());
+ *
+ * embedded.offer(base64Data);
+ *
+ * String decoded = embedded.poll();
+ * assert decoded.equals("foobar");
+ * </pre>
+ *
  * @author The Netty Project (netty-dev@lists.jboss.org)
  * @author Trustin Lee (tlee@redhat.com)
  * @version $Rev$, $Date$
@@ -36,10 +57,21 @@ import org.jboss.netty.channel.ChannelUpstreamHandler;
  */
 public class DecoderEmbedder<T> extends AbstractCodecEmbedder<T> {
 
+    /**
+     * Creates a new embedder whose pipeline is composed of the specified
+     * handlers.
+     */
     public DecoderEmbedder(ChannelUpstreamHandler... handlers) {
         super(handlers);
     }
 
+    /**
+     * Creates a new embedder whose pipeline is composed of the specified
+     * handlers.
+     *
+     * @param bufferFactory the {@link ChannelBufferFactory} to be used when
+     *                      creating a new buffer.
+     */
     public DecoderEmbedder(ChannelBufferFactory bufferFactory, ChannelUpstreamHandler... handlers) {
         super(bufferFactory, handlers);
     }

src/main/java/org/jboss/netty/handler/codec/embedder/EncoderEmbedder.java

@@ -24,10 +24,31 @@ package org.jboss.netty.handler.codec.embedder;
 
 import static org.jboss.netty.channel.Channels.*;
 
+import org.jboss.netty.buffer.ChannelBuffer;
 import org.jboss.netty.buffer.ChannelBufferFactory;
 import org.jboss.netty.channel.ChannelDownstreamHandler;
+import org.jboss.netty.channel.ChannelPipeline;
+import org.jboss.netty.handler.codec.base64.Base64Encoder;
+import org.jboss.netty.handler.codec.string.StringEncoder;
 
 /**
+ * A helper that wraps an encoder so that it can be used without doing actual
+ * I/O in unit tests or higher level codecs.  For example, you can encode a
+ * {@link String} into a Base64-encoded {@link ChannelBuffer} with
+ * {@link Base64Encoder} and {@link StringEncoder} without setting up the
+ * {@link ChannelPipeline} and other mock objects by yourself:
+ * <pre>
+ * String data = "foobar";
+ *
+ * EncoderEmbedder&lt;ChannelBuffer&gt; embedder = new EncoderEmbedder&lt;ChannelBuffer&gt;(
+ *         new Base64Encoder(), new StringEncoder());
+ *
+ * embedded.offer(data);
+ *
+ * ChannelBuffer encoded = embedded.poll();
+ * assert encoded.toString("ASCII").equals("Zm9vYmFy");
+ * </pre>
+ *
  * @author The Netty Project (netty-dev@lists.jboss.org)
  * @author Trustin Lee (tlee@redhat.com)
  * @version $Rev$, $Date$
@@ -36,10 +57,21 @@ import org.jboss.netty.channel.ChannelDownstreamHandler;
  */
 public class EncoderEmbedder<T> extends AbstractCodecEmbedder<T> {
 
+    /**
+     * Creates a new embedder whose pipeline is composed of the specified
+     * handlers.
+     */
     public EncoderEmbedder(ChannelDownstreamHandler... handlers) {
         super(handlers);
     }
 
+    /**
+     * Creates a new embedder whose pipeline is composed of the specified
+     * handlers.
+     *
+     * @param bufferFactory the {@link ChannelBufferFactory} to be used when
+     *                      creating a new buffer.
+     */
     public EncoderEmbedder(ChannelBufferFactory bufferFactory, ChannelDownstreamHandler... handlers) {
         super(bufferFactory, handlers);
     }

src/main/java/org/jboss/netty/handler/codec/embedder/package-info.java

@@ -22,9 +22,8 @@
  */
 
 /**
- * A helper that wraps an encoder or a decoder so that it can be used outside
+ * A helper that wraps an encoder or a decoder so that they can be used without
- * a {@link org.jboss.netty.channel.ChannelPipeline} or inside a
+ * doing actual I/O in unit tests or higher level codecs.
- * {@link org.jboss.netty.channel.ChannelHandler} conveniently.
  */
 package org.jboss.netty.handler.codec.embedder;