checkers.javari.quals
Annotation Type PolyRead

@Documented
@Retention(value=RUNTIME)
@TypeQualifier
public @interface PolyRead

Specifies the allowed mutabilities of a method's return value or the arguments, based on the mutability type of the arguments and the receiver at a method invocation. PolyRead has the same behavior as creating two copies of the method signature, one where all of its ocurrences are substituted with ReadOnly, and one where all of its occurences are substituted with Mutable; that is, if it were possible to have annotation overloading,

 @PolyRead getA() @PolyRead {return a;}
 

would be equivalent to

 @ReadOnly getA() @ReadOnly {return a;}
 getA() {return a;}
 

As a first example, if PolyRead appears in the return type of a method, at the method invocation it will be interpreted as ReadOnly if any the arguments passed to parameter annotated with ReadOnly is a readonly instance, or if the receiver type is readonly and the method is invocated from a readonly context. That is,

  @PolyRead aTestMethod(String a,
                            @PolyRead Object b,
                            List<@PolyRead Date> c) @PolyRead
 

has a readonly return type if the argument passed as b is readonly, or if the argument passed as c is a list of readonly Dates, or if the aTestMethod is invoked from a readonly receiver. Otherwise, it has a mutable return type. As a second example, if the receiver type of a constructor is annotated with PolyRead, the created instance will be readonly if any of the arguments passed to parameters annotated with PolyRead is readonly, and it will be mutable otherwise. That is,

  public Something(String a,
                   @PolyRead Object b,
                   List<@PolyRead Date> c) @PolyRead
 

instanciates a readonly Something if a readonly argument is passed as b, or if the argument passed as c is a list of readonly Dates. Otherwise, it instanciates a mutable Something. As a third example, if the return type of a method is not annotated anywhere with PolyRead, but its receiver type and some of its parameters are, then, at a mutable instance, only mutable arguments are accepted; at a readonly instance, both types of arguments are accepted. That is,

  aTestMethod(String a,
              @PolyRead Object b,
              List<@PolyRead Date> c) @PolyRead
 

when invoked from a mutable reference will only accept mutable arguments as b, and lists of mutable Dates as c. When aTestMethod is invoked from a readonly reference, it will accept readonly arguments as b, and lists of readonly arguments as c. Since the code must be legal at both "overloaded" cases, parameters annotated with PolyRead suffer the same restrictions inside the method body as parameters annotated with ReadOnly, and methods with receiver type annotated as PolyRead suffer the same restrictions as methods with receiver type annotated as ReadOnly.

This annotation is part of the Javari language.

See Also:

JavariChecker

See the Checker Framework manual:

Javari Checker