Permalink
Browse files

Add a lot of javadocs to make usage more clear

  • Loading branch information...
1 parent b004066 commit 8a7bc2c6068d699df21fc1b1f6326e8ede69b930 @normanmaurer normanmaurer committed Dec 21, 2012
Showing with 486 additions and 73 deletions.
  1. +3 −0 buffer/src/main/java/io/netty/buffer/Buf.java
  2. +3 −0 buffer/src/main/java/io/netty/buffer/ByteBufUtil.java
  3. +141 −0 buffer/src/main/java/io/netty/buffer/CompositeByteBuf.java
  4. +4 −0 buffer/src/main/java/io/netty/buffer/DefaultMessageBuf.java
  5. +17 −2 buffer/src/main/java/io/netty/buffer/MessageBuf.java
  6. +36 −0 codec/src/main/java/io/netty/handler/codec/ByteToByteCodec.java
  7. +42 −0 codec/src/main/java/io/netty/handler/codec/ByteToByteDecoder.java
  8. +32 −0 codec/src/main/java/io/netty/handler/codec/ByteToByteEncoder.java
  9. +35 −0 codec/src/main/java/io/netty/handler/codec/ByteToMessageDecoder.java
  10. +1 −1 codec/src/main/java/io/netty/handler/codec/CorruptedFrameException.java
  11. +1 −1 codec/src/main/java/io/netty/handler/codec/DecoderException.java
  12. +1 −1 codec/src/main/java/io/netty/handler/codec/DelimiterBasedFrameDecoder.java
  13. +1 −1 codec/src/main/java/io/netty/handler/codec/EncoderException.java
  14. +2 −6 codec/src/main/java/io/netty/handler/codec/LengthFieldBasedFrameDecoder.java
  15. +1 −4 codec/src/main/java/io/netty/handler/codec/LengthFieldPrepender.java
  16. +27 −0 codec/src/main/java/io/netty/handler/codec/MessageToByteEncoder.java
  17. +24 −0 codec/src/main/java/io/netty/handler/codec/MessageToMessageCodec.java
  18. +36 −2 codec/src/main/java/io/netty/handler/codec/MessageToMessageDecoder.java
  19. +36 −0 codec/src/main/java/io/netty/handler/codec/MessageToMessageEncoder.java
  20. +32 −45 codec/src/main/java/io/netty/handler/codec/ReplayingDecoder.java
  21. +3 −0 codec/src/main/java/io/netty/handler/codec/ReplayingDecoderBuffer.java
  22. +2 −2 codec/src/main/java/io/netty/handler/codec/TooLongFrameException.java
  23. +2 −4 codec/src/main/java/io/netty/handler/codec/UnreplayableOperationException.java
  24. +3 −0 codec/src/main/java/io/netty/handler/codec/UnsupportedMessageTypeException.java
  25. +1 −4 handler/src/main/java/io/netty/handler/logging/LoggingHandler.java
