org.checkerframework.checker.mustcall.qual

Annotation Type MustCallAlias

@Documented
 @Retention(value=RUNTIME)
 @Target(value={PARAMETER,CONSTRUCTOR,METHOD,TYPE_USE})
public @interface MustCallAlias

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 java.net.Socket#getOutputStream:

 @MustCall("close")
 class Socket {
   @MustCallAlias OutputStream getOutputStream(@MustCallAlias Socket this) { ... }
 }

Calling close() on the returned OutputStream will close the underlying socket, but the Socket may also be closed directly, which has the same effect.

Verifying @MustCallAlias annotations

Suppose that @MustCallAlias is written on the type of formal parameter p.

For a constructor:

• The constructor must always write p into exactly one field f of the new object.
• Field f must be annotated @Owning.

For a method:

• All return sites must be calls to other methods or constructors with @MustCallAlias return types, and this method's @MustCallAlias parameter must be passed in the MustCallAlias position to that method or constructor (i.e., the calls must pass @MustCallAlias parameter through a chain of @MustCallAlias-annotated parameters and returns).

When the -AnoResourceAliases command-line argument is passed to the checker, this annotation is treated identically to PolyMustCall.

See the Checker Framework Manual:

Resource Leak Checker, Qualifier polymorphism