com.surelogic

Annotation Type ReturnsLock

@Documented
@Retention(value=RUNTIME)
@Target(value=METHOD)
public @interface ReturnsLock

Declares that the object returned by the method to which this annotation is applied is the named lock. This allows the representation of the lock to be concealed from clients of the object, but still makes the lock accessible to them. It is a modeling error if the return type of the annotated method is a primitive type.

Methods that override a method annotated with @ReturnsLock("l") must also be explicitly annotated @ReturnsLock("l"). It is a modeling error if they are not.

Semantics:

Constrains the return value of the annotated method to be non-null and reference the lock object declared in the RegionLock or PolicyLock declaration for the named lock.

Examples:

A parent class, Thing, returns a lock used to protected subclass state.

 @Region("protected ThingState")
 @RegionLock("ThingLock is thingLock protects ThingState")
 class Thing {
   private final Object thingLock = new Object();
 
   @ReturnsLock("ThingLock")
   protected Object getThingLock() {
     return thingLock;
   }
   ...
 }
 

The lock getter method can then be used in subclasses such as the Player below.

 class Player extends Thing {
   @InRegion("ThingState")
   private long x, y;
 
   public void setPosition(long x, long y) {
     synchronized (getThingLock()) {
       this.x = x;
       this.y = y;
     }
   }
   ...
 }
 

A lock getter method may return a policy lock:

 @PolicyLock("InitLock is initLock")
 public class System {
   private final Object initLock = new Object();
   ...
   @ReturnsLock("InitLock")
   protected Object getInitLock() {
     return initLock;
   }
 }
 

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.

 /**
  * @annotate Region("protected ThingState")
  * @annotate RegionLock("ThingLock is thingLock protects ThingState")
  */
 class Thing {
   private final Object thingLock = new Object();
 
   /**
    * @annotate ReturnsLock("ThingLock")
    */
   protected Object getThingLock() {
     return thingLock;
   }
   ...
 }
 

See Also:

RegionLock

Required Element Summary

Required Elements

Modifier and Type	Required Element and Description
String	value The name of the lock returned by the annotated method.

Element Detail

value

public abstract String value

The name of the lock returned by the annotated method. The value of this attribute must conform to the following grammar (in Augmented Backus–Naur Form):

 value = lockSpecification
 
 lockSpecification = qualifiedLockSpecification / simpleLockSpecification
 
 simpleLockSpecification = simpleLockName ["." ("readLock" / "writeLock")]
 
 qualifiedLockSpecification = qualifiedLockName ["." ("readLock" / "writeLock")]
 
 simpleLockName = IDENTIFIER  ; Lock from the receiver (same as "this:IDENTIFIER")
 
 qualifiedLockName = parameterLockName / typeQualifiedLockName / innerClassLockName
 
 parameterLockName = simpleExpression ":" IDENTIFIER  ; Lock from a method/constructor parameter
 
 simpleExpression = "this" / IDENTIFER  ; Receiver or parameter name
 
 typeQualifiedLockName = typeExpression ":" IDENTIFIER  ; Static lock qualified by a class name
 
 typeExpression = IDENTIFIER *("." IDENTIFIER)
 
 innerClassLockName = namedType "." "this" ":" IDENTIFIER ; Lock from an enclosing instance
 
 namedType = IDENTIFIER *("." IDENTIFIER)
 
 IDENTIFIER = Legal Java Identifier