diff --git a/src/main/java/org/jboss/netty/handler/codec/embedder/AbstractCodecEmbedder.java b/src/main/java/org/jboss/netty/handler/codec/embedder/AbstractCodecEmbedder.java index 43e5dbcfaa..07d2e1dd1a 100644 --- a/src/main/java/org/jboss/netty/handler/codec/embedder/AbstractCodecEmbedder.java +++ b/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 implements CodecEmbedder { final Queue productQueue = new LinkedList(); + /** + * 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 implements CodecEmbedder { 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 implements CodecEmbedder { 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(); } diff --git a/src/main/java/org/jboss/netty/handler/codec/embedder/CodecEmbedder.java b/src/main/java/org/jboss/netty/handler/codec/embedder/CodecEmbedder.java index f7e7a6d2b8..389037f6f0 100644 --- a/src/main/java/org/jboss/netty/handler/codec/embedder/CodecEmbedder.java +++ b/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 { + /** + * 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(); } diff --git a/src/main/java/org/jboss/netty/handler/codec/embedder/CodecEmbedderException.java b/src/main/java/org/jboss/netty/handler/codec/embedder/CodecEmbedderException.java index 1ecf5bea8e..6c0117d546 100644 --- a/src/main/java/org/jboss/netty/handler/codec/embedder/CodecEmbedderException.java +++ b/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); } diff --git a/src/main/java/org/jboss/netty/handler/codec/embedder/DecoderEmbedder.java b/src/main/java/org/jboss/netty/handler/codec/embedder/DecoderEmbedder.java index aece1ea171..e31dde2b78 100644 --- a/src/main/java/org/jboss/netty/handler/codec/embedder/DecoderEmbedder.java +++ b/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: + * 
+ * ChannelBuffer base64Data = ChannelBuffer.copiedBuffer("Zm9vYmFy", "ASCII");
+ *
+ * DecoderEmbedder<String> embedder = new DecoderEmbedder<String>(
+ *         new Base64Decoder(), new StringDecoder());
+ *
+ * embedded.offer(base64Data);
+ *
+ * String decoded = embedded.poll();
+ * assert decoded.equals("foobar");
+ *
+ * * @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 extends AbstractCodecEmbedder { + /** + * 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); } diff --git a/src/main/java/org/jboss/netty/handler/codec/embedder/EncoderEmbedder.java b/src/main/java/org/jboss/netty/handler/codec/embedder/EncoderEmbedder.java index b57314e15b..dd14851dc7 100644 --- a/src/main/java/org/jboss/netty/handler/codec/embedder/EncoderEmbedder.java +++ b/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: + * 
+ * String data = "foobar";
+ *
+ * EncoderEmbedder<ChannelBuffer> embedder = new EncoderEmbedder<ChannelBuffer>(
+ *         new Base64Encoder(), new StringEncoder());
+ *
+ * embedded.offer(data);
+ *
+ * ChannelBuffer encoded = embedded.poll();
+ * assert encoded.toString("ASCII").equals("Zm9vYmFy");
+ *
+ * * @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 extends AbstractCodecEmbedder { + /** + * 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); } diff --git a/src/main/java/org/jboss/netty/handler/codec/embedder/package-info.java b/src/main/java/org/jboss/netty/handler/codec/embedder/package-info.java index 27631273ce..2ee5bc10b8 100644 --- a/src/main/java/org/jboss/netty/handler/codec/embedder/package-info.java +++ b/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 {@link org.jboss.netty.channel.ChannelPipeline} or inside a - * {@link org.jboss.netty.channel.ChannelHandler} conveniently. + * A helper that wraps an encoder or a decoder so that they can be used without + * doing actual I/O in unit tests or higher level codecs. */ package org.jboss.netty.handler.codec.embedder;