Annotation Interface MustCallAlias
@Documented
@Retention(RUNTIME)
@Target({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.
Verifying
Suppose that
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
.
- 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 theMustCallAlias
position to that method or constructor (i.e., the calls must pass@MustCallAlias
parameter through a chain of@MustCallAlias
-annotated parameters and returns).
PolyMustCall
.- See the Checker Framework Manual:
- Resource Leak Checker, Qualifier polymorphism