com.sun.sgs.nio.channels
Class AsynchronousSocketChannel

java.lang.Object
  com.sun.sgs.nio.channels.AsynchronousChannel
      com.sun.sgs.nio.channels.AsynchronousSocketChannel

All Implemented Interfaces:

AsynchronousByteChannel, NetworkChannel, Closeable, Channel

public abstract class AsynchronousSocketChannel
extends AsynchronousChannel
implements AsynchronousByteChannel, NetworkChannel

An asynchronous channel for stream-oriented connecting sockets.

Asynchronous socket channels are created in one of two ways. A newly-created AsynchronousSocketChannel is created by invoking one of the open methods defined by this class. A newly-created channel is open but not yet connected. A connected AsynchronousSocketChannel is created when a connection is made to the socket of an AsynchronousServerSocketChannel. It is not possible to create an asynchronous socket channel for an arbitrary, pre-existing socket.

A newly-created channel is connected by invoking its 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 getConnectedAddress method. Whether or not a connect operation is in progress may be determined by invoking the isConnectionPending method. An attempt to invoke an I/O operation upon an unconnected channel will cause a 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 ReadPendingException will be thrown. Similarly, an attempt to initiate a write operation before a previous write has completed will throw a WritePendingException. Whether or not a read or write operation is pending may be determined by invoking the isReadPending and isWritePending methods.

Socket options are configured using the setOption method. Asynchronous socket channels support the following options:

Option Name	Description
SO_SNDBUF	The size of the socket send buffer
SO_RCVBUF	The size of the socket receive buffer
SO_KEEPALIVE	Keep connection alive
SO_REUSEADDR	Re-use address
TCP_NODELAY	Disable the Nagle algorithm

and may support additional (implementation specific) options. The list of options supported is obtained by invoking the options method.

Timeouts

The read and 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 by throwing ExecutionException with cause AbortedByTimeoutException. A timeout may leave the channel, or the underlying connection, in an inconsistent state. Where an implementation cannot guarantee that no bytes have been read from the channel then it puts the channel into an implementation specific error state and a subsequent attempt to initiate a read operation throws an unspecified runtime exception. Similarly if a write operation times and the implementation cannot guarantee that no bytes have been written to the channel then it prohibits further write operations by throwing an unspecified runtime exception.

When a timeout elapses then the state of the 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.

Method Summary

abstract AsynchronousSocketChannel	bind(SocketAddress local) Binds the channel's socket to a local address.
abstract <A> IoFuture<Void,A>	connect(SocketAddress remote, A attachment, CompletionHandler<Void,? super A> handler) Connects this channel.
<A> IoFuture<Void,A>	connect(SocketAddress remote, CompletionHandler<Void,? super A> handler) Connects this channel.
abstract SocketAddress	getConnectedAddress() Returns the remote address to which this channel's socket is connected, or null if the channel's socket is not connected.
abstract boolean	isConnectionPending() Tells whether or not a connect is pending for this channel.
abstract boolean	isReadPending() Tells whether or not a read is pending for this channel.
abstract boolean	isWritePending() Tells whether or not a write is pending for this channel.
static AsynchronousSocketChannel	open() Opens an asynchronous socket channel.
static AsynchronousSocketChannel	open(AsynchronousChannelGroup group) Opens an asynchronous socket channel.
abstract <A> IoFuture<Long,A>	read(ByteBuffer[] dsts, int offset, int length, long timeout, TimeUnit unit, A attachment, CompletionHandler<Long,? super A> handler) Reads a sequence of bytes from this channel into a subsequence of the given buffers.
<A> IoFuture<Integer,A>	read(ByteBuffer dst, A attachment, CompletionHandler<Integer,? super A> handler) Reads a sequence of bytes from this channel into the given buffer.
<A> IoFuture<Integer,A>	read(ByteBuffer dst, CompletionHandler<Integer,? super A> handler) Reads a sequence of bytes from this channel into the given buffer.
abstract <A> IoFuture<Integer,A>	read(ByteBuffer dst, long timeout, TimeUnit unit, A attachment, CompletionHandler<Integer,? super A> handler) Reads a sequence of bytes from this channel into the given buffer.
abstract AsynchronousSocketChannel	setOption(SocketOption name, Object value) Sets the value of a socket option.
abstract AsynchronousSocketChannel	shutdown(ShutdownType how) Shutdown a connection for reading and/or writing without closing the channel.
abstract <A> IoFuture<Long,A>	write(ByteBuffer[] srcs, int offset, int length, long timeout, TimeUnit unit, A attachment, CompletionHandler<Long,? super A> handler) Writes a sequence of bytes to this channel from a subsequence of the given buffers.
<A> IoFuture<Integer,A>	write(ByteBuffer src, A attachment, CompletionHandler<Integer,? super A> handler) Writes a sequence of bytes to this channel from the given buffer.
<A> IoFuture<Integer,A>	write(ByteBuffer src, CompletionHandler<Integer,? super A> handler) Writes a sequence of bytes to this channel from the given buffer.
abstract <A> IoFuture<Integer,A>	write(ByteBuffer src, long timeout, TimeUnit unit, A attachment, CompletionHandler<Integer,? super A> handler) Writes a sequence of bytes to this channel from the given buffer.