@@ -15,6 +15,9 @@
*/
package io.netty.buffer;
+/**
+ * A buffer to operate on
+ */
public interface Buf {
/**
* The BufType which will be handled by the Buf implementation
@@ -26,6 +26,9 @@
import java.nio.charset.CharsetEncoder;
import java.nio.charset.CoderResult;
+/**
+ * Utility class for operate on a {@link ByteBuf}
+ */
public final class ByteBufUtil {
private static final char[] HEXDUMP_TABLE = new char[256 * 4];
@@ -20,30 +20,171 @@
import java.nio.ByteBuffer;
import java.util.List;
+/**
+ * A {@link ByteBuf} which is composed out of other {@link ByteBuf}s.
+ */
public interface CompositeByteBuf extends ByteBuf, Iterable<ByteBuf> {
+ /**
+ * Add the given {@link ByteBuf}.
+ *
+ * @param buffer the {@link ByteBuf} to add
+ * @return self this instance
+ */
CompositeByteBuf addComponent(ByteBuf buffer);
+
+ /**
+ * Add the given {@link ByteBuf} on the specific index.
+ *
+ * @param cIndex
+ * the index on which the {@link ByteBuf} will be added
+ * @param buffer
+ * the {@link ByteBuf} to add
+ * @return self
+ * this instance
+ * @thows {@link IndexOutOfBoundsException}
+ * if the index is invalid
+ */
CompositeByteBuf addComponent(int cIndex, ByteBuf buffer);
+ /**
+ * Add the given {@link ByteBuf}s.
+ *
+ * @param buffers the {@link ByteBuf}s to add
+ * @return self this instance
+ */
CompositeByteBuf addComponents(ByteBuf... buffers);
+
+ /**
+ * Add the given {@link ByteBuf}s.
+ *
+ * @param buffers the {@link ByteBuf}s to add
+ * @return self this instance
+ */
CompositeByteBuf addComponents(Iterable<ByteBuf> buffers);
+
+ /**
+ * Add the given {@link ByteBuf}s on the specific index
+ *
+ * @param cIndex
+ * the index on which the {@link ByteBuf} will be added.
+ * @param buffers
+ * the {@link ByteBuf}s to add
+ * @return self
+ * this instance
+ * @thows {@link IndexOutOfBoundsException}
+ * if the index is invalid
+ *
+ */
CompositeByteBuf addComponents(int cIndex, ByteBuf... buffers);
+
+ /**
+ * Add the given {@link ByteBuf}s on the specific index
+ *
+ * @param cIndex
+ * the index on which the {@link ByteBuf} will be added.
+ * @param buffers
+ * the {@link ByteBuf}s to add
+ * @return self
+ * this instance
+ * @thows {@link IndexOutOfBoundsException}
+ * if the index is invalid
+ */
CompositeByteBuf addComponents(int cIndex, Iterable<ByteBuf> buffers);
+ /**
+ * Remove the {@link ByteBuf} from the given index.
+ *
+ * @param cIndex
+ * the index on from which the {@link ByteBuf} will be remove
+ * @return self
+ * this instance
+ * @thows {@link IndexOutOfBoundsException}
+ * if the index is invalid
+ */
CompositeByteBuf removeComponent(int cIndex);
+
+ /**
+ * Remove the number of {@link ByteBuf}s starting from the given index.
+ *
+ * @param cIndex
+ * the index on which the {@link ByteBuf}s will be started to removed
+ * @param numComponents
+ * the number of components to remove
+ * @return self
+ * this instance
+ * @thows {@link IndexOutOfBoundsException}
+ * if the index is invalid
+ */
CompositeByteBuf removeComponents(int cIndex, int numComponents);
+ /**
+ * Return the current number of {@link ByteBuf}'s that are composed in this instance
+ */
int numComponents();
+
+ /**
+ * Return the max number of {@link ByteBuf}'s that are composed in this instance
+ */
int maxNumComponents();
+ /**
+ * Return the {@link ByteBuf} on the specified index
+ *
+ * @param cIndex
+ * the index for which the {@link ByteBuf} should be returned
+ * @return buf
+ * the {@link ByteBuf} on the specified index
+ * @thows {@link IndexOutOfBoundsException}
+ * if the index is invalid
+ */
ByteBuf component(int cIndex);
+
+ /**
+ * Return the {@link ByteBuf} on the specified index
+ *
+ * @param offset
+ * the offset for which the {@link ByteBuf} should be returned
+ * @return buf
+ * the {@link ByteBuf} on the specified index
+ * @thows {@link IndexOutOfBoundsException}
+ * if the offset is invalid
+ */
ByteBuf componentAtOffset(int offset);
+ /**
+ * Discard all {@link ByteBuf}s which are read.
+ *
+ * @return self this instance
+ */
CompositeByteBuf discardReadComponents();
+
+ /**
+ * Consolidate the composed {@link ByteBuf}s
+ *
+ * @return self this instance
+ */
CompositeByteBuf consolidate();
+
+ /**
+ * Consolidate the composed {@link ByteBuf}s
+ *
+ * @param cIndex
+ * the index on which to start to compose
+ * @param numComponents
+ * the number of components to compose
+ * @return self
+ * this instance
+ * @thows {@link IndexOutOfBoundsException}
+ * if the offset is invalid
+ */
CompositeByteBuf consolidate(int cIndex, int numComponents);
+ /**
+ * Return the index for the given offset
+ */
int toComponentIndex(int offset);
+
int toByteIndex(int cIndex);
/**
@@ -19,6 +19,10 @@
import java.util.Collection;
import java.util.Iterator;
+/**
+ * Default {@link MessageBuf} implementation
+ *
+ */
final class DefaultMessageBuf<T> extends ArrayDeque<T> implements MessageBuf<T> {
private static final long serialVersionUID = 1229808623624907552L;
@@ -19,11 +19,26 @@
import java.util.Queue;
/**
- * Buf which operates on messages
+ * Buf which operates on messages.
*
- * @param <T>
+ * @param <T> the type of the messages that are hold by this {@link MessageBuf}
*/
public interface MessageBuf<T> extends Buf, Queue<T> {
+
+ /**
+ * Drain the content of te {@link MessageBuf} to the given {@link Collection}.
+ *
+ * @param c the {@link Collection} to drain the content to
+ * @return number the number of objects which was transfered
+ */
int drainTo(Collection<? super T> c);
+
+ /**
+ * Drain the content of te {@link MessageBuf} to the given {@link Collection}.
+ *
+ * @param c the {@link Collection} to drain the content to
+ * @param maxElements the max number of elements to drain
+ * @return number the number of objects which was transfered
+ */
int drainTo(Collection<? super T> c, int maxElements);
}
@@ -23,6 +23,36 @@
import io.netty.channel.ChannelInboundByteHandler;
import io.netty.channel.ChannelOutboundByteHandler;
+/**
+ * A Codec for on-the-fly encoding/decoding of bytes.
+ *
+ * This can be though of an combination of {@link ByteToByteDecoder} and {@link ByteToByteEncoder}.
+ *
+ * Here is an example of a {@link ByteToByteCodec} which just square {@link Integer} read from a {@link ByteBuf}.
+ * <pre>
+ * public class SquareCodec extends {@link ByteToByteCodec} {
+ * {@code @Override}
+ * public void decode({@link ChannelHandlerContext} ctx, {@link ByteBuf} in, {@link ByteBuf} out)
+ * throws {@link Exception} {
+ * if (in.readableBytes() < 4) {
+ * return;
+ * }
+ * int value = in.readInt();
+ * out.writeInt(value * value);
+ * }
+ *
+ * {@code @Overrride}
+ * public void encode({@link ChannelHandlerContext} ctx, {@link ByteBuf} in, {@link ByteBuf} out)
+ * throws {@link Exception} {
+ * if (in.readableBytes() < 4) {
+ * return;
+ * }
+ * int value = in.readInt();
+ * out.writeInt(value / value);
+ * }
+ * }
+ * </pre>
+ */
public abstract class ByteToByteCodec
extends ChannelHandlerAdapter
implements ChannelInboundByteHandler, ChannelOutboundByteHandler {
@@ -76,10 +106,16 @@ public void freeOutboundBuffer(ChannelHandlerContext ctx, Buf buf) throws Except
encoder.freeOutboundBuffer(ctx, buf);
}
+ /**
+ * @see {@link ByteToByteEncoder#encode(ChannelHandlerContext, ByteBuf, ByteBuf)}
+ */
public abstract void encode(
ChannelHandlerContext ctx,
ByteBuf in, ByteBuf out) throws Exception;
+ /**
+ * @see {@link ByteToByteDecoder#decode(ChannelHandlerContext, ByteBuf, ByteBuf)}
+ */
public abstract void decode(
ChannelHandlerContext ctx,
ByteBuf in, ByteBuf out) throws Exception;
@@ -19,6 +19,29 @@
import io.netty.channel.ChannelHandlerContext;
import io.netty.channel.ChannelInboundByteHandlerAdapter;
+/**
+ * {@link ChannelInboundByteHandlerAdapter} which decodes bytes in a stream-like fashion from one {@link ByteBuf} to an
+ * other.
+ *
+ * This kind of decoder is often useful for doing on-the-fly processiing like i.e. compression.
+ *
+ * But you can also do other things with it. For example here is an implementation which reads {@link Integer}s from
+ * the input {@link ByteBuf} and square them before write them to the output {@link ByteBuf}.
+ *
+ * <pre>
+ * public class SquareDecoder extends {@link ByteToByteDecoder} {
+ * {@code @Override}
+ * public void decode({@link ChannelHandlerContext} ctx, {@link ByteBuf} in, {@link ByteBuf} out)
+ * throws {@link Exception} {
+ * if (in.readableBytes() < 4) {
+ * return;
+ * }
+ * int value = in.readInt();
+ * out.writeInt(value * value);
+ * }
+ * }
+ * </pre>
+ */
public abstract class ByteToByteDecoder extends ChannelInboundByteHandlerAdapter {
@Override
@@ -52,6 +75,9 @@ public void channelInactive(ChannelHandlerContext ctx) throws Exception {
ctx.fireChannelInactive();
}
+ /**
+ * Call the {@link #decode(ChannelHandlerContext, ByteBuf, ByteBuf)} method until it is done.
+ */
private void callDecode(ChannelHandlerContext ctx, ByteBuf in, ByteBuf out) {
int oldOutSize = out.readableBytes();
while (in.readable()) {
@@ -76,8 +102,24 @@ private void callDecode(ChannelHandlerContext ctx, ByteBuf in, ByteBuf out) {
}
}
+ /**
+ * Decode the from one {@link ByteBuf} to an other. This method will be called till either the input
+ * {@link ByteBuf} has nothing to read anymore or till nothing was read from the input {@link ByteBuf}.
+ *
+ * @param ctx the {@link ChannelHandlerContext} which this {@link ByteToByteDecoder} belongs to
+ * @param in the {@link ByteBuf} from which to read data
+ * @param out the {@link ByteBuf} to which the decoded data will be written
+ * @throws Exception is thrown if an error accour
+ */
public abstract void decode(ChannelHandlerContext ctx, ByteBuf in, ByteBuf out) throws Exception;
+ /**
+ * Is called one last time when the {@link ChannelHandlerContext} goes in-active. Which means the
+ * {@link #channelInactive(ChannelHandlerContext)} was triggered.
+ *
+ * By default this will just call {@link #decode(ChannelHandlerContext, ByteBuf, ByteBuf)} but sub-classes may
+ * override this for some special cleanup operation.
+ */
public void decodeLast(ChannelHandlerContext ctx, ByteBuf in, ByteBuf out) throws Exception {
decode(ctx, in, out);
}
@@ -20,6 +20,29 @@
import io.netty.channel.ChannelHandlerContext;
import io.netty.channel.ChannelOutboundByteHandlerAdapter;
+/**
+ * {@link ChannelOutboundByteHandlerAdapter} which encodes bytes in a stream-like fashion from one {@link ByteBuf} to an
+ * other.
+ *
+ * This kind of decoder is often useful for doing on-the-fly processing like i.e. compression.
+ *
+ * But you can also do other things with it. For example here is an implementation which reads {@link Integer}s from
+ * the input {@link ByteBuf} and square them before write them to the output {@link ByteBuf}.
+ *
+ * <pre>
+ * public class SquareEncoder extends {@link ByteToByteEncoder} {
+ * {@code @Override}
+ * public void encode({@link ChannelHandlerContext} ctx, {@link ByteBuf} in, {@link ByteBuf} out)
+ * throws {@link Exception} {
+ * if (in.readableBytes() < 4) {
+ * return;
+ * }
+ * int value = in.readInt();
+ * out.writeInt(value * value);
+ * }
+ * }
+ * </pre>
+ */
public abstract class ByteToByteEncoder extends ChannelOutboundByteHandlerAdapter {
@Override
@@ -47,5 +70,14 @@ public void flush(ChannelHandlerContext ctx, ChannelFuture future) throws Except
ctx.flush(future);
}
+ /**
+ * Encodes the from one {@link ByteBuf} to an other. This method will be called till either the input
+ * {@link ByteBuf} has nothing to read anymore or till nothing was read from the input {@link ByteBuf}.
+ *
+ * @param ctx the {@link ChannelHandlerContext} which this {@link ByteToByteDecoder} belongs to
+ * @param in the {@link ByteBuf} from which to read data
+ * @param out the {@link ByteBuf} to which the decoded data will be written
+ * @throws Exception is thrown if an error accour
+ */
public abstract void encode(ChannelHandlerContext ctx, ByteBuf in, ByteBuf out) throws Exception;
}
Oops, something went wrong.

0 comments on commit 8a7bc2c

Please sign in to comment.