com.amazon.carbonado

Annotation Type Join

@Documented
@Retention(value=RUNTIME)
@Target(value=METHOD)
public @interface Join

Identifies a Storable property as defining a join relationship with another Storable type. Joins can also refer to their own enclosing class or interface.

To complete the join, lists of internal and external properties may be supplied. If these lists are not supplied, then join is "natural", and the properties are determined automatically. When the lists are specified, the join is "explicit". Natural joins are merely a convenience; they can always be replaced by an explicit join.

The lists used for explicit joins must have the same length, and each must have at least one element. Each element in the internal list must refer to a property defined in this property's class or interface, and each element in the external list must refer to a matching property defined in the joined type. The matched up property pairs must not themselves be join properties, and they must be compatible with each other.

If the join is made to external properties which do not completely specify a primary key, then the type of the join property must be a Query of the joined type. When the type is a Query, a property mutator method cannot be defined. The returned query has all of the "with" parameters filled in.

With a natural join, the internal and external properties are deduced by examining the type of the referenced join property. If the type is a Query, then the internal and external properties are set to match this property's primary key. The referenced join property (specified as a parameterized type to Query) must have properties matching name and type of this property's primary key.

If a natural join's property type is not defined by a Query, then the internal and external properties are set to match the referenced property's primary key. This join property must have properties matching name and type of the referenced property's primary key.

Example:

 @PrimaryKey("addressID")
 public interface Address extends Storable {
     int getAddressID();

     ...
 }

 @PrimaryKey("userID")
 public interface UserInfo extends Storable {
     int getUserID();
     void setUserID(int id);

     int getAddressID();
     void setAddressID(int value);

     // Natural join, which works because Address has a primary key
     // property of addressID which matches a property in this type.
     @Join
     Address getAddress() throws FetchException;
     void setAddress(Address address);

     // Explicit join, equivalent to getAddress.
     @Join(internal="addressID", external="addressID")
     Address getCurrentAddress() throws FetchException;
     void setCurrentAddress(Address address);

     @Nullable
     Integer getParentID();
     void setParentID(Integer value);

     // Many-to-one relationship
     @Nullable
     @Join(internal="parentID", external="userID")
     UserInfo getParent() throws FetchException;
     void setParent(UserInfo parent);

     // One-to-many relationship
     @Join(internal="userID", external="parentID")
     Query<UserInfo> getChildren() throws FetchException;

     ...
 }
 

Author:

Brian S O'Neill

Optional Element Summary

Optional Elements

Modifier and Type	Optional Element and Description
java.lang.String[]	external List of property names defined in the foreign property's enclosing class or interface.
java.lang.String[]	internal List of property names defined in this property's enclosing class or interface.

Element Detail

internal

public abstract java.lang.String[] internal

List of property names defined in this property's enclosing class or interface.

Default:

{}

external

public abstract java.lang.String[] external

List of property names defined in the foreign property's enclosing class or interface.

Default:

{}