Methods inherited from class com.sun.sgs.nio.channels.AsynchronousChannel

close, provider

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface com.sun.sgs.nio.channels.NetworkChannel

getLocalAddress, getOption, options

Methods inherited from interface java.nio.channels.Channel

close, isOpen

Method Detail

open

public static AsynchronousSocketChannel open(AsynchronousChannelGroup group)
                                      throws IOException

Opens an asynchronous socket channel.

The new channel is created by invoking the openAsynchronousSocketChannel method on the AsynchronousChannelProvider object that created the given group. If the group parameter is null then the resulting channel is created by the system-wide default provider, and bound to the default group.

Parameters:

group - the group to which the newly constructed channel should be bound, or null for the default group

Returns:

a new asynchronous socket channel

Throws:

ShutdownChannelGroupException - if the specified group is shutdown

IOException - if an I/O error occurs

open

public static AsynchronousSocketChannel open()
                                      throws IOException

Opens an asynchronous socket channel.

This method returns an asynchronous socket channel that is bound to the default group.This method is equivalent to evaluating the expression:

       open((AsynchronousChannelGroup)null);
 

Returns:

a new asynchronous socket channel

Throws:

IOException - if an I/O error occurs

bind

public abstract AsynchronousSocketChannel bind(SocketAddress local)
                                        throws IOException

Binds the channel's socket to a local address.

This method is used to establish an association between the socket and a local address. Once an association is established then the socket remains bound until the channel is closed. An attempt to bind a socket that is already bound throws AlreadyBoundException. If the local parameter has the value null then the socket will be bound to an address that is assigned automatically.

An implementation of this interface should specify if a permission is required when a security manager is installed.

Specified by:

bind in interface NetworkChannel

Parameters:

local - the address to bind the socket, or null to bind the socket to an automatically assigned socket address

Returns:

this channel

Throws:

ClosedChannelException - if the channel is closed

IOException - if some other I/O error occurs

setOption

public abstract AsynchronousSocketChannel setOption(SocketOption name,
                                                    Object value)
                                             throws IOException

Sets the value of a socket option.

The name parameter is the name of the socket option. The value parameter is the value of the option and is of the type specified by the option. A value of null may be a valid value for some socket options.

Specified by:

setOption in interface NetworkChannel

Parameters:

name - the name of the socket option

value - the value of the socket option

Returns:

this channel

Throws:

ClosedChannelException - if this channel is closed

IOException - if an I/O error occurs

See Also:

SocketOption

shutdown

public abstract AsynchronousSocketChannel shutdown(ShutdownType how)
                                            throws IOException

Shutdown a connection for reading and/or writing without closing the channel.

