org.checkerframework.checker.mustcall.qual.MustCallAlias Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of checker-qual Show documentation
checker-qual contains annotations (type qualifiers) that a programmer writes to specify Java code for type-checking by the Checker Framework.
The newest version!
package org.checkerframework.checker.mustcall.qual;

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;

/**
 * This polymorphic annotation represents an either-or must-call obligation. This annotation should
 * always be used in pairs. On a method, it is written on some formal parameter type and on the
 * method return type. On a constructor, it is written on some formal parameter type and on the
 * result type. Fulfilling the must-call obligation of one is equivalent to fulfilling the must-call
 * obligation of the other. Beyond its impact as a polymorphic annotation on {@code MustCall} types,
 * the Resource Leak Checker uses {@link MustCallAlias} annotations to more precisely determine when
 * a must-call obligation has been satisfied.
 *
 * This annotation is useful for wrapper objects. For example, consider the declaration of {@code
 * java.net.Socket#getOutputStream}:
 *
 * 
 * @MustCall("close")
 * class Socket {
 *   @MustCallAlias OutputStream getOutputStream(@MustCallAlias Socket this) { ... }
 * }
 *
 * Calling {@code close()} on the returned {@code OutputStream} will close the underlying socket,
 * but the Socket may also be closed directly, which has the same effect.
 *
 * Type system semantics
 *
 * Within the Must Call Checker's type system, {@code @MustCallAlias} annotations have a semantics
 * different from a standard polymorphic annotation, in that the relevant actual parameter type and
 * return type at a call site are not equated in all cases. Given an actual parameter {@code p}
 * passed in a {@code @MustCallAlias} position at a call site, the return type of the call is
 * defined as follows:
 *
 * 
 *   If the base return type has a non-empty {@code @InheritableMustCall("m")} annotation on its
 *       declaration, and {@code p} has a non-empty {@code @MustCall} type, then the return type is
 *       {@code @MustCall("m")}.
 *   
In all other cases, the return type has the same {@code @MustCall} type as {@code p}.
 * 
 *
 * {@link PolyMustCall} has an identical type system semantics. This special treatment is required
 * to allow for a wrapper object to have a must-call method with a different name than the must-call
 * method name for the wrapped object.
 *
 * Verifying {@code @MustCallAlias} annotations
 *
 * Suppose that {@code @MustCallAlias} is written on the type of formal parameter {@code p}.
 *
 * For a constructor:
 *
 * 

 *   The constructor must always write p into exactly one field {@code f} of the new object.
 *   
Field {@code f} must be annotated {@code @}{@link Owning}.
 * 
 *
 * For a method:
 *
 * 
 *   All return sites must be calls to other methods or constructors with {@code @MustCallAlias}
 *       return types, and this method's {@code @MustCallAlias} parameter must be passed in the
 *       {@code MustCallAlias} position to that method or constructor (i.e., the calls must pass
 *       {@code @MustCallAlias} parameter through a chain of {@code @MustCallAlias}-annotated
 *       parameters and returns).
 * 
 *
 * When the -AnoResourceAliases command-line argument is passed to the checker, this annotation is
 * treated identically to {@link PolyMustCall}. That is, the annotation still impacts {@link
 * MustCall} types as a polymorphic annotation (see "Type system semantics" above), but it is not
 * used by the Resource Leak Checker to more precisely reason about when obligations have been
 * satisfied.
 *
 * @checker_framework.manual #resource-leak-checker Resource Leak Checker
 * @checker_framework.manual #qualifier-polymorphism Qualifier polymorphism
 */
@Documented
@Retention(RetentionPolicy.RUNTIME)
// In Java 11, this can be:
// @Target({ElementType.PARAMETER, ElementType.CONSTRUCTOR, ElementType.METHOD})
@Target({ElementType.PARAMETER, ElementType.CONSTRUCTOR, ElementType.METHOD, ElementType.TYPE_USE})
public @interface MustCallAlias {}