From 39250873ae7c3d8c1017db11b1f715838f2688f3 Mon Sep 17 00:00:00 2001 From: Norman Maurer Date: Mon, 17 Dec 2012 16:01:58 +0100 Subject: [PATCH] Add some javadocs --- .../main/java/io/netty/channel/Channel.java | 7 +- .../netty/channel/ChannelOutboundInvoker.java | 124 ++++++++++++++++++ .../netty/channel/socket/DatagramChannel.java | 83 ++++++++++-- .../netty/channel/socket/DatagramPacket.java | 10 ++ .../socket/InternetProtocolFamily.java | 2 +- .../io/netty/channel/socket/SctpChannel.java | 4 + .../io/netty/channel/socket/SctpMessage.java | 4 +- .../netty/channel/socket/SocketChannel.java | 2 + 8 files changed, 221 insertions(+), 15 deletions(-) diff --git a/transport/src/main/java/io/netty/channel/Channel.java b/transport/src/main/java/io/netty/channel/Channel.java index 4ef3b02333..b84d871546 100755 --- a/transport/src/main/java/io/netty/channel/Channel.java +++ b/transport/src/main/java/io/netty/channel/Channel.java @@ -164,7 +164,7 @@ public interface Channel extends AttributeMap, ChannelOutboundInvoker, ChannelPr * {@code null} if this channel is not connected. * If this channel is not connected but it can receive messages * from arbitrary remote addresses (e.g. {@link DatagramChannel}, - * use {@link MessageEvent#getRemoteAddress()} to determine + * use {@link io.netty.channel.socket.DatagramPacket#remoteAddress()} to determine * the origination of the received message as this method will * return {@code null}. */ @@ -277,6 +277,11 @@ public interface Channel extends AttributeMap, ChannelOutboundInvoker, ChannelPr */ void resumeRead(); + /** + * Send a {@link FileRegion} to the remote peer and notify the {@link ChannelFuture} once it completes + * or an error was detected. Once the {@link FileRegion} was transfered or an error was thrown it will + * automaticly closed via {@link io.netty.channel.FileRegion#close()}. + */ void sendFile(FileRegion region, ChannelFuture future); } } diff --git a/transport/src/main/java/io/netty/channel/ChannelOutboundInvoker.java b/transport/src/main/java/io/netty/channel/ChannelOutboundInvoker.java index fe51460202..9620f20140 100644 --- a/transport/src/main/java/io/netty/channel/ChannelOutboundInvoker.java +++ b/transport/src/main/java/io/netty/channel/ChannelOutboundInvoker.java @@ -18,23 +18,147 @@ package io.netty.channel; import java.net.SocketAddress; public interface ChannelOutboundInvoker { + /** + * Bind to the given {@link SocketAddress} and notify the {@link ChannelFuture} once the operation completes, + * either because the operation was successful or because of an error. + */ ChannelFuture bind(SocketAddress localAddress); + + /** + * Connect to the given {@link SocketAddress} and notify the {@link ChannelFuture} once the operation completes, + * either because the operation was successful or because of + * an error. + */ ChannelFuture connect(SocketAddress remoteAddress); + + /** + * Connect to the given {@link SocketAddress} while bind to the localAddress and notify the {@link ChannelFuture} + * once the operation completes, either because the operation was successful or because of + * an error. + */ ChannelFuture connect(SocketAddress remoteAddress, SocketAddress localAddress); + + /** + * Discconect from the remote peer and notify the {@link ChannelFuture} once the operation completes, + * either because the operation was successful or because of + * an error. + */ ChannelFuture disconnect(); + + /** + * Close this ChannelOutboundInvoker and notify the {@link ChannelFuture} once the operation completes, + * either because the operation was successful or because of + * an error. + * + * After it is closed it is not possible to reuse it again. + */ ChannelFuture close(); + + /** + * Deregister this ChannelOutboundInvoker from the previous assigned {@link EventExecutor} and notify the + * {@link ChannelFuture} once the operation completes, either because the operation was successful or because of + * an error. + * + */ ChannelFuture deregister(); + + /** + * Flush all pending data which belongs to this ChannelOutboundInvoker and notify the {@link ChannelFuture} + * once the operation completes, either because the operation was successful or because of an error. + */ ChannelFuture flush(); + + /** + * Write a message via this ChannelOutboundInvoker and notify the {@link ChannelFuture} + * once the operation completes, either because the operation was successful or because of an error. + * + * If you want to write a {@link FileRegion} use {@link #sendFile(FileRegion)} + */ ChannelFuture write(Object message); + + /** + * Send a {@link FileRegion} via this ChannelOutboundInvoker and notify the {@link ChannelFuture} + * once the operation completes, either because the operation was successful or because of an error. + */ ChannelFuture sendFile(FileRegion region); + /** + * Bind to the given {@link SocketAddress} and notify the {@link ChannelFuture} once the operation completes, + * either because the operation was successful or because of an error. + * + * The given {@link ChannelFuture} will be notified and also returned. + */ ChannelFuture bind(SocketAddress localAddress, ChannelFuture future); + + /** + * Connect to the given {@link SocketAddress} and notify the {@link ChannelFuture} once the operation completes, + * either because the operation was successful or because of + * an error. + * + * The given {@link ChannelFuture} will be notified and also returned. + */ ChannelFuture connect(SocketAddress remoteAddress, ChannelFuture future); + + /** + * Connect to the given {@link SocketAddress} while bind to the localAddress and notify the {@link ChannelFuture} + * once the operation completes, either because the operation was successful or because of + * an error. + * + * The given {@link ChannelFuture} will be notified and also returned. + */ ChannelFuture connect(SocketAddress remoteAddress, SocketAddress localAddress, ChannelFuture future); + + /** + * Discconect from the remote peer and notify the {@link ChannelFuture} once the operation completes, + * either because the operation was successful or because of + * an error. + * + * The given {@link ChannelFuture} will be notified and also returned. + */ ChannelFuture disconnect(ChannelFuture future); + + /** + * Close this ChannelOutboundInvoker and notify the {@link ChannelFuture} once the operation completes, + * either because the operation was successful or because of + * an error. + * + * After it is closed it is not possible to reuse it again. + * The given {@link ChannelFuture} will be notified and also returned. + */ ChannelFuture close(ChannelFuture future); + + /** + * Deregister this ChannelOutboundInvoker from the previous assigned {@link EventExecutor} and notify the + * {@link ChannelFuture} once the operation completes, either because the operation was successful or because of + * an error. + * + * The given {@link ChannelFuture} will be notified and also returned. + */ ChannelFuture deregister(ChannelFuture future); + + /** + * Flush all pending data which belongs to this ChannelOutboundInvoker and notify the {@link ChannelFuture} + * once the operation completes, either because the operation was successful or because of an error. + * + * The given {@link ChannelFuture} will be notified and also returned. + */ ChannelFuture flush(ChannelFuture future); + + /** + * Write a message via this ChannelOutboundInvoker and notify the {@link ChannelFuture} + * once the operation completes, either because the operation was successful or because of an error. + * + * If you want to write a {@link FileRegion} use {@link #sendFile(FileRegion)} + * The given {@link ChannelFuture} will be notified and also returned. + */ ChannelFuture write(Object message, ChannelFuture future); + + + /** + * Send a {@link FileRegion} via this ChannelOutboundInvoker and notify the {@link ChannelFuture} + * once the operation completes, either because the operation was successful or because of an error. + * + * The given {@link ChannelFuture} will be notified and also returned. + */ ChannelFuture sendFile(FileRegion region, ChannelFuture future); } diff --git a/transport/src/main/java/io/netty/channel/socket/DatagramChannel.java b/transport/src/main/java/io/netty/channel/socket/DatagramChannel.java index 7901d238d3..5eb06a5406 100644 --- a/transport/src/main/java/io/netty/channel/socket/DatagramChannel.java +++ b/transport/src/main/java/io/netty/channel/socket/DatagramChannel.java @@ -23,7 +23,7 @@ import java.net.InetSocketAddress; import java.net.NetworkInterface; /** - * A UDP/IP {@link Channel} which is created by {@link DatagramChannelFactory}. + * A UDP/IP {@link Channel}}. * @apiviz.landmark * @apiviz.composedOf io.netty.channel.socket.DatagramChannelConfig */ @@ -35,70 +35,131 @@ public interface DatagramChannel extends Channel { @Override InetSocketAddress remoteAddress(); + /** + * Return {@code true} if the {@link DatagramChannel} is connected to the remote peer. + */ boolean isConnected(); /** - * Joins a multicast group. + * Joins a multicast group and notifies the {@link ChannelFuture} once the operation completes. */ ChannelFuture joinGroup(InetAddress multicastAddress); + + /** + * Joins a multicast group and notifies the {@link ChannelFuture} once the operation completes. + * + * The given {@link ChannelFuture} will be notified and also returned. + */ ChannelFuture joinGroup(InetAddress multicastAddress, ChannelFuture future); /** - * Joins the specified multicast group at the specified interface. + * Joins the specified multicast group at the specified interface and notifies the {@link ChannelFuture} + * once the operation completes. */ ChannelFuture joinGroup(InetSocketAddress multicastAddress, NetworkInterface networkInterface); + + /** + * Joins the specified multicast group at the specified interface and notifies the {@link ChannelFuture} + * once the operation completes. + * + * The given {@link ChannelFuture} will be notified and also returned. + */ ChannelFuture joinGroup( InetSocketAddress multicastAddress, NetworkInterface networkInterface, ChannelFuture future); + /** + * Joins the specified multicast group at the specified interface and notifies the {@link ChannelFuture} + * once the operation completes. + */ ChannelFuture joinGroup(InetAddress multicastAddress, NetworkInterface networkInterface, InetAddress source); + + /** + * Joins the specified multicast group at the specified interface and notifies the {@link ChannelFuture} + * once the operation completes. + * + * The given {@link ChannelFuture} will be notified and also returned. + */ ChannelFuture joinGroup( InetAddress multicastAddress, NetworkInterface networkInterface, InetAddress source, ChannelFuture future); /** - * Leaves a multicast group. + * Leaves a multicast group and notifies the {@link ChannelFuture} once the operation completes. */ ChannelFuture leaveGroup(InetAddress multicastAddress); + + /** + * Leaves a multicast group and notifies the {@link ChannelFuture} once the operation completes. + * + * The given {@link ChannelFuture} will be notified and also returned. + */ ChannelFuture leaveGroup(InetAddress multicastAddress, ChannelFuture future); /** - * Leaves a multicast group on a specified local interface. + * Leaves a multicast group on a specified local interface and notifies the {@link ChannelFuture} once the + * operation completes. */ ChannelFuture leaveGroup(InetSocketAddress multicastAddress, NetworkInterface networkInterface); + + /** + * Leaves a multicast group on a specified local interface and notifies the {@link ChannelFuture} once the + * operation completes. + * + * The given {@link ChannelFuture} will be notified and also returned. + */ ChannelFuture leaveGroup( InetSocketAddress multicastAddress, NetworkInterface networkInterface, ChannelFuture future); /** - * Leave the specified multicast group at the specified interface using the specified source. + * Leave the specified multicast group at the specified interface using the specified source and notifies + * the {@link ChannelFuture} once the operation completes. + * */ ChannelFuture leaveGroup( InetAddress multicastAddress, NetworkInterface networkInterface, InetAddress source); + + /** + * Leave the specified multicast group at the specified interface using the specified source and notifies + * the {@link ChannelFuture} once the operation completes. + * + * The given {@link ChannelFuture} will be notified and also returned. + */ ChannelFuture leaveGroup( InetAddress multicastAddress, NetworkInterface networkInterface, InetAddress source, ChannelFuture future); - /** - * Block the given sourceToBlock address for the given multicastAddress on the given networkInterface + /** + * Block the given sourceToBlock address for the given multicastAddress on the given networkInterface and notifies + * the {@link ChannelFuture} once the operation completes. + * + * The given {@link ChannelFuture} will be notified and also returned. */ ChannelFuture block( InetAddress multicastAddress, NetworkInterface networkInterface, InetAddress sourceToBlock); /** - * Block the given sourceToBlock address for the given multicastAddress on the given networkInterface + * Block the given sourceToBlock address for the given multicastAddress on the given networkInterface and notifies + * the {@link ChannelFuture} once the operation completes. + * + * The given {@link ChannelFuture} will be notified and also returned. */ ChannelFuture block( InetAddress multicastAddress, NetworkInterface networkInterface, InetAddress sourceToBlock, ChannelFuture future); /** - * Block the given sourceToBlock address for the given multicastAddress + * Block the given sourceToBlock address for the given multicastAddress and notifies the {@link ChannelFuture} once + * the operation completes. * + * The given {@link ChannelFuture} will be notified and also returned. */ ChannelFuture block(InetAddress multicastAddress, InetAddress sourceToBlock); /** - * Block the given sourceToBlock address for the given multicastAddress + * Block the given sourceToBlock address for the given multicastAddress and notifies the {@link ChannelFuture} once + * the operation completes. * + * The given {@link ChannelFuture} will be notified and also returned. */ ChannelFuture block( InetAddress multicastAddress, InetAddress sourceToBlock, ChannelFuture future); 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 9f096161ae..dc1379f588 100644 --- a/transport/src/main/java/io/netty/channel/socket/DatagramPacket.java +++ b/transport/src/main/java/io/netty/channel/socket/DatagramPacket.java @@ -19,6 +19,9 @@ import io.netty.buffer.ByteBuf; import java.net.InetSocketAddress; +/** + * The message container that is used for {@link DatagramChannel} to communicate with the remote peer. + */ public class DatagramPacket { private final ByteBuf data; @@ -36,10 +39,17 @@ public class DatagramPacket { this.remoteAddress = remoteAddress; } + /** + * Return the data which is container. May return an empty {@link ByteBuf} + */ public ByteBuf data() { return data; } + /** + * 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/InternetProtocolFamily.java b/transport/src/main/java/io/netty/channel/socket/InternetProtocolFamily.java index c18273cac1..d276abc095 100644 --- a/transport/src/main/java/io/netty/channel/socket/InternetProtocolFamily.java +++ b/transport/src/main/java/io/netty/channel/socket/InternetProtocolFamily.java @@ -16,7 +16,7 @@ package io.netty.channel.socket; /** - * Internet Protocol (IP) families + * Internet Protocol (IP) families used byte the {@link DatagramChannel} */ public enum InternetProtocolFamily { IPv4, diff --git a/transport/src/main/java/io/netty/channel/socket/SctpChannel.java b/transport/src/main/java/io/netty/channel/socket/SctpChannel.java index 5c4e1cc52b..e648243d6b 100644 --- a/transport/src/main/java/io/netty/channel/socket/SctpChannel.java +++ b/transport/src/main/java/io/netty/channel/socket/SctpChannel.java @@ -85,6 +85,8 @@ public interface SctpChannel extends Channel { /** * Bind a address to the already bound channel to enable multi-homing. * The Channel bust be bound and yet to be connected. + * + * The given {@link ChannelFuture} will be notified and also returned. */ ChannelFuture bindAddress(InetAddress localAddress, ChannelFuture future); @@ -97,6 +99,8 @@ public interface SctpChannel extends Channel { /** * Unbind the address from channel's multi-homing address list. * The address should be added already in multi-homing address list. + * + * The given {@link ChannelFuture} will be notified and also returned. */ ChannelFuture unbindAddress(InetAddress localAddress, ChannelFuture future); } diff --git a/transport/src/main/java/io/netty/channel/socket/SctpMessage.java b/transport/src/main/java/io/netty/channel/socket/SctpMessage.java index 3e675f9e1c..3365d55e87 100644 --- a/transport/src/main/java/io/netty/channel/socket/SctpMessage.java +++ b/transport/src/main/java/io/netty/channel/socket/SctpMessage.java @@ -28,8 +28,7 @@ public final class SctpMessage { private final int protocolIdentifier; private final ByteBuf payloadBuffer; - - private MessageInfo msgInfo; + private final MessageInfo msgInfo; /** * Essential data that is being carried within SCTP Data Chunk @@ -41,6 +40,7 @@ public final class SctpMessage { this.protocolIdentifier = protocolIdentifier; this.streamIdentifier = streamIdentifier; this.payloadBuffer = payloadBuffer; + this.msgInfo = null; } public SctpMessage(MessageInfo msgInfo, ByteBuf payloadBuffer) { diff --git a/transport/src/main/java/io/netty/channel/socket/SocketChannel.java b/transport/src/main/java/io/netty/channel/socket/SocketChannel.java index d856dc80ce..5eb6303225 100644 --- a/transport/src/main/java/io/netty/channel/socket/SocketChannel.java +++ b/transport/src/main/java/io/netty/channel/socket/SocketChannel.java @@ -54,6 +54,8 @@ public interface SocketChannel extends Channel { /** * @see Socket#shutdownOutput() + * + * Will notify and return the given {@link ChannelFuture} */ ChannelFuture shutdownOutput(ChannelFuture future); }