The how parameter specifies if the input, output, or both sides of the connection is shutdown. If the input side of the connection is shutdown then further read operations on the channel will return -1, the end-of-stream indication. If the input side of the connection is already shutdown then invoking this method to shutdown the input side of the connection has no effect. If the output side of the connection is shutdown then further write operations on the channel will complete immediately by throwning ExecutionException with cause ClosedChannelException. If the output side of the connection is already shutdown then invoking this method to shutdown the output side of the connection has no effect.

Parameters:

how - specifies if the input, output, or both sides of the connection is shutdown

Returns:

this channel

Throws:

NotYetConnectedException - if this channel is not yet connected

ClosedChannelException - if this channel is closed

IOException - if some other I/O error occurs

getConnectedAddress

public abstract SocketAddress getConnectedAddress()
                                           throws IOException

Returns the remote address to which this channel's socket is connected, or null if the channel's socket is not connected.

Returns:

the remote address; null if the channel is not open or the channel's socket is not connected

Throws:

IOException - if an I/O error occurs

isConnectionPending

public abstract boolean isConnectionPending()

Tells whether or not a connect is pending for this channel.

The result of this method is a snapshot of the channel state. It may be invalid when the caller goes to examine the result and should not be used for purposes of coordination.

Returns:

true if, and only if, a connect is pending for this channel but has not yet completed

isReadPending

public abstract boolean isReadPending()

Tells whether or not a read is pending for this channel.

The result of this method is a snapshot of the channel state. It may be invalid when the caller goes to examine the result and should not be used for purposes of coordination.

Returns:

true if, and only if, a read is pending for this this channel but has not yet completed

See Also:

ReadPendingException

isWritePending

public abstract boolean isWritePending()

Tells whether or not a write is pending for this channel.

The result of this method is a snapshot of the channel state. It may be invalid when the caller goes to examine the result and should not be used for purposes of coordination.

Returns:

true if, and only if, a write is pending for this this channel but has not yet completed

See Also:

WritePendingException

connect

public abstract <A> IoFuture<Void,A> connect(SocketAddress remote,
                                             A attachment,
                                             CompletionHandler<Void,? super A> handler)

Connects this channel.

This method initiates an operation to connect this channel, returning a IoFuture representing the pending result of the operation. If the connection is successfully established then the IoFuture's get method will return null, otherwise it throws ExecutionException with the approach cause.

This method performs exactly the same security checks as the Socket class. That is, if a security manager has been installed then this method verifies that its checkConnect method permits connecting to the address and port number of the given remote endpoint.

Type Parameters:

A - the attachment type

Parameters:

remote - the remote address to which this channel is to be connected

attachment - the object to attach to the returned IoFuture object; can be null

handler - the handler for consuming the result; can be null

Returns:

an IoFuture object representing the pending result

Throws:

ClosedAsynchronousChannelException - if this channel is closed

AlreadyConnectedException - if this channel is already connected

ConnectionPendingException - if a connection operation is already in progress on this channel

UnresolvedAddressException - if the given remote address is not fully resolved

UnsupportedAddressTypeException - if the type of the given remote address is not supported

SecurityException - if a security manager has been installed and it does not permit access to the given remote endpoint

See Also:

getConnectedAddress(), isConnectionPending()

connect

public final <A> IoFuture<Void,A> connect(SocketAddress remote,
                                          CompletionHandler<Void,? super A> handler)

Connects this channel.

This method initiates an operation to connect this channel, returning a IoFuture representing the pending result of the operation. If the connection is successfully established then the IoFuture's get method will return null.

This method is equivalent to invoking connect(SocketAddress,A,CompletionHandler) with the attachment parameter set to null.

Type Parameters:

A - the attachment type

Parameters:

remote - the remote address to which this channel is to be connected

handler - the handler for consuming the result; can be null

Returns:

an IoFuture object representing the pending result

Throws:

ClosedAsynchronousChannelException - if this channel is closed

AlreadyConnectedException - if this channel is already connected

ConnectionPendingException - if a connection operation is already in progress on this channel

UnresolvedAddressException - if the given remote address is not fully resolved

UnsupportedAddressTypeException - if the type of the given remote address is not supported

SecurityException - if a security manager has been installed and it does not permit access to the given remote endpoint

