More javadocs

This commit is contained in:
Norman Maurer 2012-12-22 15:53:01 +01:00
parent 9098d069b0
commit fc4b205bc4
8 changed files with 80 additions and 9 deletions

View File

@ -19,7 +19,9 @@ import io.netty.buffer.ByteBuf;
import io.netty.buffer.MessageBuf; import io.netty.buffer.MessageBuf;
import io.netty.channel.ChannelFuture; import io.netty.channel.ChannelFuture;
import io.netty.channel.ChannelHandlerContext; import io.netty.channel.ChannelHandlerContext;
import io.netty.channel.ChannelOutboundMessageHandler;
import io.netty.channel.ChannelOutboundMessageHandlerAdapter; import io.netty.channel.ChannelOutboundMessageHandlerAdapter;
import io.netty.channel.ChannelPipeline;
import io.netty.channel.ChannelHandlerUtil; import io.netty.channel.ChannelHandlerUtil;
@ -44,6 +46,10 @@ public abstract class MessageToByteEncoder<I> extends ChannelOutboundMessageHand
private final Class<?>[] acceptedMsgTypes; 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) { protected MessageToByteEncoder(Class<?>... acceptedMsgTypes) {
this.acceptedMsgTypes = ChannelHandlerUtil.acceptedMessageTypes(acceptedMsgTypes); this.acceptedMsgTypes = ChannelHandlerUtil.acceptedMessageTypes(acceptedMsgTypes);
} }

View File

