org.checkerframework.framework.qual.DefaultQualifier Maven / Gradle / Ivy

Show more of this group Show more artifacts with this name
Show all versions of checker Show documentation

The Checker Framework enhances Java's type system to make it more powerful and useful. This lets software developers detect and prevent errors in their Java programs. The Checker Framework includes compiler plug-ins ("checkers") that find bugs or verify their absence. It also permits you to write your own compiler plug-ins.

There is a newer version: 3.43.0

Show newest version

package org.checkerframework.framework.qual;

import java.lang.annotation.Annotation;
import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Repeatable;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

/**
 * Applied to a declaration of a package, type, method, variable, etc., specifies that the given
 * annotation should be the default. The default is applied to type uses within the declaration for
 * which no other annotation is explicitly written. (The default is not applied to the "parametric
 * locations": class declarations, type parameter declarations, and type parameter uses.) If
 * multiple {@code DefaultQualifier} annotations are in scope, the innermost one takes precedence.
 * DefaultQualifier takes precedence over {@link DefaultQualifierInHierarchy}.
 *
 * You may write multiple {@code @DefaultQualifier} annotations (for unrelated type systems, or
 * with different {@code locations} fields) at the same location. For example:
 *
 * 
 *   @DefaultQualifier(NonNull.class)
 *   @DefaultQualifier(value = NonNull.class, locations = TypeUseLocation.IMPLICIT_UPPER_BOUND)
 *   @DefaultQualifier(Tainted.class)
 *   class MyClass { ... }
 * 
 *
 * This annotation currently has no effect in stub files.
 *
 * @see org.checkerframework.framework.qual.TypeUseLocation
 * @see DefaultQualifierInHierarchy
 * @see DefaultFor
 * @checker_framework.manual #defaults Default qualifier for unannotated types
 */
@Documented
@Retention(RetentionPolicy.SOURCE)
@Target({
  ElementType.PACKAGE,
  ElementType.TYPE,
  ElementType.CONSTRUCTOR,
  ElementType.METHOD,
  ElementType.FIELD,
  ElementType.LOCAL_VARIABLE,
  ElementType.PARAMETER
})
@Repeatable(DefaultQualifier.List.class)
public @interface DefaultQualifier {

  /**
   * The Class for the default annotation.
   *
   * 
To prevent affecting other type systems, always specify an annotation in your own type
   * hierarchy. (For example, do not set {@link
   * org.checkerframework.common.subtyping.qual.Unqualified} as the default.)
   */
  Class value();

  /**
   * Returns the locations to which the annotation should be applied.
   *
   * @return the locations to which the annotation should be applied
   */
  TypeUseLocation[] locations() default {TypeUseLocation.ALL};

  /**
   * A wrapper annotation that makes the {@link DefaultQualifier} annotation repeatable.
   *
   * Programmers generally do not need to write this. It is created by Java when a programmer
   * writes more than one {@link DefaultQualifier} annotation at the same location.
   */
  @Documented
  @Retention(RetentionPolicy.RUNTIME)
  @Target({
    ElementType.PACKAGE,
    ElementType.TYPE,
    ElementType.CONSTRUCTOR,
    ElementType.METHOD,
    ElementType.FIELD,
    ElementType.LOCAL_VARIABLE,
    ElementType.PARAMETER
  })
  @interface List {
    /**
     * Return the repeatable annotations.
     *
     * @return the repeatable annotations
     */
    DefaultQualifier[] value();
  }
}