com.sun.sgs.nio.channels
Class AsynchronousChannel

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

All Implemented Interfaces:

Closeable, Channel

Direct Known Subclasses:

AsynchronousDatagramChannel, AsynchronousServerSocketChannel, AsynchronousSocketChannel

public abstract class AsynchronousChannel
extends Object
implements Channel

A channel that supports asynchronous operations.

Asynchronous channels are non-blocking and define methods to initiate asynchronous operations of the form:

  IoFuture<R,A> operation(... CompletionHandler<R,A> handler)
 

The returned IoFuture represents the pending result of the asynchronous operation on the channel, and R is the result type returned by the IoFuture's get method.

The IoFuture's isDone method can be used to poll the operation to test if it has completed. The IoFuture's get() method can be used wait indefinitely for the result of the operation, and the get(long,TimeUnit) method can be used to wait for at most a given time. If the operation does not complete normally then the get method throws an ExecutionException with the appropriate cause.

When an operation on an asynchronous channel completes (successfully or due to error) then a completion handler is invoked to consume the result. The handler is specified when the asynchronous operation is initiated. If a completion handler is not required then it can be specified as null.

An asynchronous channel is bound to an asynchronous channel group. The group can be specified when the channel is constructed. If a group is not specified then the channel is bound to a default group. Once a channel is created it remains bound to the group until the channel is closed. This class does not define a method to obtain the group to which the channel is bound. Each group has an associated ExecutorService to which tasks are submitted to handle I/O events and dispatch the results to completion handlers. The completion handler is guaranteed to be invoked by either the thread that initiated the operation or from a task executed by the associated executor service.

Closing, Cancellation, Timeouts, and Concurrency

Invoking the close method on an asynchronous channel arranges for all outstanding operations on the channel to complete by throwing ExecutionException with cause AsynchronousCloseException.

An asynchronous operation is cancelled by invoking the cancel method on the IoFuture representing the result of the operation. It is implementation, channel, and operation specific whether an asynchronous operation can be cancelled. If an operation can be cancelled then the completion handler is invoked and the IoFuture's get method throws CancellationException. If the cancel method is invoked with the mayInterruptIfRunning parameter set to the value true then an implementation may close the channel as if by invoking the close method. In that case then all outstanding operations on the channel complete by throwing ExecutionException with cause AsynchronousCloseException.

Some channel implementations may allow a timeout to be specified when initiating an asynchronous operation. If the timeout elapses before the operation completes then the operation completes by throwing ExecutionException with cause AbortedByTimeoutException. Depending on the channel type, a timeout may put the channel into an error state that prevents further operations on the channel.

Asynchronous channels are safe for use by multiple concurrent threads. Some channel implementations may support concurrent reading and writing, but may not allow more than one read or write to be outstanding at any given time.

Read and write operations on asynchronous channels will typically involve reading into or writing from a ByteBuffer, or a sequence of buffers. Buffers are not safe for use by multiple concurrent threads so care should be taken to not access the buffer until the operation completes.

Constructor Summary

protected

AsynchronousChannel(AsynchronousChannelProvider provider) Initializes a new instance of this class.

Method Summary

abstract void	close() Closes this channel.
AsynchronousChannelProvider	provider() Returns the provider that created this channel.

Methods inherited from class java.lang.Object

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

Methods inherited from interface java.nio.channels.Channel

isOpen

Constructor Detail

AsynchronousChannel

protected AsynchronousChannel(AsynchronousChannelProvider provider)

Initializes a new instance of this class.

Parameters:

provider - the provider that created this channel

Method Detail

provider

public final AsynchronousChannelProvider provider()

Returns the provider that created this channel.

Returns:

the provider that created this channel

close

public abstract void close()
                    throws IOException

Closes this channel.

Any outstanding asynchronous operations upon this channel will complete by throwing ExecutionException with cause AsynchronousCloseException.

This method otherwise behaves exactly as specified by the Channel interface.

Specified by:

close in interface Closeable

Specified by:

close in interface Channel

Throws:

IOException - if an I/O error occurs