See Also:

getConnectedAddress(), isConnectionPending()

read

public abstract <A> IoFuture<Integer,A> read(ByteBuffer dst,
                                             long timeout,
                                             TimeUnit unit,
                                             A attachment,
                                             CompletionHandler<Integer,? super A> handler)

Reads a sequence of bytes from this channel into the given buffer.

This method initiates the reading of a sequence of bytes from this channel into the given buffer, returning an IoFuture representing the pending result of the operation. The IoFuture's get method returns the number of bytes read, possibly zero, or -1 if all bytes have been read and channel has reached end-of-stream.

If a timeout is specified and the timeout elapses before the operation completes then it completes with ExecutionException and cause AbortedByTimeoutException. In that case it is guranteed that no bytes have been read from the channel into the given buffer.

Otherwise this method works in the same manner as the AsynchronousByteChannel.read(ByteBuffer,A,CompletionHandler) method.

Type Parameters:

A - the attachment type

Parameters:

dst - the buffer into which bytes are to be transferred

timeout - the timeout, or 0L for no timeout

unit - the time unit of the timeout argument

attachment - the object to attach to the returned IoFuture object; can be null

handler - the handler for consuming the result; can be null

Returns:

an IoFuture object representing the pending result

Throws:

IllegalArgumentException - if the timeout parameter is negative

ClosedAsynchronousChannelException - if this channel is closed

ReadPendingException - if a read operation is already in progress on this channel

NotYetConnectedException - if this channel is not yet connected

IllegalChannelStateException - if a previous read operation on the channel completed due to a timeout

read

public final <A> IoFuture<Integer,A> read(ByteBuffer dst,
                                          A attachment,
                                          CompletionHandler<Integer,? super A> handler)

Reads a sequence of bytes from this channel into the given buffer.

This method initiates the reading of a sequence of bytes from this channel into the given buffer, returning an IoFuture representing the pending result of the operation. The IoFuture's get method will return the number of bytes read, possibly zero, or -1 if all bytes have been read and channel has reached end-of-stream.

This method is equivalent to invoking read(ByteBuffer,long,TimeUnit,A,CompletionHandler) with a timeout of 0L.

Specified by:

read in interface AsynchronousByteChannel

Type Parameters:

A - the attachment type

Parameters:

dst - the buffer into which bytes are to be transferred

attachment - the object to attach to the returned IoFuture object; can be null

handler - the handler for consuming the result; can be null

Returns:

an IoFuture object representing the pending result

Throws:

ClosedAsynchronousChannelException - if this channel is closed

ReadPendingException - if a read operation is already in progress on this channel

NotYetConnectedException - if this channel is not yet connected

IllegalChannelStateException - if a previous read operation on the channel completed due to a timeout

read

public final <A> IoFuture<Integer,A> read(ByteBuffer dst,
                                          CompletionHandler<Integer,? super A> handler)

Reads a sequence of bytes from this channel into the given buffer.

This method initiates the reading of a sequence of bytes from this channel into the given buffer, returning an IoFuture representing the pending result of the operation. The IoFuture's get method will return the number of bytes read, possibly zero, or -1 if all bytes have been read and channel has reached end-of-stream.

This method is equivalent to invoking read(ByteBuffer,long,TimeUnit,A,CompletionHandler) with a timeout of 0L, and an attachment of null.

Specified by:

read in interface AsynchronousByteChannel

Type Parameters:

A - the attachment type

Parameters:

dst - the buffer into which bytes are to be transferred

handler - the handler for consuming the result; can be null

Returns:

an IoFuture object representing the pending result

Throws:

ClosedAsynchronousChannelException - if this channel is closed

ReadPendingException - if a read operation is already in progress on this channel

NotYetConnectedException - if this channel is not yet connected

IllegalChannelStateException - if a previous read operation on the channel completed due to a timeout

read

public abstract <A> IoFuture<Long,A> read(ByteBuffer[] dsts,
                                          int offset,
                                          int length,
                                          long timeout,
                                          TimeUnit unit,
                                          A attachment,
                                          CompletionHandler<Long,? super A> handler)

