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

Go to download

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.42.0-eisop4

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.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();
}