HttpCall.java

package com.mastfrog.acteur.annotations;

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

/**
 * Mark a Page or Acteur class as being something which GenericApplication
 * should automatically find and add to itself as an HTTP endpoint. This
 * annotation can be applied to Page classes and GenericApplication will simply
 * load the class and call <code>add(theType)</code> on itself in its
 * constructor. If this annotation is supplied to subtypes of Acteur, then a
 * Page subtype is generated by the annotation processor, and that is what will
 * be looked up.
 *
 * @author Tim Boudreau
 */
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.TYPE)
public @interface HttpCall {
    public static final String GENERATED_SOURCE_SUFFIX = "__GenPage";
    public static final String META_INF_PATH = "META-INF/http/pages.list";

    /**
     * Specify the order in which this call is added to the application. This is
     * useful for special Page/Acteur types which act as catch-all fallbacks if
     * a request has not been matched; such acteurs should get a <i>higher</i>
     * number so as to appear last. The numbers are ad-hoc and it is up to the
     * application author to establish their range. A good way to do it to have
     * pleny of flexibility later is to use increments of 1000.  If multiple
     * pages/acteurs are registered with the same order number, then their
     * order is determined by the order in which they appear on the classpath.
     * <p/>
     * Note:  HTTP calls are ordered only with respect to other ones within
     * the same JAR file, not in relation to ones coming from other JARs.  Use
     * classpath order to determine the order in which registries from different
     * JAR files are read.
     *
     * @return An ad-hoc absolute order for the class annotated by this
     * annotation
     */
    int order() default 0;

    /**
     * Specify some types which this page/acteur will produce or consume by passing them
     * to <code>new ConsumedLockedState(someObject, otherObjecct)</code> which
     * should be bound in the application's request scope so that they can be
     * found by subsequent acteurs.  GenericApplicationModule will find all such
     * listed types and bind them in that scope.
     * 
     * @return An array of Class objects
     */
    Class<?>[] scopeTypes() default {};
}