com.signalfx.shaded.checkerframework.checker.mustcall.qual.MustCallAlias Maven / Gradle / Ivy
package com.signalfx.shaded.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.
*
* 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.
*
* 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}.
*
* @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 {}