com.sun.sgs.impl.nio
Class DelegatingCompletionHandler<OR,OA,IR,IA>

java.lang.Object
  java.util.concurrent.FutureTask<R>
      com.sun.sgs.impl.nio.IoFutureTask<OR,OA>
          com.sun.sgs.impl.nio.DelegatingCompletionHandler<OR,OA,IR,IA>

Type Parameters:

OR - the result type for the outer handler

OA - the attachment type for the outer handler

IR - the result type for this handler

IA - the attachment type for this handler

All Implemented Interfaces:

CompletionHandler<IR,IA>, IoFuture<OR,OA>, Runnable, Future<OR>, RunnableFuture<OR>

public abstract class DelegatingCompletionHandler<OR,OA,IR,IA>
extends IoFutureTask<OR,OA>
implements CompletionHandler<IR,IA>

An abstract base class for defining a CompletionHandler to use when implementing methods that return an IoFuture, have a CompletionHandler parameter, and are implemented by making calls to similar methods. This class is intended to support the interaction between the internal (involving to the delegating function) and external (involving the caller) futures and completion handlers, allowing subclasses supply the desired behavior by customizing the three protected methods: implStart(), implCompleted(com.sun.sgs.nio.channels.IoFuture), and done().

For example, suppose you wanted to implement a method like AsynchronousByteChannel.read that delegated to an existing channel, but printed a message before and after reading. A simple implementation might look like:

 public class PrintReader<A>
     extends DelegatingCompletionHandler<Integer, A, Integer, A>
 {
     private final AsynchronousByteChannel channel;
     private final ByteBuffer dst;
 
     public static <A> IoFuture<Integer, A> read(
         AsynchronousByteChannel channel, ByteBuffer dst,
         A attachment, CompletionHandler<Integer, A> handler)
     {
         return new PrintReader<A>(channel, dst, 
                                         attachment, handler).start();
     }
 
     private PrintReader(AsynchronousByteChannel channel, ByteBuffer dst,
                  A attachment, CompletionHandler<Integer, A> handler)
     {
         super(attachment, handler);
         this.channel = channel;
         this.dst = dst;
     }
 
     protected IoFuture<Integer, A> implStart() {
         System.err.println("Begin reading");
         return channel.read(dst, null);
     }
 
     protected IoFuture<Integer, A> implCompleted(
                                  IoFuture<Integer, A> result) {
         System.err.println("Done reading");
         return null;
     }
 }
 

Constructor Summary

DelegatingCompletionHandler(OA outerAttachment, CompletionHandler<OR,OA> outerHandler)
Creates an instance for the specified attachment and handler.

Method Summary

boolean	cancel(boolean mayInterruptIfRunning) Attempts to cancel execution of the operation.
void	completed(IoFuture<IR,IA> innerResult) Invoked when an inner computation has completed.
protected void	done() Called when the computation is completed, which occurs when implCompleted(com.sun.sgs.nio.channels.IoFuture) returns null or throws an exception, or when the outer future is cancelled.
protected abstract IoFuture<IR,IA>	implCompleted(IoFuture<IR,IA> innerResult) Called when the delegated computation completes.
protected abstract IoFuture<IR,IA>	implStart() Starts the computation, returning a future for managing the inner computation or null to indicate that the computation is completed.
void	run() This method should not be called.
IoFuture<OR,OA>	start() Starts the computation and returns a future representing the result of the computation.

Methods inherited from class com.sun.sgs.impl.nio.IoFutureTask

attach, attachment, getNow, newInstance

Methods inherited from class java.util.concurrent.FutureTask

get, get, isCancelled, isDone, runAndReset, set, setException

Methods inherited from class java.lang.Object

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

Methods inherited from interface java.util.concurrent.Future

get, get, isCancelled, isDone

Constructor Detail

DelegatingCompletionHandler

public DelegatingCompletionHandler(OA outerAttachment,
                                   CompletionHandler<OR,OA> outerHandler)

Creates an instance for the specified attachment and handler.

Parameters:

outerAttachment - the attachment for the outer future; may be null

outerHandler - the handler to notify or null

Method Detail

completed

public final void completed(IoFuture<IR,IA> innerResult)

Invoked when an inner computation has completed. This method calls implCompleted(com.sun.sgs.nio.channels.IoFuture), and calls FutureTask.setException(java.lang.Throwable) on the future if that method throws an exception.

Specified by:

completed in interface CompletionHandler<IR,IA>

Parameters:

innerResult - the result of the inner computation

run

public final void run()

This method should not be called.

Specified by:

run in interface Runnable

Specified by:

run in interface RunnableFuture<OR>

Overrides:

run in class FutureTask<OR>

See Also:

start()

cancel

public final 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.

This implementation cancels the current future, if any.

Specified by:

cancel in interface IoFuture<OR,OA>

Specified by:

cancel in interface Future<OR>

Overrides:

cancel in class FutureTask<OR>

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

start

public final IoFuture<OR,OA> start()

Starts the computation and returns a future representing the result of the computation.

Returns:

a future representing the result of the computation

implStart

protected abstract IoFuture<IR,IA> implStart()

Starts the computation, returning a future for managing the inner computation or null to indicate that the computation is completed. Any exception thrown will terminate the computation.

Returns:

the future or null

implCompleted

protected abstract IoFuture<IR,IA> implCompleted(IoFuture<IR,IA> innerResult)
                                          throws Exception

Called when the delegated computation completes. The implementation should return a new future if there is more computation to perform, or else null to indicate that the operation has completed. Any exception thrown will terminate the computation. If an ExecutionException is thrown, then its cause will be used.

Parameters:

innerResult - the result of the delegated computation

Returns:

a future for managing continued compuation, or null to specify that the computation is done

Throws:

Exception - if the computation failed

done

protected void done()

Called when the computation is completed, which occurs when implCompleted(com.sun.sgs.nio.channels.IoFuture) returns null or throws an exception, or when the outer future is cancelled.

This implementation runs the outer completion handler. Subclasses that override this method should make sure to call this method by calling super.done().

Overrides:

done in class FutureTask<OR>