org.curjent.agent
Annotation Type Expiration


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

Agent call expirations. By default, calls are queued and remain in the queue until they finish executing. This annotation configures calls to expire after a specified timeout. If the call expires, the agent throws an ExpiredException to any waiting caller and sets the call's completion code to CallCompletion.CALL_EXPIRED.

The expiration timeout starts when the call is made. A background thread from AgentConfig.getExecutor() expires the call at, or shortly after, the timeout period. Only waiting calls expire. A call cannot expire once it begins executing or after it has finished.

The follow example shows the configuration of the print method to expire if it has not started executing within 60 seconds:

  class PrinterTask {
      @Expiration(timeout=60, unit=TimeUnit.SECONDS)
      void print(Document document) {
          process(document);
      }
  }
 
It is also possible to configure all methods with a class-level annotation:
  @Expiration(timeout=60, unit=TimeUnit.SECONDS)
  class PrinterTask {
      void print(Document document) {
          process(document);
      }
      
      void print(String name) {
          process(name);
      }
      
      @Expiration(timeout=Long.MAX_VALUE)
      void cancel(Document document) {
          remove(document);
      }
  }
 
Both print methods above expire after a minute. Method-level annotations have precedence over class-level annotations, so calls to the cancel method won't expire.

Expiration annotations define the static compile-time timeouts for agent calls. Timeouts are also configurable dynamically via AgentConfig.setExpirationTimeout(long, TimeUnit), CallSite.setExpirationTimeout(long, TimeUnit), and AgentCall.setExpirationTimeout(long, TimeUnit). Call configurations take precedence over site configurations, and site configurations take precedence of agent configurations. Dynamic runtime configurations override static compile-time annotations.


Required Element Summary
 long timeout
          Duration a call waits to begin executing before it expires.
 
Optional Element Summary
 TimeUnit unit
          Time unit for timeout().
 

Element Detail

timeout

public abstract long timeout
Duration a call waits to begin executing before it expires. Valid values range from 1 to Long.MAX_VALUE. The time unit is specified by unit().

unit

public abstract TimeUnit unit
Time unit for timeout(). May be null if the timeout value is Long.MAX_VALUE.

Default:
java.util.concurrent.TimeUnit.NANOSECONDS


Copyright 2009-2011 Tom Landon
Apache License 2.0