Please note that this documentation is not final and is subject to change.

JavaTM SCTP API
DRAFT ea-b10

com.sun.nio.sctp
Class SctpStandardSocketOption

java.lang.Object
  extended by com.sun.nio.sctp.SctpStandardSocketOption

public class SctpStandardSocketOption
extends Object

An SCTP channel supports the socket options defined by this class (as well as those listed in the particular channel class) and may support additional Implementation specific socket options.

Since:
1.7

Nested Class Summary
static class SctpStandardSocketOption.InitMaxStreams
          This class is used to set the maximum number of inbound/outbound streams used by the local endpoint during association initialization.
 
Field Summary
static SctpSocketOption<Boolean> SCTP_DISABLE_FRAGMENTS
          Enables or disables message fragmentation.
static SctpSocketOption<Boolean> SCTP_EXPLICIT_COMPLETE
          Enables or disables explicit message completion.
static SctpSocketOption<Integer> SCTP_FRAGMENT_INTERLEAVE
          Fragmented interleave controls how the presentation of messages occur for the message receiver.
static SctpSocketOption<SctpStandardSocketOption.InitMaxStreams> SCTP_INIT_MAXSTREAMS
          The maximum number of streams requested by the local endpoint during association initialization.
static SctpSocketOption<Boolean> SCTP_NODELAY
          Enables or disables a Nagle-like algorithm.
static SctpSocketOption<SocketAddress> SCTP_PRIMARY_ADDR
          Requests that the local SCTP stack use the given peer address as the association primary.
static SctpSocketOption<SocketAddress> SCTP_SET_PEER_PRIMARY_ADDR
          Requests that the peer mark the enclosed address as the association primary.
static SctpSocketOption<Integer> SO_LINGER
          Linger on close if data is present.
static SctpSocketOption<Integer> SO_RCVBUF
          The size of the socket receive buffer.
static SctpSocketOption<Integer> SO_SNDBUF
          The size of the socket send buffer.
 
Method Summary
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

SCTP_DISABLE_FRAGMENTS

public static final SctpSocketOption<Boolean> SCTP_DISABLE_FRAGMENTS
Enables or disables message fragmentation.

The value of this socket option is a Boolean that represents whether the option is enabled or disabled. If enabled no SCTP message fragmentation will be performed. Instead if a message being sent exceeds the current PMTU size, the message will NOT be sent and an error will be indicated to the user.

It is implementation specific whether or not this option is supported.


SCTP_EXPLICIT_COMPLETE

public static final SctpSocketOption<Boolean> SCTP_EXPLICIT_COMPLETE
Enables or disables explicit message completion.

The value of this socket option is a Boolean that represents whether the option is enabled or disabled. When this option is enabled, the send method may be invoked multiple times to a send message. The isComplete parameter of the MessageInfo must only be set to true for the final send to indicate that the message is complete. If this option is disabled then each individual send invocation is considered complete.

The default value of the option is false indicating that the option is disabled. It is implementation specific whether or not this option is supported.


SCTP_FRAGMENT_INTERLEAVE

public static final SctpSocketOption<Integer> SCTP_FRAGMENT_INTERLEAVE
Fragmented interleave controls how the presentation of messages occur for the message receiver. There are three levels of fragment interleave defined. Two of the levels effect SctpChannel, while SctpMultiChannel is effected by all three levels.

This option takes an Integer value. It can be set to a value of 0, 1 or 2.

Setting the three levels provides the following receiver interactions:

level 0 - Prevents the interleaving of any messages. This means that when a partial delivery begins, no other messages will be received except the message being partially delivered. If another message arrives on a different stream (or association) that could be delivered, it will be blocked waiting for the user to read all of the partially delivered message.

level 1 - Allows interleaving of messages that are from different associations. For SctpChannel, level 0 and level 1 have the same meaning since an SctpChannel always receives messages from the same association. Note that setting an SctpMultiChannel to this level may cause multiple partial delivers from different associations but for any given association, only one message will be delivered until all parts of a message have been delivered. This means that one large message, being read with an association identification of "X", will block other messages from association "X" from being delivered.

level 2 - Allows complete interleaving of messages. This level requires that the sender carefully observe not only the peer Association but also must pay careful attention to the stream number. With this option enabled a partially delivered message may begin being delivered for association "X" stream "Y" and the next subsequent receive may return a message from association "X" stream "Z". Note that no other messages would be delivered for association "X" stream "Y" until all of stream "Y"'s partially delivered message was read. Note that this option effects both channel types. Also note that for an SctpMultiChannel not only may another streams message from the same association be delivered from the next receive, some other associations message may be delivered upon the next receive.

It is implementation specific whether or not this option is supported.

TODO: DEFAULTS/WARNINGS


SCTP_INIT_MAXSTREAMS

public static final SctpSocketOption<SctpStandardSocketOption.InitMaxStreams> SCTP_INIT_MAXSTREAMS
The maximum number of streams requested by the local endpoint during association initialization.

