org.cojen.dirmi

Annotation Type Timeout

@Documented
 @Retention(value=RUNTIME)
 @Target(value={METHOD,TYPE})
public @interface Timeout

Remote method timeout policy annotation, which can target a remote interface or method. When annotated at the interface level, it defines default timeout values for all methods. Any method can override the defaults with its own annotation. The timeout annotation can be used with TimeoutUnit to define the unit. If not specified, it defaults to milliseconds.

Timeouts only apply to the caller of a remote method. If the timeout has elapsed without a response from the remote endpoint, the connection is forcibly closed and a RemoteTimeoutException is thrown. When this happens, no special action is automatically applied on the remote side to interrupt any work in progress. The actual method implementation is responsible for this. If it completes its work and returns after a timeout, the response is discarded.

When a RemoteTimeoutException is thrown, it does not indicate whether the remote endpoint actually received the request or not. Care must be taken when attempting to retry a failed remote invocation, especially if not idempotent. Asynchronous methods with callbacks can provide more information regarding successful invocation, but timeouts on asynchronous methods alone offer less utility. This is because the timeout on an asynchronous method only applies to the sending of the request. It does not wait for method completion. When using the acknowledged calling mode, timeouts do at least wait for acknowledgement. Consider returning a Future and call the get method which accepts a timeout.

Method parameters may use the TimeoutParam annotation to specify timeout values and units. When applied to a primitive numeric type (which can be boxed), it specifies the timeout value. At most one parameter can be a timeout value. When the annotation is applied to a parameter of type TimeUnit, it specifies the timeout unit. Likewise, at most one parameter can be a timeout unit. If no parameter is annotated as a timeout unit but the parameter immediately following the timeout value is a TimeUnit, it is automatically chosen as the timeout unit parameter.

Remote method implementations may make use of timeout parameters to interrupt any work in progress, under the assumption that the caller has given up after the timeout has elapsed.

Timeout parameters can have runtime values of null, in which case default timeouts apply. These defaults are defined by any method and interface level timeout annotations. If none, then the default timeout value is infinite and the unit is milliseconds. In either case, the remote endpoint sees the applied values instead of null. If the timeout value cannot be cast to the parameter type without loss of magnitude, -1 (infinite) is passed instead.

 // 10 second timeout for all methods by default.
 @Timeout(10)
 // If unit was not specified, milliseconds is assumed.
 @TimeoutUnit(TimeUnit.SECONDS)
 public interface MyRemote extends Remote {
     // Default 10 second timeout applies.
     String getItemName(String id) throws RemoteException;

     // Override with a 20 second timeout.
     @Timeout(20)
     String getItemDescription(String id) throws RemoteException;

     // Override with a 100 millisecond timeout.
     @Timeout(100)
     @TimeoutUnit(TimeUnit.MILLISECONDS)
     String disableItem(String id) throws RemoteException;

     // A parameter is passed to define the timeout, overriding the default.
     // The timeout unit is seconds, as defined by the interface level annotation.
     void runReport(String param, @TimeoutParam int timeout) throws RemoteException;

     // A parameter and unit is passed to define the timeout. If runtime unit is
     // is null, it defaults to minutes.
     @TimeoutUnit(TimeUnit.MINUTES)
     void runReport(String param, @TimeoutParam int timeout, TimeUnit unit)
         throws RemoteException;

     // The timeout parameter is explicitly annotated, because of its non-standard
     // argument position. If runtime unit is null, seconds is assumed because
     // of interface level annotation.
     void runReport(String param, @TimeoutParam TimeUnit unit, @TimeoutParam int timeout)
         throws RemoteException;
 }
 

Author:

Brian S O'Neill

See Also:

TimeoutUnit, TimeoutParam

Required Element Summary

Required Elements

Modifier and Type	Required Element and Description
long	value Specify the timeout duration.

Element Detail

value

public abstract long value

Specify the timeout duration. Any negative value indicates an infinite timeout.