com.surelogic

Annotation Type PolicyLock

@Documented
@Retention(value=RUNTIME)
@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. This is the only check performed, otherwise this annotation is trusted, i.e., the higher-level invariant is not verified. Its use is for documentation.

Semantics:

Declares a name for the given lock object, and conveys the intent that the 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. This annotation does not, however, elicit the higher-level invariant from the programmer.

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();
     }
   }
   ...
 }
 

The same lock object may be declared to be multiple locks (including to be a RegionLock):

 @Regions({
   @Region("protected Color"),
   @Region("protected Position"),
   @Region("protected Label")
 })
 @RegionLocks({
   @RegionLock("L1 is this protects Color"),
   @RegionLock("L2 is this protects Position"),
   @RegionLock("L3 is lockField protects Label")
 })
 @PolicyLocks({
   @PolicyLock("P1 is this"),
   @PolicyLock("L1 is lockField")
 })
 public class Sprite {
   protected final Object lockField = new Object();
   ...
 }
 

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

Required Elements

Modifier and Type	Required Element and Description
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