com.sun.sgs.nio.channels
Interface IoFuture<R,A>

Type Parameters:

R - the result type

A - the attachment type

All Superinterfaces:

Future<R>

All Known Implementing Classes:

AttachedFuture, DelegatingCompletionHandler, IoFutureTask

public interface IoFuture<R,A>
extends Future<R>

A Future representing the result of an asynchronous I/O operation.

In addition to the methods defined by the Future interface, an IoFuture allows for the attachment of a single arbitrary object. Where the same CompletionHandler instance is used to consume the result of several operations then the attachment object can be used to associate application-specific data or context that is required when consuming the result. The attachment object, if any, is specified when initiating the operation. The attachment method is used to retrieve it. The attachment may later be discarded by attaching null.

Method Summary

A	attach(A ob) Attaches the given object to this channel future.
A	attachment() Retrieves the current attachment.
boolean	cancel(boolean mayInterruptIfRunning) Attempts to cancel execution of the operation.
R	getNow() Retrieves the result of a completed operation.

Methods inherited from interface java.util.concurrent.Future

get, get, isCancelled, isDone

Method Detail

getNow

R getNow()
         throws ExecutionException

Retrieves the result of a completed operation.

The method is intended to be invoked from a CompletionHandler to retrieve the result of a completed operation. It is equivalent to invoking the get method to retrieve the result except that the method does not wait for the result.

Returns:

the completed result

Throws:

ExecutionException - if the operation threw an exception

CancellationException - if the operation was cancelled

IllegalStateException - if the operation has not completed

cancel

boolean cancel(boolean mayInterruptIfRunning)

Attempts to cancel execution of the operation.

If the value of mayInterruptIfRunning is true then this method may cancel the operation forcefully by closing the channel. Whether it does close the channel is implementation and operation specific. If the channel is closed then all outstanding operations on the channel complete by throwing ExecutionException with cause AsynchronousCloseException. Where an implementation does not close the channel then the channel may be put into an error state that prevents further operations on the channel. For example, if a read operation is cancelled and the implementation cannot guarantee that no bytes have been read from the channel then it puts the channel into an implementation specific error state. Any subsequent attempt to initiate a read operation on the channel throws an unspecified runtime exception.

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

Specified by:

cancel in interface Future<R>

Parameters:

mayInterruptIfRunning - true if the operation can be cancelled forcefully (possibily by closing the channel), false otherwise

Returns:

false if the operation could not be cancelled, true if the operation has been cancelled

attachment

A attachment()

Retrieves the current attachment.

Returns:

the object currently attached to this channel future or null if there is no attachment

attach

A attach(A ob)

Attaches the given object to this channel future.

An attached object may later be retrieved via the attachment method. Only one object may be attached at a time; invoking this method causes any previous attachment to be discarded. The current attachment may be discarded by attaching null.

Parameters:

ob - the object to be attached; may be null

Returns:

the previously-attached object, if any, otherwise null