Annotation 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

 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