The value of this socket option is an InitMaxStreams, that represents the maximum number of inbound and outbound streams that an ossociation on the socket is prepared to support.

For an SctpChannel this option may only be used to change the number of inbound/outbound streams prior to connecting the socket.

For an SctpMultiChannel this option determines the maximum number of inbound/outbound streams new associations setup on the channel will be prepared to support.

For an SctpServerChannel this option determines the maximum number of inbound/outbound streams accepted sockets will negotiate with their connecting peer.

In all cases the value set by this option is used in the negotiation of new associations setup on the channel's socket and the actual maximum number of inbound/outbound streams that have been negotiated with the peer can be retrieved from the appropriate Association. The Association can be retrieved from the COMM_UP AssociationChangeNotification belonging to that association.

This value is bounded by the actual implementation. In other words the user may be able to support more streams than the Operating System. In such a case, the Operating System limit may override the value requested by the user. The default value of 0 indicates to use the endpoints default value.


SCTP_NODELAY

public static final SctpSocketOption<Boolean> SCTP_NODELAY
Enables or disables a Nagle-like algorithm.

The value of this socket option is a Boolean that represents whether the option is enabled or disabled. SCTP uses an algorithm like The Nagle Algorithm to coalesce short segments and improve network efficiency.


SCTP_PRIMARY_ADDR

public static final SctpSocketOption<SocketAddress> SCTP_PRIMARY_ADDR
Requests that the local SCTP stack use the given peer address as the association primary.

The value of this socket option is a SocketAddress that represents the peer address that the local SCTP stack should use as the association primary. The address must be one of the association peer's addresses.

An SctpMultiChannel can control more than one association, the association parameter must be given when setting or retrieving this option.

Since SctpChannel only controls one association, the association parameter is not required and this option can be set or queried directly.


SCTP_SET_PEER_PRIMARY_ADDR

public static final SctpSocketOption<SocketAddress> SCTP_SET_PEER_PRIMARY_ADDR
Requests that the peer mark the enclosed address as the association primary.

The value of this socket option is a SocketAddress that represents the local address that the peer should use as its primary address. The given address must be one of the association's locally bound addresses.

An SctpMultiChannel can control more than one association, the association parameter must be given when setting or retrieving this option.

Since SctpChannel only controls one association, the association parameter is not required and this option can be queried directly.

Note, this is a set only option and cannot be retrieved by getOption. It is implementation specific whether or not this option is supported.


SO_SNDBUF

public static final SctpSocketOption<Integer> SO_SNDBUF
The size of the socket send buffer.

The value of this socket option is an Integer that is the size of the socket send buffer in bytes. The socket send buffer is an output buffer used by the networking implementation. It may need to be increased for high-volume connections. The value of the socket option is a hint to the implementation to size the buffer and the actual size may differ. The socket option can be queried to retrieve the actual size.

For SctpChannel, this controls the amount of data the SCTP stack may have waiting in internal buffers to be sent. This option therefore bounds the maximum size of data that can be sent in a single send call.

For SctpMultiChannel, the effect is the same as for SctpChannel, except that it applies to all associations. The option applies to each association's window size separately.

An implementation allows this socket option to be set before the socket is bound or connected. Whether an implementation allows the socket send buffer to be changed after the socket is bound is system dependent.


SO_RCVBUF

public static final SctpSocketOption<Integer> SO_RCVBUF
The size of the socket receive buffer.

The value of this socket option is an Integer that is the size of the socket receive buffer in bytes. The socket receive buffer is an input buffer used by the networking implementation. It may need to be increased for high-volume connections or decreased to limit the possible backlog of incoming data. The value of the socket option is a hint to the implementation to size the buffer and the actual size may differ.

For SctpChannel, this controls the receiver window size.

For SctpMultiChannel, the meaning is implementation dependent. It might control the receive buffer for each association bound to the socket descriptor or it might control the receive buffer for the whole socket.

An implementation allows this socket option to be set before the socket is bound or connected. Whether an implementation allows the socket receive buffer to be changed after the socket is bound is system dependent.


SO_LINGER

public static final SctpSocketOption<Integer> SO_LINGER
Linger on close if data is present.

The value of this socket option is an Integer that controls the action taken when unsent data is queued on the socket and a method to close the socket is invoked. If the value of the socket option is zero or greater, then it represents a timeout value, in seconds, known as the linger interval. The linger interval is the timeout for the close method to block while the operating system attempts to transmit the unsent data or it decides that it is unable to transmit the data. If the value of the socket option is less than zero then the option is disabled. In that case the close method does not wait until unsent data is transmitted; if possible the operating system will transmit any unsent data before the connection is closed.

This socket option is intended for use with sockets that are configured in blocking mode only. The behavior of the close method when this option is enabled on a non-blocking socket is not defined.

The initial value of this socket option is a negative value, meaning that the option is disabled. The option may be enabled, or the linger interval changed, at any time. The maximum value of the linger interval is system dependent. Setting the linger interval to a value that is greater than its maximum value causes the linger interval to be set to its maximum value.


JavaTM SCTP API
DRAFT ea-b10