From e7902e5c9984b635e8d79d84116d11351253b224 Mon Sep 17 00:00:00 2001 From: Jestan Nirojan Date: Sat, 26 May 2012 17:34:18 +0530 Subject: [PATCH] Improved documentation in SCTP Transport classes --- .../sctp/DefaultNioSctpChannelConfig.java | 2 +- .../sctp/DefaultSctpServerChannelConfig.java | 2 +- .../channel/sctp/NioSctpChannelConfig.java | 8 +-- .../channel/sctp/SctpBindAddressEvent.java | 3 - .../io/netty/channel/sctp/SctpChannel.java | 60 ++++++++++++------- .../netty/channel/sctp/SctpChannelConfig.java | 30 ++++++---- .../sctp/SctpClientSocketChannelFactory.java | 2 +- .../java/io/netty/channel/sctp/SctpFrame.java | 1 + .../netty/channel/sctp/SctpServerChannel.java | 32 +++++----- .../channel/sctp/SctpServerChannelConfig.java | 28 +++++---- .../channel/sctp/SctpServerChannelImpl.java | 5 -- .../sctp/SctpServerSocketChannelFactory.java | 2 +- .../channel/sctp/SctpUnbindAddressEvent.java | 3 - .../channel/sctp/codec/SctpFrameDecoder.java | 2 +- .../handler/SimpleSctpChannelHandler.java | 2 +- .../handler/SimpleSctpUpstreamHandler.java | 2 +- 16 files changed, 101 insertions(+), 83 deletions(-) diff --git a/transport-sctp/src/main/java/io/netty/channel/sctp/DefaultNioSctpChannelConfig.java b/transport-sctp/src/main/java/io/netty/channel/sctp/DefaultNioSctpChannelConfig.java index 0598804db8..44b7d072ce 100644 --- a/transport-sctp/src/main/java/io/netty/channel/sctp/DefaultNioSctpChannelConfig.java +++ b/transport-sctp/src/main/java/io/netty/channel/sctp/DefaultNioSctpChannelConfig.java @@ -27,7 +27,7 @@ import io.netty.logging.InternalLoggerFactory; import io.netty.util.internal.ConversionUtil; /** - * The default {@link io.netty.channel.socket.nio.NioSocketChannelConfig} implementation for SCTP. + * The default {@link NioSctpChannelConfig} implementation for SCTP. */ class DefaultNioSctpChannelConfig extends DefaultSctpChannelConfig implements NioSctpChannelConfig { diff --git a/transport-sctp/src/main/java/io/netty/channel/sctp/DefaultSctpServerChannelConfig.java b/transport-sctp/src/main/java/io/netty/channel/sctp/DefaultSctpServerChannelConfig.java index 56cccf2645..ebda407430 100644 --- a/transport-sctp/src/main/java/io/netty/channel/sctp/DefaultSctpServerChannelConfig.java +++ b/transport-sctp/src/main/java/io/netty/channel/sctp/DefaultSctpServerChannelConfig.java @@ -24,7 +24,7 @@ import io.netty.util.internal.ConversionUtil; import java.io.IOException; /** - * The default {@link io.netty.channel.socket.ServerSocketChannelConfig} implementation for SCTP. + * The default {@link SctpServerChannelConfig} implementation for SCTP. */ public class DefaultSctpServerChannelConfig extends DefaultServerChannelConfig implements SctpServerChannelConfig { diff --git a/transport-sctp/src/main/java/io/netty/channel/sctp/NioSctpChannelConfig.java b/transport-sctp/src/main/java/io/netty/channel/sctp/NioSctpChannelConfig.java index dfa1be49c7..dcc78b73bf 100644 --- a/transport-sctp/src/main/java/io/netty/channel/sctp/NioSctpChannelConfig.java +++ b/transport-sctp/src/main/java/io/netty/channel/sctp/NioSctpChannelConfig.java @@ -17,16 +17,16 @@ package io.netty.channel.sctp; import io.netty.channel.ReceiveBufferSizePredictor; import io.netty.channel.ReceiveBufferSizePredictorFactory; +import io.netty.channel.ChannelConfig; import io.netty.channel.socket.nio.NioChannelConfig; /** - * A {@link io.netty.channel.sctp.SctpChannelConfig} for a NIO SCTP/IP {@link io.netty.channel.sctp.SctpChannel}. + * The {@link SctpChannelConfig} for a NIO SCTP/IP {@link SctpChannel}. * *

Available options

* - * In addition to the options provided by {@link io.netty.channel.ChannelConfig} and - * {@link io.netty.channel.sctp.SctpChannelConfig}, {@link io.netty.channel.sctp.NioSctpChannelConfig} allows the - * following options in the option map: + * In addition to the options provided by {@link ChannelConfig} and {@link SctpChannelConfig}, + * {@link NioSctpChannelConfig} allows the following options in the option map: * * * diff --git a/transport-sctp/src/main/java/io/netty/channel/sctp/SctpBindAddressEvent.java b/transport-sctp/src/main/java/io/netty/channel/sctp/SctpBindAddressEvent.java index 40e71b2a4d..56b10b1282 100644 --- a/transport-sctp/src/main/java/io/netty/channel/sctp/SctpBindAddressEvent.java +++ b/transport-sctp/src/main/java/io/netty/channel/sctp/SctpBindAddressEvent.java @@ -24,9 +24,6 @@ import java.net.InetAddress; public class SctpBindAddressEvent extends DownstreamChannelStateEvent { - /** - * Creates a new instance. - */ public SctpBindAddressEvent(Channel channel, ChannelFuture future, InetAddress localAddress) { super(channel, future, ChannelState.INTEREST_OPS, localAddress); } diff --git a/transport-sctp/src/main/java/io/netty/channel/sctp/SctpChannel.java b/transport-sctp/src/main/java/io/netty/channel/sctp/SctpChannel.java index fd0d70c15b..ffedda3567 100644 --- a/transport-sctp/src/main/java/io/netty/channel/sctp/SctpChannel.java +++ b/transport-sctp/src/main/java/io/netty/channel/sctp/SctpChannel.java @@ -24,51 +24,69 @@ import java.net.InetSocketAddress; import java.util.Set; /** + * A SCTP/IP {@link Channel} which was either accepted by + * {@link SctpServerChannel} or created by {@link SctpClientSocketChannelFactory}. */ public interface SctpChannel extends Channel { /** - * Return the primary local address of the SCTP channel. + * Bind a address to the already bound channel to enable multi-homing. + * The Channel bust be bound and yet to be connected. + */ + ChannelFuture bindAddress(InetAddress localAddress); + + + /** + * Unbind the address from channel's multi-homing address list. + * The address should be added already in multi-homing address list. + */ + ChannelFuture unbindAddress(InetAddress localAddress); + + /** + * Returns the underlying SCTP association. + */ + Association association(); + + /** + * Return the (primary) local address of the SCTP channel. + * + * Please note that, this return the first local address in the underlying SCTP Channel's + * local address iterator. (this method is implemented to support existing Netty API) + * so application, has to keep track of it's primary address. This can be done by + * requests the local SCTP stack, using the SctpStandardSocketOption.SCTP_PRIMARY_ADDR. */ @Override InetSocketAddress getLocalAddress(); /** - * Return all local addresses of the SCTP channel. + * Return all local addresses of the SCTP channel. + * Please note that, it will return more than one address if this channel is using multi-homing */ Set getAllLocalAddresses(); /** - * Returns the configuration of this channel. + * Returns the {@link SctpChannelConfig} configuration of the channel. */ @Override NioSctpChannelConfig getConfig(); /** - * Return the primary remote address of the SCTP channel. + * Return the (primary) remote address of the SCTP channel. + * + * Please note that, this return the first remote address in the underlying SCTP Channel's + * remote address iterator. (this method is implemented to support existing Netty API) + * so application, has to keep track of remote's primary address. + * + * If a peer needs to request the remote to set a specific address as primary, It can + * requests the local SCTP stack, using the SctpStandardSocketOption.SCTP_SET_PEER_PRIMARY_ADDR. */ @Override InetSocketAddress getRemoteAddress(); /** - * Return all remote addresses of the SCTP channel. + * Return all remote addresses of the SCTP server channel. + * Please note that, it will return more than one address if the remote is using multi-homing. */ Set getAllRemoteAddresses(); - - /** - * Bind a multi-homing address to the already bound channel - */ - ChannelFuture bindAddress(InetAddress localAddress); - - - /** - * Unbind a multi-homing address from a already established channel - */ - ChannelFuture unbindAddress(InetAddress localAddress); - - /** - * Get the underlying SCTP association - */ - Association association(); } diff --git a/transport-sctp/src/main/java/io/netty/channel/sctp/SctpChannelConfig.java b/transport-sctp/src/main/java/io/netty/channel/sctp/SctpChannelConfig.java index 798285abcc..c717fbd9c6 100644 --- a/transport-sctp/src/main/java/io/netty/channel/sctp/SctpChannelConfig.java +++ b/transport-sctp/src/main/java/io/netty/channel/sctp/SctpChannelConfig.java @@ -19,12 +19,12 @@ import static com.sun.nio.sctp.SctpStandardSocketOptions.*; import io.netty.channel.ChannelConfig; /** - * A {@link io.netty.channel.ChannelConfig} for a {@link io.netty.channel.sctp.SctpChannel}. + * A {@link ChannelConfig} for a {@link SctpChannel}. *

*

Available options

*

- * In addition to the options provided by {@link io.netty.channel.ChannelConfig}, - * {@link io.netty.channel.sctp.SctpChannelConfig} allows the following options in the option map: + * In addition to the options provided by {@link ChannelConfig}, + * {@link SctpChannelConfig} allows the following options in the option map: *

*

* @@ -43,42 +43,50 @@ import io.netty.channel.ChannelConfig; public interface SctpChannelConfig extends ChannelConfig { /** - * Gets the {@code SCTP_NODELAY} option. + * Gets the + * {@code SCTP_NODELAY} option. */ boolean isSctpNoDelay(); /** - * Sets the {@code SCTP_NODELAY} option. + * Sets the + * {@code SCTP_NODELAY} option. */ void setSctpNoDelay(boolean sctpNoDelay); /** - * Gets the {@code SO_SNDBUF} option. + * Gets the + * {@code SO_SNDBUF} option. */ int getSendBufferSize(); /** - * Sets the {@code SO_SNDBUF} option. + * Sets the + * {@code SO_SNDBUF} option. */ void setSendBufferSize(int sendBufferSize); /** - * Gets the {@code SO_RCVBUF} option. + * Gets the + * {@code SO_RCVBUF} option. */ int getReceiveBufferSize(); /** - * Gets the {@code SO_RCVBUF} option. + * Gets the + * {@code SO_RCVBUF} option. */ void setReceiveBufferSize(int receiveBufferSize); /** - * Gets the {@code SCTP_INIT_MAXSTREAMS} option. + * Gets the + * {@code SCTP_INIT_MAXSTREAMS} option. */ InitMaxStreams getInitMaxStreams(); /** - * Gets the {@code SCTP_INIT_MAXSTREAMS} option. + * Gets the + * {@code SCTP_INIT_MAXSTREAMS} option. */ void setInitMaxStreams(InitMaxStreams initMaxStreams); } diff --git a/transport-sctp/src/main/java/io/netty/channel/sctp/SctpClientSocketChannelFactory.java b/transport-sctp/src/main/java/io/netty/channel/sctp/SctpClientSocketChannelFactory.java index 9fe1b23a3f..1af766ba19 100644 --- a/transport-sctp/src/main/java/io/netty/channel/sctp/SctpClientSocketChannelFactory.java +++ b/transport-sctp/src/main/java/io/netty/channel/sctp/SctpClientSocketChannelFactory.java @@ -82,7 +82,7 @@ public class SctpClientSocketChannelFactory implements ChannelFactory { /** * Creates a new instance. Calling this constructor is same with calling - * {@link #SctpClientSocketChannelFactory(java.util.concurrent.Executor, java.util.concurrent.Executor, int)} with 2 * + * {@link #SctpClientSocketChannelFactory(java.util.concurrent.Executor,int)} with 2 * * the number of available processors in the machine. The number of * available processors is obtained by {@link Runtime#availableProcessors()}. * diff --git a/transport-sctp/src/main/java/io/netty/channel/sctp/SctpFrame.java b/transport-sctp/src/main/java/io/netty/channel/sctp/SctpFrame.java index 3a12600f4c..fb129983fc 100644 --- a/transport-sctp/src/main/java/io/netty/channel/sctp/SctpFrame.java +++ b/transport-sctp/src/main/java/io/netty/channel/sctp/SctpFrame.java @@ -20,6 +20,7 @@ import io.netty.buffer.ChannelBuffer; import io.netty.buffer.ChannelBuffers; /** + * Representation of SCTP Data Chunk carried with {@link io.netty.channel.MessageEvent}. */ public final class SctpFrame { private final int streamIdentifier; diff --git a/transport-sctp/src/main/java/io/netty/channel/sctp/SctpServerChannel.java b/transport-sctp/src/main/java/io/netty/channel/sctp/SctpServerChannel.java index 3257f080d6..f8fb26066f 100644 --- a/transport-sctp/src/main/java/io/netty/channel/sctp/SctpServerChannel.java +++ b/transport-sctp/src/main/java/io/netty/channel/sctp/SctpServerChannel.java @@ -23,46 +23,44 @@ import java.net.InetSocketAddress; import java.util.Set; /** - * A SCTP {@link io.netty.channel.ServerChannel} which accepts incoming SCTP connections. + * A SCTP/IP {@link ServerChannel} which accepts incoming SCTP/IP connections. + * The {@link SctpServerChannel} provides the additional operations, available in the + * underlying JDK SCTP Server Channel like multi-homing etc. */ public interface SctpServerChannel extends ServerChannel { /** - * Bind a multi-homing address to the already bound channel + * Bind a address to the already bound channel to enable multi-homing. + * The Channel bust be bound and yet to be connected. */ ChannelFuture bindAddress(InetAddress localAddress); /** - * Unbind a multi-homing address from a already established channel + * Unbind the address from channel's multi-homing address list. + * The address should be added already in multi-homing address list. */ ChannelFuture unbindAddress(InetAddress localAddress); /** - * Returns the configuration of this channel. + * Returns the {@link SctpServerChannelConfig} configuration of the channel. */ @Override SctpServerChannelConfig getConfig(); /** - * Return the primary local address of the SCTP server channel. + * Return the (primary) local address of the SCTP server channel. + * + * Please note that, this return the first local address in the underlying SCTP ServerChannel's + * local address iterator. (this method is implemented to support existing Netty API) + * so application, has to keep track of it's primary address. This can be done by + * requests the local SCTP stack, using the SctpStandardSocketOption.SCTP_PRIMARY_ADDR. */ @Override InetSocketAddress getLocalAddress(); /** * Return all local addresses of the SCTP server channel. + * Please note that, it will return more than one address if this channel is using multi-homing */ Set getAllLocalAddresses(); - - /** - * Return the primary remote address of the server SCTP channel. - */ - @Override - InetSocketAddress getRemoteAddress(); - - - /** - * Return all remote addresses of the SCTP server channel. - */ - Set getAllRemoteAddresses(); } diff --git a/transport-sctp/src/main/java/io/netty/channel/sctp/SctpServerChannelConfig.java b/transport-sctp/src/main/java/io/netty/channel/sctp/SctpServerChannelConfig.java index 82732220a5..9f741afec7 100644 --- a/transport-sctp/src/main/java/io/netty/channel/sctp/SctpServerChannelConfig.java +++ b/transport-sctp/src/main/java/io/netty/channel/sctp/SctpServerChannelConfig.java @@ -20,11 +20,11 @@ import static com.sun.nio.sctp.SctpStandardSocketOptions.*; import io.netty.channel.ChannelConfig; /** - * A {@link io.netty.channel.ChannelConfig} for a {@link SctpServerChannelConfig}. + * A {@link ChannelConfig} for a {@link SctpServerChannelConfig}. *

*

Available options

*

- * In addition to the options provided by {@link io.netty.channel.ChannelConfig}, + * In addition to the options provided by {@link ChannelConfig}, * {@link SctpServerChannelConfig} allows the following options in the * option map: *

@@ -45,46 +45,50 @@ import io.netty.channel.ChannelConfig; public interface SctpServerChannelConfig extends ChannelConfig { /** - * Gets the backlog value to specify when the channel binds to a local - * address. + * Gets the backlog value to specify when the channel binds to a local address. */ int getBacklog(); /** - * Sets the backlog value to specify when the channel binds to a local - * address. + * Sets the backlog value to specify when the channel binds to a local address. */ void setBacklog(int backlog); /** - * Gets the {@code SO_SNDBUF} option. + * Gets the + * {@code SO_SNDBUF} option. */ int getSendBufferSize(); /** - * Sets the {@code SO_SNDBUF} option. + * Sets the + * {@code SO_SNDBUF} option. */ void setSendBufferSize(int sendBufferSize); /** - * Gets the {@code SO_RCVBUF} option. + * Gets the + * {@code SO_RCVBUF} option. */ int getReceiveBufferSize(); /** - * Gets the {@code SO_RCVBUF} option. + * Gets the + * {@code SO_RCVBUF} option. */ void setReceiveBufferSize(int receiveBufferSize); /** - * Gets the {@code SCTP_INIT_MAXSTREAMS} option. + * Gets the + * {@code SCTP_INIT_MAXSTREAMS} option. */ InitMaxStreams getInitMaxStreams(); /** - * Gets the {@code SCTP_INIT_MAXSTREAMS} option. + * Gets the + * {@code SCTP_INIT_MAXSTREAMS} option. */ void setInitMaxStreams(InitMaxStreams initMaxStreams); } diff --git a/transport-sctp/src/main/java/io/netty/channel/sctp/SctpServerChannelImpl.java b/transport-sctp/src/main/java/io/netty/channel/sctp/SctpServerChannelImpl.java index 5b54e77922..ff0b571633 100644 --- a/transport-sctp/src/main/java/io/netty/channel/sctp/SctpServerChannelImpl.java +++ b/transport-sctp/src/main/java/io/netty/channel/sctp/SctpServerChannelImpl.java @@ -136,11 +136,6 @@ class SctpServerChannelImpl extends AbstractServerChannel return null; // not available for server channel } - @Override - public Set getAllRemoteAddresses() { - return null; // not available for server channel - } - @Override public boolean isBound() { return isOpen() && bound; diff --git a/transport-sctp/src/main/java/io/netty/channel/sctp/SctpServerSocketChannelFactory.java b/transport-sctp/src/main/java/io/netty/channel/sctp/SctpServerSocketChannelFactory.java index c7a632db1c..c6a8201381 100644 --- a/transport-sctp/src/main/java/io/netty/channel/sctp/SctpServerSocketChannelFactory.java +++ b/transport-sctp/src/main/java/io/netty/channel/sctp/SctpServerSocketChannelFactory.java @@ -84,7 +84,7 @@ public class SctpServerSocketChannelFactory implements ServerChannelFactory { /** * Creates a new instance. Calling this constructor is same with calling - * {@link #SctpServerSocketChannelFactory(java.util.concurrent.Executor, java.util.concurrent.Executor, int)} with 2 * + * {@link #SctpServerSocketChannelFactory(java.util.concurrent.Executor, int)} with 2 * * the number of available processors in the machine. The number of * available processors is obtained by {@link Runtime#availableProcessors()}. * diff --git a/transport-sctp/src/main/java/io/netty/channel/sctp/SctpUnbindAddressEvent.java b/transport-sctp/src/main/java/io/netty/channel/sctp/SctpUnbindAddressEvent.java index f6d7e828bc..6a4b2b1bfa 100644 --- a/transport-sctp/src/main/java/io/netty/channel/sctp/SctpUnbindAddressEvent.java +++ b/transport-sctp/src/main/java/io/netty/channel/sctp/SctpUnbindAddressEvent.java @@ -24,9 +24,6 @@ import java.net.InetAddress; public class SctpUnbindAddressEvent extends DownstreamChannelStateEvent { - /** - * Creates a new instance. - */ public SctpUnbindAddressEvent(Channel channel, ChannelFuture future, InetAddress value) { super(channel, future, ChannelState.INTEREST_OPS, value); } diff --git a/transport-sctp/src/main/java/io/netty/channel/sctp/codec/SctpFrameDecoder.java b/transport-sctp/src/main/java/io/netty/channel/sctp/codec/SctpFrameDecoder.java index b3e6a9ca02..4d573fd8c1 100644 --- a/transport-sctp/src/main/java/io/netty/channel/sctp/codec/SctpFrameDecoder.java +++ b/transport-sctp/src/main/java/io/netty/channel/sctp/codec/SctpFrameDecoder.java @@ -24,7 +24,7 @@ import io.netty.channel.sctp.SctpFrame; import io.netty.handler.codec.oneone.OneToOneDecoder; /** - * SCTP Frame Decoder which extract payload channel buffer + * SCTP Frame Decoder which extract payload channel buffer. * Note: Supported SCTP Frame Interleave Level - 0 */ diff --git a/transport-sctp/src/main/java/io/netty/channel/sctp/handler/SimpleSctpChannelHandler.java b/transport-sctp/src/main/java/io/netty/channel/sctp/handler/SimpleSctpChannelHandler.java index 910fd0093b..b399947307 100644 --- a/transport-sctp/src/main/java/io/netty/channel/sctp/handler/SimpleSctpChannelHandler.java +++ b/transport-sctp/src/main/java/io/netty/channel/sctp/handler/SimpleSctpChannelHandler.java @@ -21,7 +21,7 @@ import io.netty.channel.SimpleChannelHandler; import io.netty.channel.sctp.SctpNotificationEvent; /** - * SCTP Channel Handler (upstream + downstream) with SCTP notification handling + * SCTP Channel Handler (upstream + downstream) with SCTP notification handling. */ public class SimpleSctpChannelHandler extends SimpleChannelHandler { diff --git a/transport-sctp/src/main/java/io/netty/channel/sctp/handler/SimpleSctpUpstreamHandler.java b/transport-sctp/src/main/java/io/netty/channel/sctp/handler/SimpleSctpUpstreamHandler.java index 37c3696de4..8d4c368b2d 100644 --- a/transport-sctp/src/main/java/io/netty/channel/sctp/handler/SimpleSctpUpstreamHandler.java +++ b/transport-sctp/src/main/java/io/netty/channel/sctp/handler/SimpleSctpUpstreamHandler.java @@ -21,7 +21,7 @@ import io.netty.channel.SimpleChannelUpstreamHandler; import io.netty.channel.sctp.SctpNotificationEvent; /** - * SCTP Upstream Channel Handler with SCTP notification handling + * SCTP Upstream Channel Handler with SCTP notification handling. */ public class SimpleSctpUpstreamHandler extends SimpleChannelUpstreamHandler {