- * A {@link Channel} can have a {@linkplain #getParent() parent} depending on + * A {@link Channel} can have a {@linkplain #parent() parent} depending on * how it was created. For instance, a {@link SocketChannel}, that was accepted * by {@link ServerSocketChannel}, will return the {@link ServerSocketChannel} - * as its parent on {@link #getParent()}. + * as its parent on {@link #parent()}. *
* The semantics of the hierarchical structure depends on the transport * implementation where the {@link Channel} belongs to. For example, you could @@ -68,38 +67,6 @@ import java.nio.channels.SelectionKey; * operations. For example, with the old I/O datagram transport, multicast * join / leave operations are provided by {@link DatagramChannel}. * - *
- * A {@link Channel} has a property called {@link #getInterestOps() interestOps} - * which is similar to that of {@link SelectionKey#interestOps() NIO SelectionKey}. - * It is represented as a bit - * field which is composed of the two flags. - *
- * You can set or clear the {@link #OP_READ} flag to suspend and resume read - * operation via {@link #setReadable(boolean)}. - *
- * Please note that you cannot suspend or resume write operation just like you - * can set or clear {@link #OP_READ}. The {@link #OP_WRITE} flag is read only - * and provided simply as a mean to tell you if the size of pending write - * requests exceeded a certain threshold or not so that you don't issue too many - * pending writes that lead to an {@link OutOfMemoryError}. For example, the - * NIO socket transport uses the {@code writeBufferLowWaterMark} and - * {@code writeBufferHighWaterMark} properties in {@link NioSocketChannelConfig} - * to determine when to set or clear the {@link #OP_WRITE} flag. - *
* @apiviz.landmark * @apiviz.composedOf io.netty.channel.ChannelConfig * @apiviz.composedOf io.netty.channel.ChannelPipeline @@ -131,8 +98,19 @@ public interface Channel extends AttributeMap, ChannelOutboundInvoker, ChannelPr */ ChannelConfig config(); + /** + * Returns {@code true} if the {@link Channel} is open an may get active later + */ boolean isOpen(); + + /** + * Returns {@code true} if the {@link Channel} is registered with an {@link EventLoop}. + */ boolean isRegistered(); + + /** + * Return {@code true} if the {@link Channel} is active and so connected. + */ boolean isActive(); /** diff --git a/transport/src/main/java/io/netty/channel/ChannelHandlerContext.java b/transport/src/main/java/io/netty/channel/ChannelHandlerContext.java index 6dd61e89a5..d4cca647c3 100755 --- a/transport/src/main/java/io/netty/channel/ChannelHandlerContext.java +++ b/transport/src/main/java/io/netty/channel/ChannelHandlerContext.java @@ -18,6 +18,8 @@ package io.netty.channel; import io.netty.buffer.ByteBuf; import io.netty.buffer.MessageBuf; +import io.netty.util.Attribute; +import io.netty.util.AttributeKey; import io.netty.util.AttributeMap; import java.nio.channels.Channels; @@ -25,20 +27,19 @@ import java.util.Set; /** * Enables a {@link ChannelHandler} to interact with its {@link ChannelPipeline} - * and other handlers. A handler can send a {@link ChannelEvent} upstream or - * downstream, modify the {@link ChannelPipeline} it belongs to dynamically. + * and other handlers. A handler can notify the next {@link ChannelHandler} in the {@link ChannelPipeline}, + * modify the {@link ChannelPipeline} it belongs to dynamically. * - *
- * public class MyHandler extends {@link SimpleChannelHandler}
- * implements {@link LifeCycleAwareChannelHandler} {
+ * public class MyHandler extends {@link ChannelHandlerAdapter} {
*
* private {@link ChannelHandlerContext} ctx;
*
@@ -56,10 +56,7 @@ import java.util.Set;
* }
*
* public void login(String username, password) {
- * {@link Channels}.write(
- * this.ctx,
- * {@link Channels}.succeededFuture(this.ctx.getChannel()),
- * new LoginMessage(username, password));
+ * ctx.write(new LoginMessage(username, password));
* }
* ...
* }
@@ -67,7 +64,7 @@ import java.util.Set;
*
* Storing stateful information
*
- * {@link #setAttachment(Object)} and {@link #getAttachment()} allow you to
+ * {@link #attr(AttributeKey)} allow you to
* store and access stateful information that is related with a handler and its
* context. Please refer to {@link ChannelHandler} to learn various recommended
* ways to manage stateful information.
@@ -85,20 +82,23 @@ import java.util.Set;
* as how many times it is added to pipelines, regardless if it is added to the
* same pipeline multiple times or added to different pipelines multiple times:
*
- * public class FactorialHandler extends {@link SimpleChannelHandler} {
+ * public class FactorialHandler extends {@link ChannelInboundMessageHandlerAdapter}<{@link Integer}> {
+ *
+ * private final {@link AttributeKey}<{@link Integer}> counter =
+ * new {@link AttributeKey}<{@link Integer}>("counter");
*
* // This handler will receive a sequence of increasing integers starting
* // from 1.
* {@code @Override}
- * public void messageReceived({@link ChannelHandlerContext} ctx, {@link MessageEvent} evt) {
- * Integer a = (Integer) ctx.getAttachment();
- * Integer b = (Integer) evt.getMessage();
+ * public void messageReceived({@link ChannelHandlerContext} ctx, {@link Integer} integer) {
+ * {@link Attribute}<{@link Integer}>} attr = ctx.getAttr(counter);
+ * Integer a = ctx.getAttr(counter).get();
*
* if (a == null) {
* a = 1;
* }
*
- * ctx.setAttachment(Integer.valueOf(a * b));
+ * attr.set(a * integer));
* }
* }
*
@@ -119,10 +119,10 @@ import java.util.Set;
*
* Additional resources worth reading
*
- * Please refer to the {@link ChannelHandler}, {@link ChannelEvent}, and
- * {@link ChannelPipeline} to find out what a upstream event and a downstream
- * event are, what fundamental differences they have, how they flow in a
- * pipeline, and how to handle the event in your application.
+ * Please refer to the {@link ChannelHandler}, and
+ * {@link ChannelPipeline} to find out more about inbound and outbound operations,
+ * what fundamental differences they have, how they flow in a pipeline, and how to handle
+ * the operation in your application.
* @apiviz.owns io.netty.channel.ChannelHandler
*/
public interface ChannelHandlerContext
diff --git a/transport/src/main/java/io/netty/channel/ChannelOperationHandler.java b/transport/src/main/java/io/netty/channel/ChannelOperationHandler.java
index 4868565283..ebde7e8ae7 100644
--- a/transport/src/main/java/io/netty/channel/ChannelOperationHandler.java
+++ b/transport/src/main/java/io/netty/channel/ChannelOperationHandler.java
@@ -17,15 +17,77 @@ package io.netty.channel;
import java.net.SocketAddress;
+/**
+ * {@link ChannelHandler} which will get notified for IO-outbound-operations.
+ */
public interface ChannelOperationHandler extends ChannelHandler {
+ /**
+ * Called once a bind operation is made.
+ *
+ * @param ctx the {@link ChannelHandlerContext} for which the bind operation is made
+ * @param localAddress the {@link SocketAddress} to which it should bound
+ * @param future the {@link ChannelFuture} to notify once the operation completes
+ * @throws Exception thrown if an error accour
+ */
void bind(ChannelHandlerContext ctx, SocketAddress localAddress, ChannelFuture future) throws Exception;
+
+ /**
+ * Called once a connect operation is made.
+ *
+ * @param ctx the {@link ChannelHandlerContext} for which the connect operation is made
+ * @param remoteAddress the {@link SocketAddress} to which it should connect
+ * @param localAddress the {@link SocketAddress} which is used as source on connect
+ * @param future the {@link ChannelFuture} to notify once the operation completes
+ * @throws Exception thrown if an error accour
+ */
void connect(
ChannelHandlerContext ctx, SocketAddress remoteAddress,
SocketAddress localAddress, ChannelFuture future) throws Exception;
+
+ /**
+ * Called once a disconnect operation is made.
+ *
+ * @param ctx the {@link ChannelHandlerContext} for which the disconnect operation is made
+ * @param future the {@link ChannelFuture} to notify once the operation completes
+ * @throws Exception thrown if an error accour
+ */
void disconnect(ChannelHandlerContext ctx, ChannelFuture future) throws Exception;
+
+ /**
+ * Called once a close operation is made.
+ *
+ * @param ctx the {@link ChannelHandlerContext} for which the close operation is made
+ * @param future the {@link ChannelFuture} to notify once the operation completes
+ * @throws Exception thrown if an error accour
+ */
void close(ChannelHandlerContext ctx, ChannelFuture future) throws Exception;
+
+ /**
+ * Called once a deregister operation is made from the current registered {@link EventLoop}.
+ *
+ * @param ctx the {@link ChannelHandlerContext} for which the close operation is made
+ * @param future the {@link ChannelFuture} to notify once the operation completes
+ * @throws Exception thrown if an error accour
+ */
void deregister(ChannelHandlerContext ctx, ChannelFuture future) throws Exception;
+
+ /**
+ * Called once a flush operation is made and so the outbound data should be written.
+ *
+ * @param ctx the {@link ChannelHandlerContext} for which the flush operation is made
+ * @param future the {@link ChannelFuture} to notify once the operation completes
+ * @throws Exception thrown if an error accour
+ */
void flush(ChannelHandlerContext ctx, ChannelFuture future) throws Exception;
+
+ /**
+ * Called once a sendFile operation is made and so the {@link FileRegion} should be transfered.
+ *
+ * @param ctx the {@link ChannelHandlerContext} for which the flush operation is made
+ * @param region the {@link FileRegion} to transfer
+ * @param future the {@link ChannelFuture} to notify once the operation completes
+ * @throws Exception thrown if an error accour
+ */
void sendFile(ChannelHandlerContext ctx, FileRegion region, ChannelFuture future) throws Exception;
}
diff --git a/transport/src/main/java/io/netty/channel/socket/DatagramPacket.java b/transport/src/main/java/io/netty/channel/socket/DatagramPacket.java
index 161ed5c3f6..0a1c9a2ba3 100644
--- a/transport/src/main/java/io/netty/channel/socket/DatagramPacket.java
+++ b/transport/src/main/java/io/netty/channel/socket/DatagramPacket.java
@@ -27,6 +27,13 @@ public final class DatagramPacket {
private final ByteBuf data;
private final InetSocketAddress remoteAddress;
+ /**
+ * Create a new instance
+ *
+ * @param data the {@link ByteBuf} which holds the data of the packet
+ * @param remoteAddress the (@link InetSocketAddress} from which the packet was received or to which the
+ * packet will be send
+ */
public DatagramPacket(ByteBuf data, InetSocketAddress remoteAddress) {
if (data == null) {
throw new NullPointerException("data");
@@ -48,7 +55,6 @@ public final class DatagramPacket {
/**
* The {@link InetSocketAddress} which this {@link DatagramPacket} will send to or was received from.
- * If {@code null} is used the default address will be used which the {@link DatagramChannel} was connected to.
*/
public InetSocketAddress remoteAddress() {
return remoteAddress;
diff --git a/transport/src/main/java/io/netty/channel/socket/nio/ProtocolFamilyConverter.java b/transport/src/main/java/io/netty/channel/socket/nio/ProtocolFamilyConverter.java
index ec8f3665ca..e4f4dc23cf 100644
--- a/transport/src/main/java/io/netty/channel/socket/nio/ProtocolFamilyConverter.java
+++ b/transport/src/main/java/io/netty/channel/socket/nio/ProtocolFamilyConverter.java
@@ -22,8 +22,6 @@ import java.net.StandardProtocolFamily;
/**
* Helper class which convert the {@link InternetProtocolFamily}.
- *
- *
*/
final class ProtocolFamilyConverter {
@@ -38,7 +36,6 @@ final class ProtocolFamilyConverter {
switch (family) {
case IPv4:
return StandardProtocolFamily.INET;
-
case IPv6:
return StandardProtocolFamily.INET6;
default: