com.surelogic
Annotation Type Aggregate

@Documented
@Target(value=FIELD)
public @interface Aggregate

Declares that regions of the object referenced by this field are to be mapped into regions of the object that contains the field to which this annotation is applied.

It is a modeling error if the field declaration is not also annotated with Unique. It is a modeling error if the field declaration is also annotated with AggregateInRegion.

Although it is possible to use this annotation to aggregate the Instance region of a referenced object into a named region, it is recommended that the AggregateInRegion annotation be used in this case. For example, use AggregateInRegion("MyRegion") rather than the equivalent Aggregate("Instance into MyRegion") which makes the aggregation look similar to the more familiar InRegion.

Examples:

The below class incorporates the state referenced by the observers field (i.e., the internals of the HashSet object) into the Instance region of the Observer class.

 class Observer {

   @Unique
   @Aggregate
   private final Set<Callback> observers = new HashSet<Callback>()
   ...
 }
 

We can change the above example to use a named region instead of the default Instance region. The below class defines a region, called ObserverRegion, that includes the integer notifyCounter and the state referenced by the observers field (i.e., the internals of the HashSet object).

 @Region("private ObserverRegion")
 class Observer {

   @InRegion("ObserverRegion")
   private int notifyCounter = 0;

   @Unique
   @Aggregate("Instance into ObserverRegion")
   private final Set<Callback> observers = new HashSet<Callback>()
   ...
 }
 

However, the above syntax is not recommended. Instead it is recommended to use the AggregateInRegion annotation as shown below.

 @Region("private ObserverRegion")
 class Observer {

   @InRegion("ObserverRegion")
   private int notifyCounter = 0;

   @Unique
   @AggregateInRegion("ObserverRegion")
   private final Set<Callback> observers = new HashSet<Callback>()
   ...
 }
 

The syntax if only a portion of a referenced object is to be aggregated is more complex. Consider the highly contrived example below.

 @Regions({
   @Region("private OrderRegion"),
   @Region("private InvRegion") })
 @RegionLocks({
   @RegionLock("ShopLock is this protects OrderRegion"),
   @RegionLock("InvLock  is inv  protects InvRegion") })
 public class Shop {

   @InRegion("OrderRegion")
   private int ordersPlaced;
 
   private static class SandwichInventory {
     int bread;
     int mustard;
     int ordersPlaced;
   }
 
   @Unique
   @Aggregate("bread into InvRegion, mustard into InvRegion, ordersPlaced into OrderRegion, Instance into Instance")
   private final SandwichInventory inv = new SandwichInventory();

   void order() {
     synchronized (inv) {
       inv.bread++;
       inv.mustard++;
     }
     synchronized (this) {
       ordersPlaced++;
       inv.ordersPlaced++;
     }
   }
   ...
 }
 

In the above example the fields that count the number of orders placed are protected by synchronizing on this while the inventory fields ( bread and mustard) are protected by synchronizing on inv. All the state of the SandwichInventory must be placed into named regions (even if you never use one of the named regions, e.g., you create a JunkRegion) and the aggregation must be completed with a mapping of the region Instance of the referenced object, usually Instance into Instance.

Models of the sort shown for the Shop class above are discouraged and should occur rarely in Java code that follows object-oriented design principles.

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.

 class Observer {

   /**
    * @annotate Unique
    * @annotate Aggregate
    */
   private final Set<Callback> observers = new HashSet<Callback>()
   ...
 }
 

See Also:

AggregateInRegion, Unique

Optional Element Summary

String

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

value

public abstract String value

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

 value = regionMapping *("," regionMapping)
 
 regionMapping = simpleRegionSpecification "into" 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
 

In A into B, the first RegionSpecification is relative to the object referenced by the field; the second is relative to the object that contains the field.

Default:

"Instance into Instance"