com.surelogic

Annotation Type BorrowedInRegion

@Documented
@Retention(value=RUNTIME)
@Target(value=FIELD)
public @interface BorrowedInRegion

Annotating a field as @BorrowedInRegion means that the entity pointed to by the field is unique as long as the object with the annotated field is being used. Put another way, the borrowed field is treated as unique as long as the unique object assigned to it isn't being used. Once the original reference is used, the borrowed field cannot be used any more. Such a field can be initialized with a value of a borrowed parameter to a constructor as long as the parameter's borrowed annotation sets the allowsReturn attribute to true and we have write access to its complete state. A @BorrowedInRegion field must be final and cannot be static.

This annotation differs from Borrowed only with regard to the region the state referenced by the annotated field is mapped into. This annotation declares that the Instance region of the object referenced by the annotated field is mapped into a named region of the object that contains the annotated field. Borrowed maps the state into the Instance region of the object that contains the annotated field. Therefore, the two annotations below on the friends field are equivalent.

 @Borrowed
 private final Set<Person> friends; // initialized in constructor
 
 @BorrowedInRegion("Instance")
 private final Set<Person> friends; // initialized in constructor
 

In addition, a more complex syntax is allowed where regions of the object referenced by the annotated field are explicitly mapped to regions of the object that contains the annotated field. Using this syntax the annotation below is equivalent to the two previous examples.

 @BorrowedInRegion("Instance into Instance")
 private final Set<Person> friends; // initialized in constructor
 

This syntax should be rare in practice, however we show an example of its use in the Examples section below.

Borrowed fields are not currently assured by analysis.

Semantics:

Examples:

Javadoc usage notes:

See Also:

Borrowed

Optional Element Summary

Optional Elements

Modifier and Type	Optional 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 = regionSpecification / 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:

""