de.skuzzle.inject.async.TriggerStrategy Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of guice-async-extension Show documentation
Allows to execute tagged methods asynchronously
There is a newer version: 2.0.0
Show newest version
package de.skuzzle.inject.async;


import java.lang.annotation.Annotation;
import java.lang.reflect.Method;
import java.util.ServiceLoader;
import java.util.concurrent.ScheduledExecutorService;

import de.skuzzle.inject.async.annotation.Trigger;
import de.skuzzle.inject.async.util.InjectedMethodInvocation;

/**
 * Defines how a certain {@link Trigger} annotation is handled in order to
 * extract scheduling meta information and to actually schedule method
 * invocations.
 * 
 * The framework searches for implementations of this class using the Java's
 * {@link ServiceLoader}. In order to implement your own trigger, just follow these steps:
 * 
 * 
 * Create a new Trigger annotation which will hold scheduling meta information:
 *  * @Trigger
 * @Retention(RetentionPolicy.RUNTIME)
 * @Target(ElementType.METHOD)
 * public @interface CustomTrigger {
 *     // meta information fields
 * }
 * 
 * 
 * Create an implementation of this interface to handle the new annotation:
 *  * public class CustomTriggerStrategy implements TriggerStrategy {
 *
 *     // Field injection is allowed
 *     @Inject
 *     private Injector injector;
 *
 *     // public no-argument constructor required (because of the ServiceLoader)!
 *
 *     @Override
 *     public Class<CustomTrigger> getTriggerType() {
 *         return CustomTrigger.class;
 *     }
 *
 *     @Override
 *     public void schedule(Method method, Object self,
 *             ScheduledExecutorService executor) {
 *
 *         // read trigger annotation from the method
 *         CustomTrigger trigger = method.getAnnotation(getTriggerType());
 *
 *         // use meta information from the trigger to schedule the execution with the
 *         // provided executor (might want to use InjectedMethodInvocation class)
 *         executor.schedule(...);
 *     }
 * }
 * 
 * 
 * Register your implementation for the ServiceLoader. Create the folder structure
 * 'META-INF/services'. Within the services folder create a file named
 * 'de.skuzzle.inject.async.TriggerStrategy'. Put a single line which contains the
 * full qualified class name of your CustomTriggerStrategy into that file.
 * 
 * @author Simon Taddiken
 */
public interface TriggerStrategy {

    /**
     * Returns the annotation type that this strategy can handle.
     *
     * @return The annotation type.
     */
    Class getTriggerType();

    /**
     * Extracts scheduling information from the provided {@link Method} and then
     * schedules invocations of that method according to the information.
     *
     * 
     * To support invocation of parameterized methods, implementors can refer to
     * {@link InjectedMethodInvocation} to inject actual parameters of a method.
     * 
     *
     * @param method The method to schedule.
     * @param self The object to invoke the method on.
     * @param executor The executor to use for scheduling.
     */
    void schedule(Method method, Object self, ScheduledExecutorService executor);
}