xapi.annotation.reflect.KeepAnnotation Maven / Gradle / Ivy

Show more of this group Show more artifacts with this name
Show all versions of xapi-dev Show documentation

Everything needed to run a comprehensive dev environment. Just type X_ and pick a service from autocomplete; new dev modules will be added as they are built. The only dev service not included in the uber jar is xapi-dev-maven, as it includes all runtime dependencies of maven, adding ~4 seconds to build time, and 6 megabytes to the final output jar size (without xapi-dev-maven, it's ~1MB).

The newest version!

package xapi.annotation.reflect;

import static java.lang.annotation.ElementType.ANNOTATION_TYPE;
import static java.lang.annotation.ElementType.CONSTRUCTOR;
import static java.lang.annotation.ElementType.FIELD;
import static java.lang.annotation.ElementType.METHOD;
import static java.lang.annotation.ElementType.PACKAGE;
import static java.lang.annotation.ElementType.PARAMETER;
import static java.lang.annotation.ElementType.TYPE;

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

/**
 * Annotation used to tell reflection subsystem to hold onto annotation data.
 * This annotation can be supplied almost anywhere to explicitly include
 * a particular set of annotations in the {@link ReflectionService}.
 * 
 * Can be applied to packages, classes, annotation types, parameters,
 * methods, fields and constructors.  The {@link ReflectionService} will do
 * its best to retain manual annotation retention overrides.
 * 

 * Primarily used in gwt reflection, but available as well for future
 * iterations of classpath scanner to intelligently discard runtime metadata (anything not annotated).
 * 

 * @author "James X. Nelson ([email protected])"
 */
@Documented
@Target({PACKAGE, TYPE, ANNOTATION_TYPE, FIELD, METHOD, CONSTRUCTOR, PARAMETER} )
@Retention(RetentionPolicy.RUNTIME)
public @interface KeepAnnotation {

  /**
   * DebugData to include.
   * @return "" (default) = no debug data / production mode
   * "anything" = keep this string, and print extra debug logging.
   * 

   * Using debugData.length > 0 will result in as much type data being preserved
   * as possible in log messages, including method default class types.
   */
  String debugData() default "";

  /**
   * Whether or not to defer including reflected constructor
   * into a code split containing all reflection data.
   * 

   * Implementations using xapi-gwt-inject won't need to worry as much,
   * the magic-method-injector will ensure code bloat is localized to call site.
   * 

   * Running without injection support will put all class data into a single,
   * monolithic, generated factory for the whole app, unless async is used.
   * 

   * @return true to force this code into async split.
   * false (default) to load synchronously; no boilerplate.
   * 

   * if true,
   * Generator will throw exception if accessed outside of X_Reflect.async()
   */
  boolean loadAsync() default false;

  /**
   * Used to allow package-level or type-level annotations to override children.
   * 

   * Good for overriding default settings temporarily; setting debugData and
   * preventOverride on package-info.java will turn on debugging for that package.
   * 

   * @return true, to prevent checking for more specific child types.
   * 
   * Inheritance Hierarchy Is ->
   * package-info.java -> OuterClass -> OuterClass$InnerClass -> ...
   */
  boolean preventOverride() default false;



}