org.cojen.dirmi

Annotation Type Batched

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

Identify a method as being batched and asynchronous, which does not imply non-blocking. Requests are sent to the remote endpoint, but the channel is not immediately flushed. The current thread holds the same channel for making additional requests until an immediate or synchronous request is sent. All requests received by the remote endpoint are executed in one thread, in the correct order. If the sender thread exits before releasing the channel, the batched requests are eventually sent.

A batched method must declare returning void, a Remote object, Completion or Future. Returning a Remote object allows batched calls to be chained together. A batched task represented by a Completion or Future cannot be cancelled, at least not directly. Implementations of batched future methods should return a factory generated response.

 @Batched
 void setOption(int option) throws RemoteException;

 @Batched
 RemoteAccess login(String user, String password) throws RemoteException, AuthFailure;
 

Batched methods can declare throwing any exception, and any exception thrown by the server aborts the batch operation. This exception is passed to the caller of the immediate or synchronous method that terminated the batch. If the terminating method does not declare throwing the exception type, it is wrapped by UndeclaredThrowableException. Any Remote objects returned from batched methods at or after the exception being thrown will be bogus. Attempts to invoke methods on these objects will also throw the original exception, possibly wrapped.

Any exception thrown by a batched method which returns a Completion or Future 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:

Asynchronous, Unbatched

Optional Element Summary

Optional Elements

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

Element Detail

value

public abstract CallMode value

Control the calling mode of the batched method. By default, the request is eventually sent to the remote endpoint.

Default:

org.cojen.dirmi.CallMode.EVENTUAL