@ -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} * 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}. * and encode from {@link Long} to {@link Integer}.
*
* <pre> * <pre>
* public class NumberCodec extends * public class NumberCodec extends
* {@link MessageToMessageCodec}&lt;{@link Integer}, {@link Long}, {@link Long}, {@link Integer}&gt; { * {@link MessageToMessageCodec}&lt;{@link Integer}, {@link Long}, {@link Long}, {@link Integer}&gt; {

View File

@ -50,7 +50,7 @@ public abstract class MessageToMessageDecoder<I, O>
private final Class<?>[] acceptedMsgTypes; 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} * to the next {@link ChannelInboundMessageHandler} in the {@link ChannelPipeline}
*/ */
protected MessageToMessageDecoder(Class<?>... acceptedMsgTypes) { protected MessageToMessageDecoder(Class<?>... acceptedMsgTypes) {

View File

@ -23,8 +23,8 @@ import io.netty.channel.socket.SctpMessage;
import io.netty.handler.codec.CodecException; import io.netty.handler.codec.CodecException;
/** /**
* A ChannelHandler which receives {@link SctpMessage} belongs to a application protocol form a specific SCTP Stream * A ChannelHandler which receives {@link SctpMessage}s which belong to a application protocol form a specific
* and decode it as {@link ByteBuf}. * SCTP Stream and decode it as {@link ByteBuf}.
*/ */
public class SctpInboundByteStreamHandler extends ChannelInboundMessageHandlerAdapter<SctpMessage> { public class SctpInboundByteStreamHandler extends ChannelInboundMessageHandlerAdapter<SctpMessage> {
private final int protocolIdentifier; private final int protocolIdentifier;

View File

@ -34,8 +34,8 @@ public class SctpOutboundByteStreamHandler extends ChannelOutboundByteHandlerAda
private final int protocolIdentifier; private final int protocolIdentifier;
/** /**
* @param streamIdentifier stream number, this should be >=0 or <= max stream number of the association. * @param streamIdentifier stream number, this should be >=0 or <= max stream number of the association.
* @param protocolIdentifier supported application protocol id. * @param protocolIdentifier supported application protocol id.
*/ */
public SctpOutboundByteStreamHandler(int streamIdentifier, int protocolIdentifier) { public SctpOutboundByteStreamHandler(int streamIdentifier, int protocolIdentifier) {
this.streamIdentifier = streamIdentifier; this.streamIdentifier = streamIdentifier;

View File

@ -80,12 +80,12 @@ public interface ChannelConfig {
* Sets a configuration property with the specified name and value. * Sets a configuration property with the specified name and value.
* To override this method properly, you must call the super class: * To override this method properly, you must call the super class:
* <pre> * <pre>
* public boolean setOption(String name, Object value) { * public boolean setOption(ChannelOption&lt;T&gt; option, T value) {
* if (super.setOption(name, value)) { * if (super.setOption(option, value)) {
* return true; * return true;
* } * }
* *
* if (name.equals("additionalOption")) { * if (option.equals(additionalOption)) {
* .... * ....
* return true; * return true;
* } * }

View File

@ -18,11 +18,37 @@ package io.netty.channel;
import io.netty.buffer.MessageBuf; import io.netty.buffer.MessageBuf;
import io.netty.buffer.Unpooled; import io.netty.buffer.Unpooled;
/**
* {@link ChannelHandler} which handles inbound messages of a specific type.
*
* <pre>
* public class StringHandler extends
* {@link ChannelInboundMessageHandlerAdapter}&lt;{@link String}&gt; {
* public StringToIntegerDecoder() {
* super(String.class);
* }
*
* {@code @Override}
* public void messageReceived({@link ChannelHandlerContext} ctx, {@link String} message)
* throws {@link Exception} {
* // Do something with the String
* ...
* ...
* }
* }
* </pre>
*
* @param <I> The type of the messages to handle
*/
public abstract class ChannelInboundMessageHandlerAdapter<I> public abstract class ChannelInboundMessageHandlerAdapter<I>
extends ChannelInboundHandlerAdapter implements ChannelInboundMessageHandler<I> { extends ChannelInboundHandlerAdapter implements ChannelInboundMessageHandler<I> {
private final Class<?>[] acceptedMsgTypes; 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) { protected ChannelInboundMessageHandlerAdapter(Class<?>... acceptedMsgTypes) {
this.acceptedMsgTypes = ChannelHandlerUtil.acceptedMessageTypes(acceptedMsgTypes); this.acceptedMsgTypes = ChannelHandlerUtil.acceptedMessageTypes(acceptedMsgTypes);
} }
@ -92,10 +118,30 @@ public abstract class ChannelInboundMessageHandlerAdapter<I>
* This will return {@code true} by default, and may get overriden by sub-classes for * This will return {@code true} by default, and may get overriden by sub-classes for
* special handling. * special handling.
*/ */
@SuppressWarnings("unused")
public boolean beginMessageReceived(ChannelHandlerContext ctx) throws Exception { public boolean beginMessageReceived(ChannelHandlerContext ctx) throws Exception {
return true; 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 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
}
} }

View File

@ -25,6 +25,14 @@ import java.util.List;
import java.util.concurrent.ConcurrentHashMap; import java.util.concurrent.ConcurrentHashMap;
import java.util.concurrent.ConcurrentMap; 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 <T> the type of the value which is valid for the {@link ChannelOption}
*/
public class ChannelOption<T> extends UniqueName { public class ChannelOption<T> extends UniqueName {
private static final ConcurrentMap<String, Boolean> names = new ConcurrentHashMap<String, Boolean>(); private static final ConcurrentMap<String, Boolean> names = new ConcurrentHashMap<String, Boolean>();
@ -103,10 +111,20 @@ public class ChannelOption<T> extends UniqueName {
public static final ChannelOption<Long> AIO_WRITE_TIMEOUT = public static final ChannelOption<Long> AIO_WRITE_TIMEOUT =
new ChannelOption<Long>("AIO_WRITE_TIMEOUT"); new ChannelOption<Long>("AIO_WRITE_TIMEOUT");
/**
* Create a new {@link ChannelOption} with the given name. The name needs to be
* unique.
*
*/
public ChannelOption(String name) { public ChannelOption(String name) {
super(names, 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) { public void validate(T value) {
if (value == null) { if (value == null) {
throw new NullPointerException("value"); throw new NullPointerException("value");