org.cojen.dirmi

Annotation Type Asynchronous

@Documented
 @Retention(value=RUNTIME)
 @Target(value=METHOD)
public @interface Asynchronous

Identify a method as being asynchronous, which does not imply non-blocking. It merely means that the caller does not wait for the remote method to finish. An asynchronous method will likely block if the transport layer is backed up.

An asynchronous method must declare returning void, Pipe, Completion or Future. An asynchronous task represented by a Completion or Future cannot be cancelled, at least not directly. Implementations of asynchronous future methods should return a factory generated response.

 @Asynchronous
 void sendMessage(String data) throws RemoteException;

 @Asynchronous
 @RemoteFailure(exception=FileNotFoundException.class)
 Pipe readFile(String name, Pipe pipe) throws FileNotFoundException;

 @Asynchronous
 Future<Image> generateImage(int width, int height, Object data) throws RemoteException;

 @Asynchronous(CallMode.ACKNOWLEDGED)
 void launchBuild(Object params, ProgressCallback callback) throws RemoteException;
 

Asynchronous methods can only declare throwing RemoteException or the exception indicated by RemoteFailure. A client can expect an exception to be thrown by an asynchronous method only if there is a communication failure. Any exception thrown by the server implementation of an asynchronous void or Pipe method is not passed to the client. Instead, it is passed to the thread's uncaught exception handler.

For asynchronous methods which return a Completion or Future, any server thrown exception is passed to the caller via the returned object. Upon calling get, an ExecutionException is thrown. A communication failure while sending the request is thrown directly to the caller and not through the Future.

Author:

Brian S O'Neill

See Also:

Batched, Ordered, ThrottledExecutor

Optional Element Summary

Optional Elements

Modifier and Type	Optional Element and Description
CallMode	value Control the calling mode of the asynchronous method.

Element Detail

value

public abstract CallMode value

Control the calling mode of the asynchronous method. By default, the request is immediately sent to the remote endpoint, but it does not wait for acknowledgement.

Default:

org.cojen.dirmi.CallMode.IMMEDIATE