org.checkerframework.framework.qual.HasQualifierParameter Maven / Gradle / Ivy
package org.checkerframework.framework.qual;
import java.lang.annotation.Annotation;
import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Inherited;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
/**
* This is a declaration annotation that applies to type declarations and packages. On a type, it
* means that the class conceptually takes a type qualifier parameter, though there is nowhere to
* write it because the class hard-codes a Java basetype rather than taking a type parameter.
* Writing {@code HasQualifierParameter} on a package is the same as writing it on each class in
* that package.
*
* Writing {@code @HasQualifierParameter} on a type declaration has two effects.
*
*
* - Invariant subtyping is used for occurrences of the type: no two occurrences of the type
* with different qualifiers have a subtyping relationship.
*
- The polymorphic qualifier is the default for all occurrences of that type in its own
* compilation unit, including as the receiver, as another formal parameter, or as a return
* type.
*
*
* Here is an example of the effect of invariant subtyping. Suppose we have the following
* declaration:
*
*
* {@code @HasQualifierParameter}
* class StringBuffer { ... }
*
*
* Then {@code @Tainted StringBuffer} is unrelated to {@code @Untainted StringBuffer}.
*
* The type hierarchy looks like this:
*
*
*
* {@code @Tainted} Object
* / | \
* / | {@code @Tainted} Date
* / | |
* / | |
* / {@code @Untainted} Object |
* / | \ |
* {@code @Tainted} StringBuffer | {@code @Untainted} Date
* | |
* | {@code @Untainted} StringBuffer
* | |
* {@code @Tainted} MyStringBuffer |
* |
* {@code @Untainted} MyStringBuffer
*
*
* When a class is {@code @HasQualifierParameter}, all its subclasses are as well.
*
*
When {@code @HasQualifierParameter} is written on a package, it is equivalent to writing that
* annotation on each class in the package or in a sub-package. It can be disabled on a specific
* class and its subclasses by writing {@code @NoQualifierParameter} on that class. This annotation
* may not be written on the same class as {@code NoQualifierParameter} for the same hierarchy.
*
* @see NoQualifierParameter
*/
@Inherited
@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.TYPE, ElementType.PACKAGE})
public @interface HasQualifierParameter {
/**
* Class of the top qualifier for the hierarchy for which this class has a qualifier parameter.
*
* @return the value
*/
Class[] value();
}