Add and correct javadocs

This commit is contained in:
Norman Maurer 2013-07-13 19:42:02 +02:00
parent 910c5fd594
commit a07abee55f
9 changed files with 122 additions and 15 deletions

View File

@ -58,11 +58,20 @@ public abstract class ByteToMessageCodec<I> extends ChannelDuplexHandler {
}
};
/**
* Create a new instance which will try to detect the types to encode out of the type parameter
* of the class.
*/
protected ByteToMessageCodec() {
checkForSharableAnnotation();
outboundMsgMatcher = TypeParameterMatcher.find(this, ByteToMessageCodec.class, "I");
}
/**
* Create a new instance.
*
* @param outboundMessageType The type of messages to encode
*/
protected ByteToMessageCodec(Class<? extends I> outboundMessageType) {
checkForSharableAnnotation();
outboundMsgMatcher = TypeParameterMatcher.get(outboundMessageType);
@ -74,6 +83,11 @@ public abstract class ByteToMessageCodec<I> extends ChannelDuplexHandler {
}
}
/**
* Returns {@code true} if and only if the specified message can be encoded by this codec.
*
* @param msg the message
*/
public boolean acceptOutboundMessage(Object msg) throws Exception {
return outboundMsgMatcher.match(msg);
}

View File

@ -129,7 +129,6 @@ public class LengthFieldPrepender extends MessageToByteEncoder<ByteBuf> {
@Override
protected void encode(ChannelHandlerContext ctx, ByteBuf msg, ByteBuf out) throws Exception {
int length = msg.readableBytes() + lengthAdjustment;
if (lengthIncludesLengthFieldLength) {
length += lengthFieldLength;

View File

@ -18,7 +18,9 @@ package io.netty.handler.codec;
import io.netty.buffer.ByteBuf;
import io.netty.buffer.Unpooled;
import io.netty.channel.ChannelHandlerContext;
import io.netty.channel.ChannelOutboundHandler;
import io.netty.channel.ChannelOutboundHandlerAdapter;
import io.netty.channel.ChannelPipeline;
import io.netty.channel.ChannelPromise;
import io.netty.util.ReferenceCountUtil;
import io.netty.util.internal.TypeParameterMatcher;
@ -46,24 +48,49 @@ public abstract class MessageToByteEncoder<I> extends ChannelOutboundHandlerAdap
private final TypeParameterMatcher matcher;
private final boolean preferDirect;
/**
* @see {@link #MessageToByteEncoder(boolean)} with {@code true} as boolean parameter.
*/
protected MessageToByteEncoder() {
this(true);
}
/**
* @see {@link #MessageToByteEncoder(Class, boolean)} with {@code true} as boolean value.
*/
protected MessageToByteEncoder(Class<? extends I> outboundMessageType) {
this(outboundMessageType, true);
}
/**
* Create a new instance which will try to detect the types to match out of the type parameter of the class.
*
* @param preferDirect {@code true} if a direct {@link ByteBuf} should be tried to be used as target for
* the encoded messages. If {@code false} is used it will allocate a heap
* {@link ByteBuf}, which is backed by an byte array.
*/
protected MessageToByteEncoder(boolean preferDirect) {
matcher = TypeParameterMatcher.find(this, MessageToByteEncoder.class, "I");
this.preferDirect = preferDirect;
}
/**
* Create a new instance
*
* @param outboundMessageType The tpye of messages to match
* @param preferDirect {@code true} if a direct {@link ByteBuf} should be tried to be used as target for
* the encoded messages. If {@code false} is used it will allocate a heap
* {@link ByteBuf}, which is backed by an byte array.
*/
protected MessageToByteEncoder(Class<? extends I> outboundMessageType, boolean preferDirect) {
matcher = TypeParameterMatcher.get(outboundMessageType);
this.preferDirect = preferDirect;
}
/**
* Returns {@code true} if the given message should be handled. If {@code false} it will be passed to the next
* {@link ChannelOutboundHandler} in the {@link ChannelPipeline}.
*/
public boolean acceptOutboundMessage(Object msg) throws Exception {
return matcher.match(msg);
}

View File

@ -33,17 +33,17 @@ import java.util.List;
*
* <pre>
* public class NumberCodec extends
* {@link MessageToMessageCodec}&lt;{@link Integer}, {@link Long}, {@link Long}, {@link Integer}&gt; {
* {@link MessageToMessageCodec}&lt;{@link Integer}, {@link Long}&gt; {
* {@code @Override}
* public {@link Long} decode({@link ChannelHandlerContext} ctx, {@link Integer} msg)
* public {@link Long} decode({@link ChannelHandlerContext} ctx, {@link Integer} msg, List&lt;Object&gt; out)
* throws {@link Exception} {
* return msg.longValue();
* out.add(msg.longValue());
* }
*
* {@code @Overrride}
* public {@link Integer} encode({@link ChannelHandlerContext} ctx, {@link Long} msg)
* public {@link Integer} encode({@link ChannelHandlerContext} ctx, {@link Long} msg, List&lt;Object&gt; out)
* throws {@link Exception} {
* return msg.intValue();
* out.add(msg.intValue());
* }
* }
* </pre>
@ -85,11 +85,21 @@ public abstract class MessageToMessageCodec<INBOUND_IN, OUTBOUND_IN> extends Cha
private final TypeParameterMatcher inboundMsgMatcher;
private final TypeParameterMatcher outboundMsgMatcher;
/**
* Create a new instance which will try to detect the types to decode and encode out of the type parameter
* of the class.
*/
protected MessageToMessageCodec() {
inboundMsgMatcher = TypeParameterMatcher.find(this, MessageToMessageCodec.class, "INBOUND_IN");
outboundMsgMatcher = TypeParameterMatcher.find(this, MessageToMessageCodec.class, "OUTBOUND_IN");
}
/**
* Create a new instance.
*
* @param inboundMessageType The type of messages to decode
* @param outboundMessageType The type of messages to encode
*/
protected MessageToMessageCodec(
Class<? extends INBOUND_IN> inboundMessageType, Class<? extends OUTBOUND_IN> outboundMessageType) {
inboundMsgMatcher = TypeParameterMatcher.get(inboundMessageType);

View File

@ -16,7 +16,9 @@
package io.netty.handler.codec;
import io.netty.channel.ChannelHandlerContext;
import io.netty.channel.ChannelInboundHandler;
import io.netty.channel.ChannelInboundHandlerAdapter;
import io.netty.channel.ChannelPipeline;
import io.netty.util.ReferenceCountUtil;
import io.netty.util.ReferenceCounted;
import io.netty.util.internal.RecyclableArrayList;
@ -52,14 +54,26 @@ public abstract class MessageToMessageDecoder<I> extends ChannelInboundHandlerAd
private final TypeParameterMatcher matcher;
/**
* Create a new instance which will try to detect the types to match out of the type parameter of the class.
*/
protected MessageToMessageDecoder() {
matcher = TypeParameterMatcher.find(this, MessageToMessageDecoder.class, "I");
}
/**
* Create a new instance
*
* @param inboundMessageType The type of messages to match and so decode
*/
protected MessageToMessageDecoder(Class<? extends I> inboundMessageType) {
matcher = TypeParameterMatcher.get(inboundMessageType);
}
/**
* Returns {@code true} if the given message should be handled. If {@code false} it will be passed to the next
* {@link ChannelInboundHandler} in the {@link ChannelPipeline}.
*/
public boolean acceptInboundMessage(Object msg) throws Exception {
return matcher.match(msg);
}

View File

@ -16,7 +16,9 @@
package io.netty.handler.codec;
import io.netty.channel.ChannelHandlerContext;
import io.netty.channel.ChannelOutboundHandler;
import io.netty.channel.ChannelOutboundHandlerAdapter;
import io.netty.channel.ChannelPipeline;
import io.netty.channel.ChannelPromise;
import io.netty.util.ReferenceCountUtil;
import io.netty.util.ReferenceCounted;
@ -51,14 +53,26 @@ public abstract class MessageToMessageEncoder<I> extends ChannelOutboundHandlerA
private final TypeParameterMatcher matcher;
/**
* Create a new instance which will try to detect the types to match out of the type parameter of the class.
*/
protected MessageToMessageEncoder() {
matcher = TypeParameterMatcher.find(this, MessageToMessageEncoder.class, "I");
}
/**
* Create a new instance
*
* @param outboundMessageType The type of messages to match and so encode
*/
protected MessageToMessageEncoder(Class<? extends I> outboundMessageType) {
matcher = TypeParameterMatcher.get(outboundMessageType);
}
/**
* Returns {@code true} if the given message should be handled. If {@code false} it will be passed to the next
* {@link ChannelOutboundHandler} in the {@link ChannelPipeline}.
*/
public boolean acceptOutboundMessage(Object msg) throws Exception {
return matcher.match(msg);
}

View File

@ -36,14 +36,14 @@ import java.util.List;
* availability of the required bytes. For example, the following
* {@link ByteToMessageDecoder} implementation:
* <pre>
* public class IntegerHeaderFrameDecoder extends {@link ByteToMessageDecoder}&lt;{@link ByteBuf}&gt; {
* public class IntegerHeaderFrameDecoder extends {@link ByteToMessageDecoder} {
*
* {@code @Override}
* protected ByteBuf decode({@link ChannelHandlerContext} ctx,
* {@link ByteBuf} in) throws Exception {
* protected void decode({@link ChannelHandlerContext} ctx,
* {@link ByteBuf} in, List&lt;Object&gt; out) throws Exception {
*
* if (in.readableBytes() &lt; 4) {
* return <strong>null</strong>;
* return;
* }
*
* in.markReaderIndex();
@ -51,22 +51,22 @@ import java.util.List;
*
* if (in.readableBytes() &lt; length) {
* in.resetReaderIndex();
* return <strong>null</strong>;
* return;
* }
*
* return in.readBytes(length);
* out.add(in.readBytes(length));
* }
* }
* </pre>
* is simplified like the following with {@link ReplayingDecoder}:
* <pre>
* public class IntegerHeaderFrameDecoder
* extends {@link ReplayingDecoder}&lt;{@link ByteBuf},{@link Void}&gt; {
* extends {@link ReplayingDecoder}&lt;{@link Void}&gt; {
*
* protected Object decode({@link ChannelHandlerContext} ctx,
* protected void decode({@link ChannelHandlerContext} ctx,
* {@link ByteBuf} buf) throws Exception {
*
* return buf.readBytes(buf.readInt());
* out.add(buf.readBytes(buf.readInt()));
* }
* }
* </pre>

View File

@ -35,30 +35,55 @@ import io.netty.util.internal.TypeParameterMatcher;
* }
* </pre>
*
* Be aware that depending of the constructor parameters it will release all handled messages.
*
*/
public abstract class SimpleChannelInboundHandler<I> extends ChannelInboundHandlerAdapter {
private final TypeParameterMatcher matcher;
private final boolean autoRelease;
/**
* @see {@link #SimpleChannelInboundHandler(boolean)} with {@code true} as boolean parameter.
*/
protected SimpleChannelInboundHandler() {
this(true);
}
/**
* Create a new instance which will try to detect the types to match out of the type parameter of the class.
*
* @param autoRelease {@code true} if handled messages should be released automatically by pass them to
* {@link ReferenceCountUtil#release(Object)}.
*/
protected SimpleChannelInboundHandler(boolean autoRelease) {
matcher = TypeParameterMatcher.find(this, SimpleChannelInboundHandler.class, "I");
this.autoRelease = autoRelease;
}
/**
* @see {@link #SimpleChannelInboundHandler(Class, boolean)} with {@code true} as boolean value.
*/
protected SimpleChannelInboundHandler(Class<? extends I> inboundMessageType) {
this(inboundMessageType, true);
}
/**
* Create a new instance
*
* @param inboundMessageType The type of messages to match
* @param autoRelease {@code true} if handled messages should be released automatically by pass them to
* {@link ReferenceCountUtil#release(Object)}.
*/
protected SimpleChannelInboundHandler(Class<? extends I> inboundMessageType, boolean autoRelease) {
matcher = TypeParameterMatcher.get(inboundMessageType);
this.autoRelease = autoRelease;
}
/**
* Returns {@code true} if the given message should be handled. If {@code false} it will be passed to the next
* {@link ChannelInboundHandler} in the {@link ChannelPipeline}.
*/
public boolean acceptInboundMessage(Object msg) throws Exception {
return matcher.match(msg);
}

View File

@ -15,6 +15,7 @@
*/
package io.netty.channel;
import io.netty.util.concurrent.EventExecutorGroup;
import io.netty.util.concurrent.SingleThreadEventExecutor;
import java.util.concurrent.ThreadFactory;
@ -25,6 +26,9 @@ import java.util.concurrent.ThreadFactory;
*/
public abstract class SingleThreadEventLoop extends SingleThreadEventExecutor implements EventLoop {
/**
* @see {@link SingleThreadEventExecutor#SingleThreadEventExecutor(EventExecutorGroup, ThreadFactory, boolean)}
*/
protected SingleThreadEventLoop(EventLoopGroup parent, ThreadFactory threadFactory, boolean addTaskWakesUp) {
super(parent, threadFactory, addTaskWakesUp);
}