Using Java with Caché Jalapeño
Jalapeño Annotation Reference
[Back] [Next]
   
Server:docs1
Instance:LATEST
User:UnknownUser
 
-
Go to:
Search:    

The following sections describe annotations and related enumerated types in detail.

Annotations
This section lists all annotations in alphabetical order. Functionally, the annotations used by Jalapeño can be divided into two categories:
@Access
Restricts mapping of the generated Caché class to members with the specified access level and type. The following parameters are supported:
For example, the following annotation would restrict mapping to members of the class that are Public or Protected property accessors, excluding all Private members and any properties that do not have accessors:
  @Access(level=AccessLevel.PROTECTED,
    type=AccessType.PROPERTY)

For further information and examples, see Limiting Persisted Properties by Access Level and Limiting Persisted Properties by Access Type in Using Annotations.
@CacheClass
A class level annotation that provides additional information about the generated Caché class. The following parameters are supported:
For example:
  @CacheClass(name="Person",
    sqlTableName="PERSON",
    xmlSerializable=true)
  public class Person {

  {...}
@CacheProperty
A property level annotation that specifies the corresponding Caché property type and name, as well as the SQL column name. The following parameters are supported:
For example:
  @CacheProperty(name="VersionID")
  public int version_id;

For further information and examples, see Overriding Property Types in Using Annotations.
@ClassParameter
A class level annotation that defines a class parameter to be declared in the generated Caché class. The following parameters are supported:
For example, the following annotation:
  @ClassParameter(
    name="myParam"
    value="my param value")
generates the following declaration in the Caché class:
  Parameter myParam = "my param value";
Also see @Version, a property level annotation that defines class parameter VERSIONPROPERTY.
For further information and examples, see Adding Class Parameters in Using Annotations.
@ClassParameters
A class level annotation that declares multiple @ClassParameter values. The following parameter is supported:
For example, the following annotation:
  @ClassParameters({
    @ClassParameter(name="myParm1",value="snark"),
    @ClassParameter(name="myParm2",value="boojum")
  })
generates the following declarations in the Caché class:
  Parameter myParm1 = "snark";
  Parameter myParm2 = "boojum";
For further information and examples, see Adding Class Parameters in Using Annotations.
@Collection
A property level annotation that specifies the collection type (ARRAY or LIST) to be used for a property in the generated Caché class. In addition, you can specify the base type of the database collection. The following parameters are supported:
For example:
  @CacheProperty(name="FavoriteColors", SQLColumnName="FAVORITECOLORS")

  @Collection(type="ARRAY",elementType="%String")
    public ArrayList<String> favorite_colors;
Note that in the above example the base type of the collection can be inferred due to the use of Java generics, so the Collection annotation is not strictly necessary. On the other hand, should the field be defined as:
  public ArrayList favorite_colors;
use of the collection annotation (at least the base type portion of it) would be necessary.
@Embeddable
A class level annotation that adds superclass %Library.SerialObject to the generated class (required before class can be serial). The following parameter is supported:
For example:
  @Embeddable (accessType = AccessType.PROPERTY)
  public class Address
  {...}
For further information and examples, see Using @Embeddable in Using Annotations.
@Extends
A class level annotation that replaces the default superclass of the generated Caché Class. The following parameter is supported:
The default class is determined by the following rule:
For example:
  @Extends(className="bank1.Account")
For further information and examples, see Using @Extends in Using Annotations.
@ID
A property level annotation that declares a field to be an internal database ID. The following parameter is supported:
For example:
  @ID(type = IDType.SYSTEM_ASSIGNED)
  protected String idPlaceHolder;

Storing the database ID allows the save() method to determine whether it should insert a new object or update an existing one. For further discussion, see the information on the save() method in Creating or Updating an Object.
@Implements
A class level annotation that defines additional superclasses to be added to the generated Caché class. Such superclasses can inject additional functionality. Unlike the Java implements clause, additional superclasses can include actual implementations of the additional functionality. The following parameter is supported:
For example:
  @Implements({
    "%Library.Populate",
    "%Library.Utility"
  })
For further information and examples, see Using @Implements in Using Annotations.
@Index
A class level annotation that defines an index to be declared in the generated Caché class. Indices are used to improve the performance of database search operations. The following parameters are required:
The following parameters are also supported:
For example, given the following annotations:
  @Index(
    name="PersonIndexOne",
    propertyNames={"number","socialSecurity"},
    sqlName="AccountIOne"
  )
  public class Account
  {
    public long number;
    @CacheProperty(name="socialSecurity")
    public String social_security;
  ...}
the following lines are generated in the Caché class:
  Class bank1.Account Extends %Library.Persistent 
  [ SqlTableName = Account ]
  {
  Property number As %Library.Integer(JAVATYPE = "long");

  Property socialSecurity As %Library.String(JAVATYPE = "java.lang.String", 
                                             MAXLEN = 4096) 
  [ ClientName = social_security ];

  Index PersonIndexOne On (number, socialSecurity) 
  [ SqlName = AccountIOne ];
  ...}
For further information and examples, see Adding Indices in Using Annotations.
@Indices
A class level annotation that defines multiple indices to be declared in the generated Caché class. The following parameter is supported:
For example:
  @CacheClass(cacheName="Person",sqlTableName="PERSON")
  @Indices({
    @Index(name="IndexOnName",propertyNames={"Name"}),
    @Index(name="IndexOnSSN",propertyNames={"SSN"})
  })

  public class Person {
    @CacheProperty(sqlColumnName="NAME")
    public String name;

    @CacheProperty(name="SSN",sqlColumnName="SSN")
    public String social_security;
  ...}
For further information and examples, see Adding Indices in Using Annotations.
@Lob
A property level annotation that specifies that a given property should generate a LOB (large object or stream) property within the database class. The following parameters are supported:
There are two types of LOBs, BLOB (binary large object), and CLOB (character large object). Which to use depends on what type of data will be stored within the property.
This annotation is useful for POJO classes that have properties with types such as byte[], Character[], and String that you want to treat as streams within the database. At runtime, LOB-properties are lazy-loaded by default.
For example:
  @CacheProperty(name="LongString",type="%CharacterStream")
  @Lob(type="Clob")
  public String a_very_long_string;
@ManyToOne
A property level annotation specifying a many-to-one relationship that will be declared in the generated Caché class. The following parameters are supported:
For examples and further information, see Adding Relationships in Using Annotations.
@OneToMany
A property level annotation specifying a one-to-many relationship that will be declared in the generated Caché class. The following parameters are supported:
For examples and further information, see Adding Relationships in Using Annotations.
@PropertyParameter
A property level annotation that defines a property parameter (for example, MAXVAL, MINVAL, etc) to be added to the generated Caché class. The following parameters are supported:
For example:
  @PropertyParameter (name = "PATTERN", value = "3N1\"-\"2N1\"-\"4N")
  public String ssn;

  @PropertyParameter (name = "MINVAL", value = "0")
  public float balance;

  @PropertyParameter (name = "POPSPEC", 
                      value = "ValueList(\",checking,checking,saving,cd,money market\")")
  public String type;
For further information and examples, see Adding Property Parameters in Using Annotations.
@PropertyParameters
A property level annotation that declares multiple @PropertyParameter values. The following parameter is supported:
For example:
  @PropertyParameters ({
    @PropertyParameter(name = "PATTERN", value = "3N1\"-\"2N1\"-\"4N"),
    @PropertyParameter(name = "POPSPEC", value = "SSN()")
    })
  public String ssn;
For further information and examples, see Adding Property Parameters in Using Annotations.
@Relationship
Note:
This annotation is deprecated. Use @ManyToOne and @OneToMany instead.
A property level annotation that specifies relationships to be declared in the generated Caché class. Two types of relationships are supported: ONE_TO_MANY, and MANY_TO_ONE. Additionally, a relationship can be defined as a parent-child relationship. The following parameters are supported:
For example, consider two classes, Person and Dog. A Person can own any number of Dogs, but a Dog will have only one owner:
  // Person class
  @Relationship(type=RelationshipType.ONE_TO_MANY,inverseClass="Dog")
  public ArrayList<Dog> getDogs();

  // Dog class
  @Relationship(type=RelationshipType.MANY_TO_ONE,inverseClass="Person")
  public Person getOwner();
The type parameters define the one-to-many relationship. The inverseClass parameters specify that Person and Dog are the members of the relationship. The inverseProperty parameters define Person.getDogs() and Dog.getOwner() as the specific properties to be related.
The resulting Caché classes would contain the following entries:
  Class tinyproject.Person Extends %Library.Persistent
  [ SqlTableName = Person ]
  {
  Relationship getDog As Dog(JAVATYPE = "java.util.ArrayList") 
  [ Cardinality = many, Inverse = getOwner ];
  ...
  }

  Class tinyproject.Dog Extends (%Library.Persistent)
  [ SqlTableName = Dog ]
  {
  Relationship getOwner As Person(JAVATYPE = "tinyproject.Person") 
  [ Cardinality = one, Inverse = getDog ];
  ...
  }
Also see Adding Relationships in Using Annotations.
@Transient (class level)
When used as a class level annotation, @Transient specifies that the annotated class should not be persisted. This annotation does not take any parameters.
For example:
  @Transient
  public class LocalService {}
For further information and examples, see Preventing a Class or Property from being Persisted in Using Annotations.
@Transient (property level)
When used as a property level annotation, @Transient specifies that a property within the generated database class will not be stored within the database or accessible from SQL. This annotation can be used interchangeably with the Java transient keyword. This annotation does not take any parameters.
For example:
  @Transient
  public int age;
For further information and examples, see Preventing a Class or Property from being Persisted in Using Annotations.
@Version
A property level annotation that identifies a property used to hold version information for optimistic concurrency control (see Version Checking in Using Caché Objects). This annotation does not take any parameters.
@Version defines the Caché VERSIONPROPERTY class parameter. For example, the following declaration:
  @Version
  public int versionID;
generates the following lines in the Caché class:
  Parameter VERSIONPROPERTY As STRING = "versionID";
  Property versionID As %Library.Integer(JAVATYPE = "int");
Enumerated Types
These enumerations define the possible values for certain annotations.
AccessLevel
Specifies the access level for a generated persistent class. Used by the @Access annotation. The following values are defined:
AccessType
Specifies whether the mappings should be applied to fields or accessors. Used by the @Access and @Embeddable annotations. The following values are defined:
CollectionType
Specifies the collection type used for a property of a generated persistent class. Used by the @Collection annotation. The following values are defined:
IDType
Specifies the internal (database) ID type. Used by the @ID annotation. The following values are defined:
LobType
Specifies the type of LOB (large binary object) used for a stream/LOB property within a generated persistent class. Used by the @Lob annotation. The following values are defined:
FetchType
Specifies the strategy used for fetching object properties from the database. Used by the @Collection, @Lob, and @Relationship annotations. The following values are defined:
RelationshipType
This specifies the type of relationship used for used for a relationship property within a generated persistent class. Used by the @Relationship annotation. The following values are defined: