An asynchronous channel for stream-oriented connecting sockets.
Asynchronous socket channels are created in one of two ways. A newly-created {@code AsynchronousSocketChannel} is created by invoking one of the {@link #open open} methods defined by this class. A newly-created channel is open butnot yet connected. A connected {@code AsynchronousSocketChannel} is createdwhen a connection is made to the socket of an {@link AsynchronousServerSocketChannel}. It is not possible to create an asynchronous socket channel for an arbitrary, pre-existing {@link java.net.Socket socket}.
A newly-created channel is connected by invoking its {@link #connect connect}method; once connected, a channel remains connected until it is closed. Whether or not a socket channel is connected may be determined by invoking its {@link #getRemoteAddress getRemoteAddress} method. An attempt to invoke an I/Ooperation upon an unconnected channel will cause a {@link NotYetConnectedException}to be thrown.
Channels of this type are safe for use by multiple concurrent threads. They support concurrent reading and writing, though at most one read operation and one write operation can be outstanding at any time. If a thread initiates a read operation before a previous read operation has completed then a {@link ReadPendingException} will be thrown. Similarly, anattempt to initiate a write operation before a previous write has completed will throw a {@link WritePendingException}.
Socket options are configured using the {@link #setOption(SocketOption,Object) setOption} method. Asynchronous socket channels support the following options:
Option Name | Description |
{@link java.net.StandardSocketOptions#SO_SNDBUF SO_SNDBUF} | The size of the socket send buffer |
{@link java.net.StandardSocketOptions#SO_RCVBUF SO_RCVBUF} | The size of the socket receive buffer |
{@link java.net.StandardSocketOptions#SO_KEEPALIVE SO_KEEPALIVE} | Keep connection alive |
{@link java.net.StandardSocketOptions#SO_REUSEADDR SO_REUSEADDR} | Re-use address |
{@link java.net.StandardSocketOptions#TCP_NODELAY TCP_NODELAY} | Disable the Nagle algorithm |
Additional (implementation specific) options may also be supported.
Timeouts
The {@link #read(ByteBuffer,long,TimeUnit,Object,CompletionHandler) read}and {@link #write(ByteBuffer,long,TimeUnit,Object,CompletionHandler) write}methods defined by this class allow a timeout to be specified when initiating a read or write operation. If the timeout elapses before an operation completes then the operation completes with the exception {@link InterruptedByTimeoutException}. A timeout may leave the channel, or the underlying connection, in an inconsistent state. Where the implementation cannot guarantee that bytes have not been read from the channel then it puts the channel into an implementation specific error state. A subsequent attempt to initiate a {@code read} operation causes an unspecified runtimeexception to be thrown. Similarly if a {@code write} operation times out andthe implementation cannot guarantee bytes have not been written to the channel then further attempts to {@code write} to the channel cause anunspecified runtime exception to be thrown. When a timeout elapses then the state of the {@link ByteBuffer}, or the sequence of buffers, for the I/O operation is not defined. Buffers should be discarded or at least care must be taken to ensure that the buffers are not accessed while the channel remains open. All methods that accept timeout parameters treat values less than or equal to zero to mean that the I/O operation does not timeout.
@since 1.7