org.checkerframework.checker.mustcall.qual.CreatesMustCallFor 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 org.checkerframework.checker.calledmethods.qual.CalledMethods;
import org.checkerframework.framework.qual.InheritedAnnotation;
import org.checkerframework.framework.qual.JavaExpression;

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;

/**
 * Indicates that the method resets the expression's must-call type to its declared type. This
 * effectively undoes flow-sensitive type refinement. The expression is the {@code value}
 * argument/element. More precisely, a call to a method annotated by this annotation changes the
 * expression's must-call type to the least upper bound of its current must-call type and its
 * declared must-call type.
 *
 * When calling a method annotated as {@code @CreatesMustCallFor("}expression{@code ")},
 * the {@code expression}'s static type in the Called Methods type system must be {@code @}{@link
 * CalledMethods}{@code ({})}. That is, {@code expression}'s CalledMethods type must be empty.
 *
 * 
{@code @CreatesMustCallFor("obj")} must be written on any method that assigns a non-final,
 * owning field of {@code obj} whose declared type has a must-call obligation.
 *
 * 
Because this annotation can only add obligations, it can be written safely on any method, even
 * one that does not actually create a new obligation. Writing this annotation on a method that does
 * not actually create any new obligations may lead to false alarms (warnings at correct code), but
 * never to missed alarms (lack of warnings at incorrect code).
 *
 * 
As an example, consider the following code, which uses a {@code @CreatesMustCallFor}
 * annotation to indicate that the {@code reset()} method re-assigns the {@code socket} field:
 *
 * 
 * @MustCall("stop")
 * class SocketContainer {
 *     // Note that @MustCall("close") is the default type for java.net.Socket, but it
 *     // is included on the next line for illustrative purposes. This example would function
 *     // identically if that qualifier were omitted.
 *     private @Owning @MustCall("close") Socket socket = ...;
 *
 *     @EnsuresCalledMethods(value="this.socket", methods="close")
 *     public void stop() throws IOException {
 *       socket.close();
 *     }
 *
 *    @CreatesMustCallFor("this")
 *    public void reset() {
 *      if (socket.isClosed()) {
 *        socket = new Socket(...);
 *      }
 *    }
 * }
 * 
 *
 * A client of {@code SocketContainer} is permitted to call {@code reset()} arbitrarily many times.
 * Each time it does so, a new {@code Socket} might be created. A {@code SocketContainer}'s
 * must-call obligation of "stop" is fulfilled only if {@code stop()} is called after the last call
 * to {@code reset()}. The {@code @CreatesMustCallFor} annotation on {@code reset()}'s declaration
 * enforces this requirement: at any call to {@code reset()}, all called-methods information about
 * the receiver is removed from the store of the Must Call Checker and the store of the Called
 * Methods Checker, so the client has to "start over" as if a fresh {@code SocketContainer} object
 * had been created.
 *
 * When the {@code -AnoCreatesMustCallFor} command-line argument is passed to the checker, this
 * annotation is ignored and all fields are treated as non-owning.
 *
 * @checker_framework.manual #resource-leak-checker Resource Leak Checker
 */
@Target({ElementType.METHOD})
@InheritedAnnotation
@Retention(RetentionPolicy.RUNTIME)
@Repeatable(CreatesMustCallFor.List.class)
public @interface CreatesMustCallFor {

    /**
     * Returns the expression whose must-call type is reset after a call to a method with this
     * annotation. The expression must be visible in the scope immediately before each call site, so
     * it can only refer to fields, the method's parameters (which should be referenced via the "#X"
     * syntax, where "#1" is the first argument, #2 is the second, etc.), or {@code "this"}. The
     * default is {@code "this"}. At call-sites, the viewpoint-adapted referent of expression must
     * be owning (an owning field, a local variable tracked in a resource alias set, etc.) or a
     * {@code reset.not.owning} error is issued.
     *
     * @return the expression to which must-call obligations are added when the annotated method is
     *     invoked
     */
    @JavaExpression
    String value() default "this";

    /**
     * A wrapper annotation that makes the {@link CreatesMustCallFor} annotation repeatable.
     *
     * Programmers generally do not need to write this. It is created by Java when a programmer
     * writes more than one {@link CreatesMustCallFor} annotation at the same location.
     *
     * @checker_framework.manual #must-call-checker Must Call Checker
     */
    @Documented
    @Retention(RetentionPolicy.RUNTIME)
    @Target({ElementType.METHOD})
    @InheritedAnnotation
    public static @interface List {
        /**
         * Return the repeatable annotations.
         *
         * @return the repeatable annotations
         */
        CreatesMustCallFor[] value();
    }
}