Reads a sequence of bytes from this channel into a subsequence of the given buffers.

This method initiates the reading of a sequence of bytes from this channel into a subsequence of the given buffers, returning an IoFuture representing the pending result of the operation. The IoFuture's get method returns the number of bytes read, possibly zero, or -1 if all bytes have been read and channel has reached end-of-stream.

This method initiates a read of up to r bytes from this channel, where r is the total number of bytes remaining in the specified subsequence of the given buffer array, that is,

      dsts[offset].remaining()
          + dsts[offset+1].remaining()
          + ... + dsts[offset+length-1].remaining()
 

at the moment that the read is attempted.

Suppose that a byte sequence of length n is read, where 0 <= n <= r. Up to the first dsts[offset].remaining() bytes of this sequence are transferred into buffer dsts[offset], up to the next dsts[offset+1].remaining() bytes are transferred into buffer dsts[offset+1], and so forth, until the entire byte sequence is transferred into the given buffers. As many bytes as possible are transferred into each buffer, hence the final position of each updated buffer, except the last updated buffer, is guaranteed to be equal to that buffer's limit.

If a timeout is specified and the timeout elapses before the operation completes then it completes with ExecutionException and cause AbortedByTimeoutException. In that case it is guranteed that no bytes have been read from the channel into the given buffers.

Type Parameters:

A - the attachment type

Parameters:

dsts - the buffers into which bytes are to be transferred

offset - the offset within the buffer array of the first buffer into which bytes are to be transferred; must be non-negative and no larger than dsts.length

length - the maximum number of buffers to be accessed; must be non-negative and no larger than dsts.length - offset

timeout - the timeout, or 0L for no timeout

unit - the time unit of the timeout argument

attachment - the object to attach to the returned IoFuture object; can be null

handler - the handler for consuming the result; can be null

Returns:

an IoFuture object representing the pending result

Throws:

IllegalArgumentException - if the timeout parameter is negative, or the pre-conditions for the offset and length parameter aren't met

ClosedAsynchronousChannelException - if this channel is closed

ReadPendingException - if a read operation is already in progress on this channel

NotYetConnectedException - if this channel is not yet connected

IllegalChannelStateException - if a previous read operation on the channel completed due to a timeout

write

public abstract <A> IoFuture<Integer,A> write(ByteBuffer src,
                                              long timeout,
                                              TimeUnit unit,
                                              A attachment,
                                              CompletionHandler<Integer,? super A> handler)

Writes a sequence of bytes to this channel from the given buffer.

This method initiates the writing of a sequence of bytes to this channel from the given buffer, returning an IoFuture representing the pending result of the operation. The IoFuture's get method will return the number of bytes written, possibly zero.

If a timeout is specified and the timeout elapses before the operation completes then it completes with ExecutionException and cause AbortedByTimeoutException. In that case it is guranteed that no bytes have written to the channel from the given buffer.

Otherwise this method works in the same manner as the AsynchronousByteChannel.write(ByteBuffer,A,CompletionHandler) method.

Type Parameters:

A - the attachment type

Parameters:

src - the buffer from which bytes are to be retrieved

timeout - the timeout, or 0L for no timeout

unit - the time unit of the timeout argument

attachment - the object to attach to the returned IoFuture object; can be null

handler - the handler for consuming the result; can be null

Returns:

an IoFuture object representing the pending result

Throws:

IllegalArgumentException - if the timeout parameter is negative

ClosedAsynchronousChannelException - if this channel is closed

WritePendingException - if a write operation is already in progress on this channel

NotYetConnectedException - if this channel is not yet connected

IllegalChannelStateException - if a previous write operation on the channel completed due to a timeout

write

public final <A> IoFuture<Integer,A> write(ByteBuffer src,
                                           A attachment,
                                           CompletionHandler<Integer,? super A> handler)

Writes a sequence of bytes to this channel from the given buffer.

This method initiates the writing of a sequence of bytes to this channel rom the given buffer, returning an IoFuture representing the pending result of the operation.

