org.checkerframework.framework.qual.PreconditionAnnotation 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.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

/**
 * A meta-annotation that indicates that an annotation R is a precondition annotation, i.e., R is a
 * type-specialized version of {@link RequiresQualifier}. The value {@code qualifier} that is
 * necessary for a precondition specified with {@link RequiresQualifier} is specified here with the
 * value {@code qualifier}.
 *
 * The annotation R that is meta-annotated as {@link PreconditionAnnotation} must have an element
 * called {@code value} that is an array of {@code String}s of the same format and with the same
 * meaning as the value {@code expression} in {@link RequiresQualifier}.
 *
 * 
The established precondition P has type specified by the {@code qualifier} field of this
 * annotation. If the annotation R has elements annotated by {@link QualifierArgument}, their values
 * are copied to the arguments (elements) of annotation P with the same names. Different element
 * names may be used in R and P, if a {@link QualifierArgument} in R gives the name of the
 * corresponding element in P.
 *
 * 
For example, the following code declares a precondition annotation for the {@link
 * org.checkerframework.common.value.qual.MinLen} qualifier:
 *
 * 

 * {@literal @}PreconditionAnnotation(qualifier = MinLen.class)
 * {@literal @}Target({ElementType.METHOD, ElementType.CONSTRUCTOR})
 * public {@literal @}interface RequiresMinLen {
 *   String[] value();
 *   {@literal @}QualifierArgument("value")
 *   int targetValue() default 0;
 * 
 *
 * The {@code value} element holds the expressions to which the qualifier applies and {@code
 * targetValue} holds the value for the {@code value} argument of {@link
 * org.checkerframework.common.value.qual.MinLen}.
 *
 * The following code then uses the annotation on a method that requires {@code field} to be
 * {@code @MinLen(2)} upon entry.
 *
 * 

 * {@literal @}RequiresMinLen(value = "field", targetValue = 2")
 * public char getThirdCharacter() {
 *   return field.charAt(2);
 * }
 * 
 *
 * @see RequiresQualifier
 * @see QualifierArgument
 */
@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.ANNOTATION_TYPE})
public @interface PreconditionAnnotation {
  /** The qualifier that must be established as a precondition. */
  Class qualifier();
}