com.surelogic

Annotation Type Region

@Documented
@Retention(value=RUNTIME)
@Target(value=TYPE)
public @interface Region

Declares a new abstract region of state for the class to which this annotation is applied. To declare more than one region for a class use the Regions annotation.

It is a modeling error for a class to have both a Regions and a Region annotation.

A @Region declaration along with corresponding @InRegion declarations provides a name for a subset of the fields of a class. This set is extensible: subclasses may add both new abstract regions via @Region annotations, and new fields via @InRegion annotations.

A region is either static or instance (non-static). A static region may contain both static and instance regions and fields. An instance region may only contain other instance regions and fields.

Regions are hierarchical in the form of a tree:

• The root is declared in Object and is a static region named All.
• The instance region Instance is a child of All and is also declared in java.lang.Object.
• Every programmer-declared region has a parent: If the parent is not explicitly declared in the @Region annotation, then the parent is All for static regions and Instance for instance regions.

The set of fields in a region R are those fields annotated with @InRegion("R") together with those fields that are recursively members of the region's children. There are three pre-defined regions available for use:

All

A region representing the entire state of the program's heap.

Instance

A region representing the instance state of an object.

Static

A region representing the static state of a class.

Semantics:

Declaration of a region does not constrain the implementation of the program, it simply gives a name to part of the program's state.

At runtime, a region represents a subset of the JVM heap, subdividing one or more objects in the heap. Let C.f denote field f declared in class C. Let R be a static region. The set of fields in R can be partitioned into the non-intersecting sets of static and instance fields S and I, respectively. The region R denotes the following subset of the heap:

• The field f of class C for each C.f ∈ S.
• The field f of each instance of class X where C.f ∈ I and X instanceof C.

The Region All contains all the fields, and thus denotes the entire runtime heap.

The instance region Q declared in class C is instantiated at runtime for each object of class X in the heap, where X instanceof C in the heap. Specifically, for an object o of type X such that X instanceof C, there is runtime region in the heap consisting of the fields o.f1, …, o.fn where fi is a member of Q.

Examples:

A private region, named ObserverRegion, that includes the field observers and the contents of the referenced set.

 @Region("private ObserverRegion")
 class Observer {
   @UniqueInRegion("ObserverRegion")
   private Set<Callback> observers = new HashSet<Callback>()
   ...
 }
 

The UniqueInRegion annotation is used to aggregate referenced state. The Unique annotation also allows aggregation of state, but only into the default Instance region.

A private region, named FinalObserverRegion, that includes the contents of the set referenced by the observers field, but not the field itself. The field is not included because it is declared final.

 @Region("private FinalObserverRegion")
 class Observer {
   @UniqueInRegion("FinalObserverRegion")
   private final Set<Callback> observers = new HashSet<Callback>()
   ...
 }
 

A region, named AircraftState, that contains three long fields use to represent the position of the object.

 @Region("private AircraftState")
 public class Aircraft {
 
   @InRegion("AircraftState")
   private long x, y;
   
   @InRegion("AircraftState")
   private long altitude;
   ...
 }
 

A region, named ThingState, that contains two long fields use to represent the position of a subclass. ThingState is empty in the parent class Thing but has state added into it in the subclass Player.

 @Region("protected ThingState")
 class Thing {
   ...
 }
 
 class Player extends Thing {
   @InRegion("ThingState")
   private long x, y;
   ...
 }
 

This is an example of a static region declared in a simple counter utility class.

 package com.surelogic;
 
 import com.surelogic.*;
 
 @Utility
 @Region("static public CounterState")
 public class CounterUtility {
 
   @InRegion("CounterState")
   private static long count = 0;
 
   @RegionEffects("writes CounterState")
   public static long incrementAndGet() {
     return ++count;
   }
 
   @RegionEffects("reads CounterState")
   public static long get() {
     return count;
   }
 
   private CounterUtility() {
     // no instances
   }
 }
 
 

Here is some client code of the counter class referencing the static CounterState region.

 package com.surelogic;
 
 import com.surelogic.RegionEffects;
 
 public class ClientCode {
 
   @RegionEffects("writes com.surelogic.CounterUtility:CounterState")
   public static void main(String[] args) {
     long counter = CounterUtility.incrementAndGet();
   }
 
 }
 

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("private AircraftState")
  */
 public class Aircraft {
   /**
    * @annotate InRegion("AircraftState")
    */
   private long x, y;
   
   /**
    * @annotate InRegion("AircraftState")
    */
   private long altitude;
   ...
 }
 

See Also:

InRegion, Regions, Unique, UniqueInRegion

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 = accessModifiers IDENTIFIER ["extends" regionSpecification]
   
 accessModifiers = ["public" / "protected" / "private"] [static]
 
 regionSpecification = simpleRegionSpecificaion / qualifiedRegionName
 
 simpleRegionSpecification = IDENTIFIER                         ; Region of the class being annotated
 
 qualifedRegionName = IDENTIFIER *("." IDENTIFIER) : IDENTIFER  ; Static region from the named, optionally qualified, class
 
 IDENTIFIER = Legal Java Identifier
 

As in Java, if neither public, protected, or private is declared then the region has default visibility; if static is not declared the region is an instance region.

If no explicit "extends" clause is provided the region extends from region Instance if it is an instance region, or All if it is a static region.