com.surelogic

Annotation Type InRegion

@Documented
@Retention(value=RUNTIME)
@Target(value={TYPE,FIELD})
public @interface InRegion

Declares that the field to which this annotation is applied is mapped into the named region.

When annotated on a type this annotation can be used to map several fields into a named region. This can be more concise than multiple InRegion annotations on the individual fields, this conciseness comes at the price of moving information about particular fields away from their declarations.

Which style is preferred, annotation on fields or on types, is a matter of programmer preference.

Semantics:

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

Examples:

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

The following example uses an InRegion annotation on the class declaration for C to map the fields f1, f2, and f3 into the region CState.

 @Region("private CState")
 @InRegion("f1, f2, f3 into CState")
 public class C {
   private int f1;
   private int f2;
   private int f3;
   ...
 }
 

The above example is equivalent to the following use of InRegion on field declarations.

 @Region("private CState")
 public class C {
   @InRegion("CState") private int f1;
   @InRegion("CState") private int f2;
   @InRegion("CState") private int f3;
   ...
 }
 

Which style is preferred is a matter of programmer preference.

To apply more than one InRegion annotation to a class use the InRegions annotation. It is a modeling error for a class to have both a InRegion and a InRegions annotation. It is a modeling error for a field that is named in an InRegion annotation on a class declaration to also have an InRegion annotation on its field declaration. That is, the below class has a modeling error:

 @Region("private Appearance")
 @InRegion("color into Appearance")
 public class Sprite {
   @InRegion("Appearance") private int color;
   ...
 }
 

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:

InRegions, Unique, UniqueInRegion

Required Element Summary

Required Elements

Modifier and Type	Required Element and Description
String	value On a field the value of this attribute indicates the abstract region that is the superregion of the annotated field.

Element Detail

value

public abstract String value

On a field the value of this attribute indicates the abstract region that is the superregion of the annotated field. The value of this attribute must conform to the following grammar (in Augmented Backus–Naur Form):

 value = regionSpecification
 
 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
 

On a type the value of this attribute lists a set of fields that are mapped into a region. The value of this attribute must conform to the following grammar (in Augmented Backus–Naur Form):

 value = fieldList "into" regionName
 
 fieldList = IDENTIFIER *("," IDENTIFIER)
 
 regionName = IDENTIFIER
 
 IDENTIFIER = Legal Java Identifier