This method is equivalent to invoking write(ByteBuffer,long,TimeUnit,A,CompletionHandler) with a timeout of 0L.

Specified by:

write in interface AsynchronousByteChannel

Type Parameters:

A - the attachment type

Parameters:

src - the buffer from which bytes are to be retrieved

attachment - the object to attach to the returned IoFuture object; can be null

handler - the handler for consuming the result; can be null

Returns:

an IoFuture object representing the pending result

Throws:

ClosedAsynchronousChannelException - if this channel is closed

WritePendingException - if a write operation is already in progress on this channel

NotYetConnectedException - if this channel is not yet connected

IllegalChannelStateException - if a previous write operation on the channel completed due to a timeout

write

public final <A> IoFuture<Integer,A> write(ByteBuffer src,
                                           CompletionHandler<Integer,? super A> handler)

Writes a sequence of bytes to this channel from the given buffer.

This method initiates the writing of a sequence of bytes to this channel from the given buffer, returning an IoFuture representing the pending result of the operation.

This method is equivalent to invoking write(ByteBuffer,long,TimeUnit,A,CompletionHandler) with a timeout of 0L, and an attachment of null.

Specified by:

write in interface AsynchronousByteChannel

Type Parameters:

A - the attachment type

Parameters:

src - the buffer from which bytes are to be retrieved

handler - the handler for consuming the result; can be null

Returns:

an IoFuture object representing the pending result

Throws:

ClosedAsynchronousChannelException - if this channel is closed

WritePendingException - if a write operation is already in progress on this channel

NotYetConnectedException - if this channel is not yet connected

IllegalChannelStateException - if a previous write operation on the channel completed due to a timeout

write

public abstract <A> IoFuture<Long,A> write(ByteBuffer[] srcs,
                                           int offset,
                                           int length,
                                           long timeout,
                                           TimeUnit unit,
                                           A attachment,
                                           CompletionHandler<Long,? super A> handler)

Writes a sequence of bytes to this channel from a subsequence of the given buffers.

This method initiates the writing of a sequence of bytes to this channel from a subsequence of the given buffers, returning an IoFuture representing the pending result of the operation. The IoFuture's get method will return the number of bytes written, possibly zero.

This method initiates a write of up to r bytes to this channel, where r is the total number of bytes remaining in the specified subsequence of the given buffer array, that is,

      srcs[offset].remaining()
          + srcs[offset+1].remaining()
          + ... + srcs[offset+length-1].remaining()
 

at the moment that the write is attempted.

Suppose that a byte sequence of length n is written, where 0 <= n <= r. Up to the first srcs[offset].remaining() bytes of this sequence are written from buffer srcs[offset], up to the next srcs[offset+1].remaining() bytes are written from buffer srcs[offset+1], and so forth, until the entire byte sequence is written. As many bytes as possible are written from each buffer, hence the final position of each updated buffer, except the last updated buffer, is guaranteed to be equal to that buffer's limit.

If a timeout is specified and the timeout elapses before the operation completes then it completes with ExecutionException and cause AbortedByTimeoutException. In that case it is guranteed that no bytes have written to the channel from the given buffers.

Type Parameters:

A - the attachment type

Parameters:

srcs - the buffers from which bytes are to be retrieved

offset - the offset within the buffer array of the first buffer from which bytes are to be retrieved; must be non-negative and no larger than srcs.length.

length - the maximum number of buffers to be accessed; must be non-negative and no larger than srcs.length - offset

timeout - the timeout, or 0L for no timeout

unit - the time unit of the timeout argument

attachment - the object to attach to the returned IoFuture object; can be null

handler - the handler for consuming the result; can be null

Returns:

an IoFuture object representing the pending result

Throws:

IllegalArgumentException - if the timeout parameter is negative or the pre-conditions for the offset or length parameter aren't met

ClosedAsynchronousChannelException - if this channel is closed

WritePendingException - if a write operation is already in progress on this channel

NotYetConnectedException - if this channel is not yet connected

IllegalChannelStateException - if a previous write operation on the channel completed due to a timeout