com.surelogic

Annotation Type ReadOnly

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

Declares that the parameter, receiver, return value, or field to which this annotation is applied cannot be used to mutate the referenced object. A read-only reference differs from a an immutable reference in that @ReadOnly does not exclude the existence of references used for mutation. A read-only parameter, unlike a borrowed parameter for which mutation is not permitted, may be compromised/aliased. Thus we normally do not recommend variables be annotated @ReadOnly unless the callee wishes to retain a reference.

A Borrowed field may be annotated @ReadOnly to indicate that the field cannot be used for mutation.

It is a modeling error to annotate a primitive type. For example

 @ReadOnly("return") public int getValue() { … }

and

 public void setValue(@ReadOnly int value) { … }
 

would generate modeling errors.

This annotation is not currently checked by analysis and is still experimental. It may be used for documentation purposes.

Semantics:

Parameter:

Return Value:

Field:

Examples:

Under development.

Javadoc usage notes:

This annotation may placed in Javadoc, which can be useful for Java 1.4 code which does not include language support for annotations, via the @annotate tag. One complication is that the parameter being annotated must be explicitly specified because the annotation can no longer appear in the context of the parameter declaration.

 /**
  * @annotate ReadOnly("a, b, c")
  */
 public void m1(Object a, Object b, Object c) { ... }
 

This annotation states that the three parameters are readonly. Alternatively, you can use several annotations as shown below.

 /**
  * @annotate ReadOnly("a")
  * @annotate ReadOnly("b")
  * @annotate ReadOnly("c")
  */
 public void m1(Object a, Object b, Object c) { ... }
 

See Also:

Borrowed, Immutable

Optional Element Summary

Optional Elements

Modifier and Type	Optional Element and Description
String	value When annotating a method, this attribute is used to disambiguate whether the annotation refers to the method's receiver, the method's return value, or both.

Element Detail

value

public abstract String value

When annotating a method, this attribute is used to disambiguate whether the annotation refers to the method's receiver, the method's return value, or both. The value is comma separated list of tokens, and has the following set of legal values (ignoring white space issues):

• ""
• "this"
• "return"
• "this, return"
• "return, this"

The values are interpreted thusly

• If the list contains the value "this", it indicates the receiver is readonly. This value is only allowed on methods.
• If the list contains the value "return", it indicates the return value is readonly. This value is allowed on methods and constructors.
• If the list contains both "this" and "return", it indicates that both the receiver and the return value are readonly. This value is only allowed on methods.

This attribute is not used when annotating a parameter or a field: the attribute value must be the empty string in these cases.

The value of this attribute must conform to the following grammar (in Augmented Backus–Naur Form):

 value = [("this" ["," "return"]) / ("return" ["," "this"])] ; See above comments
 

Default:

""