com.surelogic
Annotation Type PolicyLock

@Documented
@Target(value=TYPE)
public @interface PolicyLock

Declares a new policy lock for the class to which this annotation is applied. This declaration creates a new named lock representing a particular lock object. Unlike a lock declared with RegionLock, a policy lock is not associated with any particular object state. Instead, a policy lock is used to enforce a higher-level invariant that requires a section of code to execute atomically with respect to some other section of code.

To declare more than one policy lock for a class use the PolicyLocks annotation. It is a modeling error for a class to have both a PolicyLocks and a PolicyLock annotation.

The named lock is a Java object. If the object's type implements java.util.concurrent.locks.Lock then the lock object must be used according to the protocol of the Lock interface. Otherwise, the object must be used as a Java intrinsic lock, i.e., with synchronized blocks.

Examples

The code below declares a policy lock named OutsideDoorLock for a Java intrinsic lock.

 @PolicyLock("OutsideDoorLock is outsideDoorLock")
 public class Station {
 
   private final Object outsideDoorLock = new Object();
 
   void m1() {
     synchronized (outsideDoorLock) {
       // work with the door
     }
   }
   ...
 }
 

The code below declares a policy lock named JailLock for a java.util.concurrent.locks.Lock.

 @PolicyLock("JailLock is jailLock")
 public class Station {
 
   private final Lock jailLock = new ReentrantLock();
 
   void m1() {
     jailLock.lock();
     try {
       // work with the jail
     } finally {
       jailLock.unlock();
     }
   }
   ...
 }
 

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 PolicyLock("OutsideDoorLock is outsideDoorLock")
  */
 public class Station {
   ...
 }
 

See Also:

PolicyLocks, RegionLock

Required Element Summary

String

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

Element Detail

value

public abstract String value

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

 value = IDENTIFIER "is" lockExpression
 
 lockExpression = simpleLockExpression / qualifiedLockExpression
 
 simpleLockExpression = 
   "class" /              ; the Class object referenced by the "class" pseudo-field of the annotated class
   "this" /               ; the instance itself
   "this" "." IDENTIFIER  ; the object referenced by the named field
 
 qualifiedLockExpression = 
   namedType "." "CLASS" /            ; the Class object referenced by the "class" pseudo-field of a named class
   namedType "." "THIS" /             ; a named enclosing instance
   namedType "." IDENTIFIER /         ; a named static field
   namedType "." THIS "." IDENTIFIER  ; a named field of an enclosing instance
 
 namedType = IDENTIFIER *("." IDENTIFIER)
 
 IDENTIFIER = Legal Java Identifier