de.skuzzle.inject.async.annotation

Annotation Type Scheduled

@Retention(value=RUNTIME)
 @Target(value=METHOD)
public @interface Scheduled

Marks a method to be executed periodically. In order for a method to be eligible for periodic execution, it must additionally be annotated with exactly one trigger annotation. The trigger defines the way in which the method will be scheduled. Possible triggers are:

• SimpleTrigger - Define a delay or rate at which the method should be scheduled.
• CronTrigger - Define a complex cron job pattern to define the periodicity.
• DelayedTrigger - Method will be executed only once after a provided delay.
• Custom - You can provide a custom TriggerStrategy using Java's Service Provider Interfaces.

Methods are scheduled for execution by the time an instance of their containing type is constructed using the Injector.

WARNING: You should only ever schedule methods in classes bound as Singleton! Otherwise you will prevent scoped objects from being garbage collected and cause a memory leak.

Specifying the Scheduler

Methods are scheduled by using an implementation of ScheduledExecutorService. You can provide a Key that will be used to look up the scheduler implementation on a per-method basis.

• You can put any BindingAnnotation including Named on the method to specify the annotation part of the Key.
• If you need to reference a certain ScheduledExecutorService sub type, you can use Scheduler to specify the class part of the Key.

For example, if your method may look like:

 @Scheduled
 @SimpleTrigger(5000) // execute every 5 seconds
 @Named("mainScheduler")
 @Scheduler(AdvancedScheduler.class)
 public void compute() {...}
 

In this case, the Scheduler to use will be looked up like injector.getInstance(Key.get(AdvancedScheduler.class, Names.named("mainScheduler"))

If you leave out the Scheduler part, the class defaults to ScheduledExecutorService.class. If you leave out the binding annotation, the created key will not have an annotation part. If you put neither a binding annotation nor a Scheduler class on the method, a default ScheduledExecutorService is used which is created internally. You should make no assumptions about the actual behavior of that service and it is highly recommended to bind and specify an ScheduledExecutorService yourself.

 public class MyModule extends AbstractModule {
     @Provides
     public ThreadFactory provideMyThreadFactory() {
         return new ThreadFactoryBuilder()....build(); // class from Google guava
     }

     @Provides
     @Named("mainScheduler")
     public ScheduledExecutorService provideMyExecutor(ThreadFactory threadFactory) {
         return Executors.newScheduledThreadPool(NUM_OF_THREADS, threadFactory);
     }
 }
 

Injecting parameters

The framework will take care of injecting all parameters of a scheduled method when it is being executed. The injected objects are retrieved from the Injector right before every execution of the method.

 @Scheduled
 @SimpleTrigger(5000) // execute every 5 seconds
 public void compute(ComputationService service,
     @Named("threshold") int computationThreshold) {...}
 

Thread safety

As your method is executed asynchronously, special care has to be taken to ensure thread safety of that operation. Beware of the following:

• Do not access attributes of the surrounding class. If you do, use synchronization to ensure visibility of the data that you write and read .
• Parameters that are passed to the asynchronous method are also transferred to the executing thread. Thus, all actual parameters must be thread safe. That is, they must use synchronization and/or volatile declarations to ensure integrity and visibility of the data that is written and read.

Exception handling

Scheduled methods can throw checked exceptions. If they do, those exceptions will be delegated to the ExceptionHandler in place. You can specify a custom handler for a scheduled method using the OnError annotation. If you do not specify a handler, a default handler which prints a log message will be used.

Author:

Simon Taddiken