2 Annotation Extensions Reference

@AdditionalCriteria

Use @AdditionalCriteria to define parameterized views on data.

You can define additional criteria on entities or mapped superclass. When specified at the mapped superclass level, the additional criteria definition applies to all inheriting entities, unless those entities define their own additional criteria, in which case those defined for the mapped superclass are ignored.

Annotation Elements

Table 2-1 describes this annotation's elements.

Usage

Additional criteria can provide an additional filtering mechanism for queries. This filtering option, for example, allows you to use an existing additional JOIN expression defined for the entity or mapped superclass and allows you to pass parameters to it.

Set additional criteria parameters through properties on the entity manager factory or on the entity manager. Properties set on the entity manager override identically named properties set on the entity manager factory. Properties must be set on an entity manager before executing a query. Do not change the properties for the lifespan of the entity manager.

Examples

Specify additional criteria using the @AdditionalCriteria annotation or the <additional-criteria> element. The additional criteria definition supports any valid JPQL string and must use this as an alias to form the additional criteria. For example:

@AdditionalCriteria("this.address.city IS NOT NULL")

Example 2-1 shows additional criteria defined for the entity Employee and then shows the parameters for the additional criteria set on the entity manager.

package model;
 
@AdditionalCriteria("this.company=:COMPANY")
public class Employee {

  ...
}

entityManager.setProperty("COMPANY", "MyCompany");

Example 2-2 illustrates the same example as before, but uses the <additional-criteria> element in the eclipselink-orm.xml mapping file.

<additional-criteria>
  <criteria>this.address.city IS NOT NULL</criteria>
</additional-criteria>

Uses for Additional Criteria

Uses for additional criteria include:

• Multitenancy

• Soft Delete

• Data History

• Temporal Filtering

• Shared Table

Multitenancy

In a multitenancy environment, tenants (users, clients, organizations, applications) can share database tables, but the views on the data are restricted so that tenants have access only to their own data. You can use additional criteria to configure such restrictions.

@AdditionalCriteria("this.tenant = 'Billing'")

@AdditionalCriteria("this.tenant = :tenant")

When the tenant acquires its EntityManagerFactory or EntityManager, the persistence/entity manager property tenant is set to the name of the tenant acquiring it. For example,

Map properties = new HashMap();
properties.put("tenant", "ACME");
EntityManagerFactory emf = Persistence.createEntityManagerFactory(properties);

Or

Map properties = new HashMap();
properties.put("tenant", "ACME");
EntityManager em = factory.createEntityManager(properties);

Soft Delete

The following example filters data that is marked as deleted (but which still exists in the table) from a query:

@AdditionalCriteria("this.isDeleted = false")

Data History

The following example returns the current data from a query, thus filtering out any out-of-date data, for example data stored in a history table.

@AdditionalCriteria("this.endDate is null")

Temporal Filtering

The following example filters on a specific date:

@AdditionalCriteria("this.startDate <= :viewDate and this.endDate >= :viewDate")

Shared Table

For a shared table, there may be inheritance in the table but not in the object model. For example, a SavingsAccount class may be mapped to an ACCOUNT table, but the ACCOUNT table contains both savings account data (SAVINGS) and checking account (CHECKING) data. You can use additional criteria to filter out the checking account data.

See Also

For more information, see:

• "COLUMN"

• "@Multitenant"

@Array

Use @Array to define object-relational data types supported by specific databases, such as Oracle VARRAY types or PostgreSQL JDBC Array types.

Annotation Elements

Table 2-2 describes this annotation's elements.

Usage

Use @Array on a collection attribute that is persisted to an Array type. The collection can be of basic types or embeddable class mapped using a Struct.

Examples

Example 2-5 shows how to use this annotation with an Oracle VARRAY type.

VARRAY DDL:
CREATE TYPE TASKS_TYPE AS VARRAY(10) OF VARCHAR(100)

@Struct
@Entity
public class Employee {
    @Id
    private long id;
    @Array(databaseType="TASKS_TYPE")
    private List<String> tasks;
}

Example 2-6 shows how to use this annotation with an PostgreSQL Struct type.

DDL:
CREATE TABLE EMPLOYEE (ID BIGINT, TASKS TEXT[])

@Struct
@Entity
public class Employee {
    @Id
    private long id;
    @Array(databaseType="TEXT")
    private List<String> tasks;
}

See Also

For more information, see the following:

• "@Struct"

• Understanding EclipseLink

• Solutions Guide for EclispeLink

@BatchFetch

Use @BatchFetch to read objects related to a relationship mapping (such as @OneToOne, @OneToMany, @ManyToMany, and @ElementCollection) to be read in a single query.

Annotation Elements

Table 2-3 describes this annotation's elements.

Usage

Batch fetching allows for the optimal loading of a tree. Setting the @BatchFetch annotation on a child relationship of a tree structure causes EclipseLink to use a single SQL statement for each level. For example, consider an object with an EMPLOYEE and PHONE table in which PHONE has a foreign key to EMPLOYEE. By default, reading a list of employees' addresses by default requires n queries, for each employee's address. With batch fetching, you use one query for all the addresses.

Using BatchFetchType=EXISTS does not require an SQL DISTINCT statement (which may cause issues with LOBs) and may be more efficient for some types of queries or on specific databases.

When using BatchFetchType=IN, EclipseLink selects only objects not already in the cache. This method may work better with cursors or pagination, or in situations in which you cannot use a JOIN. On some databases, this may only work for singleton IDs.

Examples

The following examples show how to use this annotation (and XML) with different batch fetch types.

@OneToOne
@BatchFetch(BatchFetchType.JOIN)
private Address address;

<one-to-one name="address">
    <batch-fetch type="JOIN" />
</one-to-one>

 

@BatchFetch(BatchFetchType.EXISTS)
@OneToOne
public Map<String, String> getStringMap() {
return stringMap;
}

<one-to-one name="StringMap">
    <batch-fetch type="EXISTS"/>
</one-to-one>

@BatchFetch(BatchFetchType.IN, size=50)
@OneToOne
public Map<String, String> getStringMap() {
return stringMap;
}
 

<one-to-one name="StringMap">
    <batch-fetch type="IN" size="50" />
</one-to-one>

See Also

For more information, see:

• "@JoinFetch"

• Understanding EclipseLink

• Solutions Guide for EclispeLink

@Cache

Use @Cache (in place of the JPA @Cachable annotation) to configure the EclipseLink object cache. By default, EclipseLink uses a shared object cache to cache all objects. You can configure the caching type and options on a per class basis to allow optimal caching.

Annotation Elements

Table 2-4 describes this annotation's elements.

Usage

Use the @Cache annotation instead of the JPA @Cachable annotation to provide additional caching configuration.

You can define the @Cache annotation on the following:

• @Entity

• @MappedSuperclass

• the root of the inheritance hierarchy (if applicable)

If you define the @Cache annotation on an inheritance subclass, the annotation will be ignored. If you define the @Cache annotation on @Embeddable EclipseLink will throw an exception.

Caching in EclipseLink

The EclipseLink cache is an in-memory repository that stores recently read or written objects based on class and primary key values. EclipseLink uses the cache to do the following:

• Improve performance by holding recently read or written objects and accessing them in-memory to minimize database access.

• Manage locking and isolation level.

• Manage object identity.

For more information about the EclipseLink cache and its default behavior, see:

• Caching examples:

  http://wiki.eclipse.org/EclipseLink/Examples/JPA/Caching

EclipseLink defines the following entity caching annotations:

• @Cache

• @TimeOfDay

• @ExistenceChecking

EclipseLink also provides a number of persistence unit properties that you can specify to configure the cache. These properties may compliment or provide an alternative to the usage of annotations.

For more information, see "Caching".

Examples

Example 2-10 illustrates an @Cache annotation.

...
@Entity
@Cache(
  type=CacheType.SOFT, // Cache everything until the JVM decides memory is low.
  size=64000  // Use 64,000 as the initial cache size.
  expiry=36000000,  // 10 minutes
  coordinationType=CacheCoordinationType.INVALIDATE_CHANGED_OBJECTS  // if cache coordination is used, only send invalidation messages.
)
public class Employee {
  ...
} 

Example 2-11 shows how to use this annotation in the eclipselink-orm.xml file.

<entity-mappings
  xmlns="http://www.eclipse.org/eclipselink/xsds/persistence/orm"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://www.eclipse.org/eclipselink/xsds/persistence/orm 
  http://www.eclipse.org/eclipselink/xsds/eclipselink_orm_2_4.xsd"
  version="2.4">
    <entity name="Employee" class="org.acme.Employee" access="FIELD">
      <cache type="SOFT" size="64000" expiry="36000000" coordination-type="INVALIDATE_CHANGED_OBJECTS"/>
    </entity>
</entity-mappings>

You can also specify caching properties at the persistence unit level (in the persistence.xml file) as shown here:

<persistence xmlns="http://java.sun.com/xml/ns/persistence"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://java.sun.com/xml/ns/persistence persistence_2_0.xsd"
  version="2.0">
    <persistence-unit name="acme" transaction-type="RESOURCE_LOCAL">
      <provider>org.eclipse.persistence.jpa.PersistenceProvider</provider>
        <exclude-unlisted-classes>false</exclude-unlisted-classes>
        <properties>
          <property name="eclipselink.cache.shared.default" value="false"/>
          <property name="eclipselink.cache.shared.Employee" value="true"/>
          <property name="eclipselink.cache.type.Employee" value="SOFT"/>
          <property name="eclipselink.cache.size.Employee" value="64000"/>
        </properties>
    </persistence-unit>
</persistence>

See Also

For more information, see:

• "@ExistenceChecking"

• "@TimeOfDay"

• "@CacheInterceptor"

• "Understanding Caching" in the Understanding EclipseLink

• "Object Caching" in Solutions Guide for EclispeLink

• EclipseLink Caching examples: http://wiki.eclipse.org/EclipseLink/Examples/JPA/Caching

@CacheIndex

Use @CacheIndex to define a cached index. Cache indexes are used only when caching is enabled.

Annotation Elements

Table 2-5 describes this annotation's elements.

Usage

A cache index allows singleResult queries to obtain a cache hit when querying on the indexed fields. A resultList query cannot obtain cache hits, as it is unknown if all of the objects are in memory, (unless the cache usage query hint is used).

The index should be unique. If it is not, the first indexed object will be returned.

You can use @CacheIndex on an Entity class or on an attribute. The column is defaulted when defined on a attribute.

Examples

Example 2-13 shows an example of using the @CacheIndex annotation.

@Entity
@CacheIndex(columnNames={"F_NAME", "L_NAME"}, updateable=true)
public class Employee {
  @Id
  private long id;
  @CacheIndex
  private String ssn;
  @Column(name="F_NAME")
  private String firstName;
  @Column(name="L_NAME")
  private String lastName;
}

Example 2-14 shows an example of using the <cache-index> XML element in the eclipselink-orm.xml file.

<?xml version="1.0"?>
<entity-mappings
  xmlns="http://www.eclipse.org/eclipselink/xsds/persistence/orm"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://www.eclipse.org/eclipselink/xsds/persistence/orm http://www.eclipse.org/eclipselink/xsds/eclipselink_orm_2_4.xsd"
  version="2.4">
    <entity name="Employee" class="org.acme.Employee" access="FIELD">
        <cache-index updateable="true">
            <column-name>F_NAME</column-name>
            <column-name>L_NAME</column-name>
        </cache-index>
        <attributes>
            <id name="id"/>
            <basic name="ssn">
                <cache-index/>
            </basic>
            <basic name="firstName">
                <column name="F_NAME"/>
            </basic>
            <basic name="lastName">
                <column name="L_NAME"/>
            </basic>
        </attributes>
    </entity>
</entity-mappings>

Example 2-15 shows an example query using a cache index.

Query query = em.createQuery("Select e from Employee e where e.firstName = :firstName and e.lastName = :lastName");
query.setParameter("firstName", "Bob");
query.setParameter("lastName", "Smith");
Employee employee = (Employee)query.getSingleResult();

See Also

For more information, see:

• "@Cache"

• "About Cache Indexes" in Understanding EclipseLink

@CacheIndexes

Use @CacheIndexes to define a set of @CacheIndex on an entity.

Annotation Elements

Table 2-6 describes this annotation's elements.

Examples

See "@CacheIndex" for examples of using the @CacheIndexes annotation.

See Also

For more information, see:

• "@CacheIndex"

• "About Cache Indexes" in Understanding EclipseLink

@CacheInterceptor

Use @CacheInterceptor on an entity to intercept all EclipseLink cache access to the entity instead of responding to cache operations through an event.

Annotation Elements

Table 2-7 describes this annotation's elements.

Usage

Once set, the specified class will receive all caching calls. Existing EclipseLink cache settings will continue to be used, any calls allowed to continue to the EclipseLink cache will execute against the configured cache.

When using with an entity in inheritance, you should define the @CacheInterceptor on the root of the inheritance hierarchy.

Examples

Example 2-16 shows how to integrate an external cache with EclipseLink.

import oracle.eclipselink.coherence.integrated.cache.CoherenceInterceptor;
import org.eclipse.persistence.annotations.Customizer;
 
@Entity
@CacheInterceptor(value = CoherenceInterceptor.class)
public class Employee {
...
}

Example 2-17 shows an example of using the <cache-interceptor> XML element in the eclipselink-orm.xml file.

<entity class="Employee">
    <cache-interceptor class="CoherenceInterceptor"/>
...
</entity>

See Also

For more information, see:

• Understanding EclipseLink

• Oracle Coherence Integration Guide for EclipseLink with Coherence Grid

• "@Cache"

@CascadeOnDelete

Use the @CascadeOnDelete annotation to specify that a delete operation performed on a database object is cascaded on secondary or related tables.

ON DELETE CASCADE is a database foreign key constraint option that automatically removes the dependent rows.

Annotation Elements

There are no elements for this annotation.

Usage

You can place @CascadeOnDelete on any relationship in which the target is defined as foreign key to the source Entity.

Add the annotation on the source relationship: @OneToOne, @OneToMany, @ManyToMany, and @ElementCollection You can also add @CascadeOnDelete to an Entity with a @SecondaryTable or JOINED inheritance. Table 2-8 describes the affect of placing @CascadeOnDelete on these different elements

@CascadeOnDelete has the following behavior:

• DDL generation: If DDL generation is used, the generated constraint will include the cascade deletion option.

• Entity: Remove will not execute SQL for deletion from secondary or joined inheritance tables (as constraint will handle deletion).

• OneToOne: If the mapping uses cascading or orphanRemoval, SQL will not be executed to delete target object.

• OneToMany: If the mapping uses cascading or orphanRemoval, SQL will not be executed to delete target objects.

• ManyToMany: SQL will not be executed to delete from the join table.

• ElementCollection: SQL will not be executed to delete from the collection table.

• Cache: Cascaded objects will still be removed from the cache and persistence context.

• Version locking: Version will not be verified on deletion of cascaded object.

• Events: Deletion events may not be executed on the cascaded objects if the objects are not loaded.

• Cascading: The remove operation should still be configured to cascade in the mapping if using CascadeOnDelete.

Examples

Example 2-18 shows the cascading deletion of the Employee secondary table and all of its owned relationships.

@Entity
@SecondaryTable(name="EMP_SALARY")
@CascadeOnDelete
public class Employee{
    @Id
    private long id;
    private String firstName;
    private String lastName;
    @Column(table="EMP_SALARY")
    private String salary;
    @OneToOne(mappedBy="owner", orphanRemoval=true, cascade={CascadeType.ALL})
    @CascadeOnDelete
    private Address address;
    @OneToMany(mappedBy="owner", orphanRemoval=true, cascade={CascadeType.ALL})
    @CascadeOnDelete
    private List<Phone> phones;
    @ManyToMany
    @JoinTable(name="EMP_PROJ")
    @CascadeOnDelete
    private List<Project> projects;
    ...
}

In the eclipselink-orm.xml descriptor file, specify cascade on delete as shown in Example 2-19

...
<cascade-on-delete>true</cascade-on-delete>
...

See Also

For more information, see:

• EclipseLink example: http://wiki.eclipse.org/EclipseLink/Examples/JPA/DeleteCascade

• "@CascadeOnDelete"http://wiki.eclipse.org/EclipseLink/UserGuide/JPA/Advanced_JPA_Development/Schema_Generation/CascadeOnDelete

• "Enhancing Performance" in Solutions Guide for EclispeLink

@ChangeTracking

Use @ChangeTracking to specify the org.eclipse.persistence.descriptors.changetracking.ObjectChangePolicy. This policy computes change sets for the EclipseLink commit process and optimizes the transaction by including objects in the change set calculation that have at least one changed attribute.

Annotation Elements

Table 2-9 describes this annotation's elements.

Usage

Use this annotation to configure an alternative change policy, if the automatic policy is having issues with your application. Using @ChangeTracking may improve commit performance for objects with few attributes or objects with many changed attributes.

Examples

Example 2-20 shows how to use @ChangeTracking to set the unit of work's change policy.

@ChangeTracking(DEFERRED)
@Entity
public class Employee {
    ...
}

Example 2-21 shows how to use the <change-tracking> element in the eclipselink-orm.xml file.

<entity class="Employee"
    <change-tracking type="DEFERRED"/>
...
</entity>

Example 2-22 shows how to configure change tracking in the persistence unit persistence.xml file or by importing a property map.

<property name="eclipselink.weaving.changetracking" value="false"/>

import org.eclipse.persistence.config.PersistenceUnitProperties;
propertiesMap.put(PersistenceUnitProperties.WEAVING_CHANGE_TRACKING, "false");

See Also

For more information, see:

• "weaving"

• "Enhancing Performance" in Solutions Guide for EclispeLink

@ClassExtractor

Use @ClassExtractor to define a custom class indicator in place of providing a discriminator column.

Annotation Elements

Table 2-10 describes this annotation's elements.

Usage

If you are mapping to an existing database, and the tables do not have a discriminator column you can still define inheritance using the @ClassExtractor annotation or <class-extractor> element. The class extractor takes a class that implements the ClassExtractor interface. An instance of this class is used to determine the class type to use for a database row. The class extractor must define a extractClassFromRow method that takes the database Record and Session.

If a class extractor is used with SINGLE_TABLE inheritance, the rows of the class type must be able to be filtered in queries. This can be accomplished by setting an onlyInstancesExpression or withAllSubclassesExpression for branch classes. These can be set to Expression objects using a DescriptorCustomizer.

Examples

Example 2-23 shows an example of using ClassExtractor to define inheritance.

@Entity
@Table(name="MILES_ACCOUNT")
@Inheritance(strategy=InheritanceType.SINGLE_TABLE)
@ClassExtractor(AirMilesClassExtractor.class)
@Customizer(AirMilesCustomizer.class)
public class AirMilesAccount implements Serializable {
    @Id
    private Long id;
    @Basic
    private String totalMiles;
    @Basic
    private String milesBalance;
    ...
}
 
@Entity
@Customizer(PreferredCustomizer.class)
public class PreferredAccount extends AirMilesAccount {
    ...
}
 
public class AirMilesClassExtractor implements ClassExtractor {
    public void extractClassFromRow(Record row, Session session) {
        if (row.get("TOTALMILES").lessThan(100000)) {
            return AirMilesAccount.class;
        } else {
            return PreferredAccount.class;
        }
    }
}
 
public class AirMilesCustomizer implements DescriptorCustomizer {
    public void customize(ClassDescriptor descriptor) {
        ExpressionBuilder account = new ExpressionBuilder();
        Expression expression = account.getField("TOTALMILES").lessThan(100000);
        descriptor.getInheritancePolicy().setOnlyInstancesExpression(expression);
    }
}
 
public class PreferredCustomizer implements DescriptorCustomizer {
    public void customize(ClassDescriptor descriptor) {
        ExpressionBuilder account = new ExpressionBuilder();
        Expression expression = account.getField("TOTALMILES").greaterThanEqual(100000);
        descriptor.getInheritancePolicy().setOnlyInstancesExpression(expression);
    }
}

Example 2-24 shows how to use the <class-extractor> element in the eclipselink-orm.xml file.

<entity class="AirMilesAccount">
    <table name="MILES_ACCOUNT"/>
    <inheritance strategy="SINGLE_TABLE"/>
    <class-extractor class="AirMilesClassExtractor"/>
...
</entity>
 
<entity class="PreferredAccount">
    <customizer class="PreferredCustomizer"/>
...
</entity>

See Also

For more information, see:

• "Entities" in Understanding EclipseLink

• "@Customizer"

@CloneCopyPolicy

Use @CloneCopyPolicy to specify an org.eclipse.persistence.descriptors.copying.CloneCopyPolicy on an Entity.

Annotation Elements

Table 2-11 describes this annotation's elements.

Usage

The clone method should perform a shallow clone of the object. This can be used to clone non-persistent fields from a instance in the shared cache.

You can specify @CloneCopyPolicy on an Entity, MappedSuperclass, or Embeddable class.

Examples

Example 2-25 and Example 2-26 show several examples of the @CloneCopyPolicy annotation and <clone-copy-policy> XML element, respectively.

@CloneCopyPolicy(method="myClone")

@CloneCopyPolicy(method="myClone", workingCopyMethod="myWorkingCopyClone")

@CloneCopyPolicy(workingCopyMethod="myWorkingCopyClone")

<clone-copy-policy type="copy" method="myClone" workingCopyMethod="myWorkingCopyClone"/>

<clone-copy-policy type="copy" workingCopyMethod="myWorkingCopyClone"/>

<clone-copy-policy type="copy" method="myClone"/>
 

See Also

For more information, see:

• Understanding EclipseLink

• "@CopyPolicy"

• "@InstantiationCopyPolicy"

@CompositeMember

Use @CompositeMember to indicate that a class belongs to a composite persistence unit.

It should be used if target type is a primitive type and @CollectionTable designates the table that belongs to composite member persistence unit other than the source composite member persistence unit. This allows the source and target to be mapped to different databases.

Annotation Elements

Table 2-12 describes this annotation's elements.

Usage

The @CompositeMember annotation is ignored unless it is in a composite member persistence unit. It may be used in conjunction with @ElementCollection and @CollectionTable annotations.

Examples

You can configure the CompositeMember using annotations or the eclipselink-orm.xml file, as shown in these examples.

@ElementCollection()
@CollectionTable(name = "MBR1_RESPONS", joinColumns=@JoinColumn(name="EMP_ID"))
@CompositeMember("branch-database")
@Column(name = "DESCRIPTION")
public Collection<String> getResponsibilities() {
    return responsibilities;
}

<element-collection name="responsibilities" composite-member="branch-database">
  <column name="DESCRIPTION"/>
  <collection-table name="XML_MBR3_RESPONS">
    <join-column name="EMP_ID"/>
  </collection-table>
</element-collection>

See Also

For more information, see:

• "Using Multiple Databases with a Composite Persistence Unit" in Solutions Guide for EclispeLink

• "composite-unit"

• "composite-unit.member"

• "Composite Persistence Units" http://wiki.eclipse.org/EclipseLink/UserGuide/JPA/Advanced_JPA_Development/Composite_Persistence_Units

@ConversionValue

Use @ConversionValue to specify the database and object values for an ObjectTypeConverter.

Annotation Elements

Table 2-13 describes this annotation's elements.

Usage

The JPA specification allows you to map an Enum to database columns using the @Enumerated annotation, when the database value is either the name of the Enum or its ordinal value. With EclipseLink, you can also map an Enum to a coded value, using a converter.

Examples

In Example 2-29, the enum Gender(MALE, FEMALE) is mapped to a single character in the database where M=MALE and F=FEMALE.

@ObjectTypeConverter(name = "gender", objectType = Gender.class, dataType = String.class, conversionValues = {
  @ConversionValue(objectValue = "Male", dataValue = "M"),
  @ConversionValue(objectValue = "Female", dataValue = "F") })

...

@Basic
@Convert("gender")
private Gender gender = Gender.Male;

Example 2-30 illustrates the same function using XML.

<object-type-converter name="gender" object-type="model.Gender   "data-type="java.lang.String">
  <conversion-value object-value="Male" data-value="M" />
  <conversion-value object-value="Female" data-value="F" />
</object-type-converter>

...

<basic name="gender">
  <column name="GENDER" />
  <convert>gender</convert>
</basic>

See Also

For more information, see:

• "@ObjectTypeConverter"

• Understanding EclipseLink

@Convert

Use @Convert to specify that a named converter should be used with the corresponding mapped attribute.

Annotation Elements

Table 2-14 describes this annotation's elements.

Usage

The @Convert has the following reserved names:

• serialized – Places the org.eclipse.persistence.mappings.converters.SerializedObjectConverter on the associated mapping.

• class-instance – Uses an ClassInstanceConverter on the associated mapping. When using a ClassInstanceConverter, the database representation is a String representing the Class name and the object-model representation is an instance of that class built with a no-args constructor

• none – Does not place a converter on the associated mapping.

Examples

Example 2-31 shows how to use the @Convert annotation to define the gender field.

@Entity
 @Table(name="EMPLOYEE")
 @Converter(
     name="genderConverter",
         converterClass=org.myorg.converters.GenderConverter.class
 )
 public class Employee implements Serializable{
     ...
     @Basic
     @Convert("genderConverter")
     public String getGender() {
         return gender;
     }
     ...
 }

See Also

For more information, see:

• "@Converter"

• "@ObjectTypeConverter"

• "@TypeConverter"

• Understanding EclipseLink

@Converter

Use the @Converter annotation to specify a custom converter for modification of the data value(s) during the reading and writing of a mapped attribute.

Annotation Elements

Table 2-15 describes this annotation's elements.

Usage

Use @Converter to define a named converter that can be used with mappings. A converter can be defined on an entity class, method, or field. Specify a converter with the @Convert annotation on a Basic or ElementCollection mapping.

Using non-JPA Converter Annotations

EclipseLink provides a set of non-JPA converter annotations (in addition to the JPA default type mappings):

• @Converter

• @TypeConverter

• @ObjectTypeConverter

• @StructConverter

• @Convert

The persistence provider searches the converter annotations in the following order:

1. @Convert

2. @Enumerated

3. @Lob

4. @Temporal

5. Serialized (automatic)

Specify the converters on the following classes:

• @Entity

• @MappedSuperclass

• @Embeddable

Use the converters with the following mappings:

• @Basic

• @Id

• @Version

• @ElementCollection

An exception is thrown if a converter is specified with any other type of mapping annotation.

Examples

Example 2-32 shows how to use the @Converter annotation to specify a converter class for the gender field.

@Entity
 public class Employee implements Serializable{
    ...
     @Basic
     @Converter (
         name="genderConverter",
         converterClass=org.myorg.converters.GenderConverter.class
     )
     @Convert("genderConverter")
     public String getGender() {
         return gender;
     }
     ...
 }

Example 2-33 shows how to use the <converter> element in the eclipselink-orm.xml file.

<entity class="Employee">
...
    <attributes>
    ...
      <basic name="gender">
        <convert>genderConverter</convert>
        <converter name="genderConverter" class="org.myorg.converters.GenderConverter"/>
      </basic>
    ...
    </attributes>
</entity>

See Also

For more information, see:

• "@Converters"

• "@Convert"

• "@MapKeyConvert"

• Understanding EclipseLink

@Converters

Use @Converters annotation to define multiple @Converter elements.

Annotation Elements

Table 2-16 describes this annotation's elements.

Examples

See "@Converter" for an example of this annotation.

See Also

For more information, see:

• "@Converter"

• Understanding EclipseLink

@CopyPolicy

Use @CopyPolicy to set an org.eclipse.persistence.descriptors.copying.CopyPolicy on an entity to produce a copy of the persistent element.

Annotation Elements

Table 2-17 describes this annotation's elements.

Usage

You can specify @CopyPolicy on an Entity, MappedSuperclass, or Embeddable class.

Examples

Example 2-34 shows how to use this annotation.

@Entity
  @Table(name="EMPLOYEE")
  @CopyPolicy(mypackage.MyCopyPolicy.class)
  public class Employee implements Serializable {
    ...
  }

Example 2-35 shows how to use the <copy-policy> element in the eclipselink-orm.xml file.

<entity class="Employee">
  <table name="EMPLOYEE"/>
  <copy-policy class="mypackage.MyCopyPolicy"/>
...
</entity>

See Also

For more information, see:

• "@CloneCopyPolicy"

• "@InstantiationCopyPolicy"

• Understanding EclipseLink

@Customizer

Use @Customizer to specify a class that implements org.eclipse.persistence.config.DescriptorCustomizer and is to run against an entity's class descriptor after all metadata processing has been completed.

Annotation Elements

Table 2-18 describes this annotation's elements.

Usage

Use this annotation to customize or extend the mapping metadata through the EclipseLink native API. With @Customizer, you can access additional EclipseLink functionality and configurations.

You can specify @Customizer on an Entity, MappedSuperclass, or Embeddable class.

Examples

Example 2-36 show how to use the @Customizer annotation with the following DescriptorCustomer:

public class MyCustomizer implements DescriptorCustomizer {
  public void customize(ClassDescriptor descriptor) {
    DirectToFieldMapping genderMapping = (DirectToFieldMapping)descriptor.getMappingForAttributeName("gender");
    ObjectTypeConverter converter = new ObjectTypeConverter();
    convert.addConversionValue("M", Gender.MALE);
    convert.addConversionValue("F", Gender.FEMALE);
    genderMapping.setConverter(converter);
  }
}

@Entity
 @Table(name="EMPLOYEE")
 @Customizer(mypackage.MyCustomizer.class)
 public class Employee implements Serializable {
     ...
 }

Example 2-37 show how to use the <customizer> element in the eclipselink-orm.xml file.

<entity class="Employee">
  <table name="EMPLOYEE"/>
  <customizer class="mypackage.MyCustomizer"/>
...
</entity>

See Also

For more information, see:

• "descriptor.customizer"

• "Binding JPA Entities to XML" in Solutions Guide for EclispeLink

• EclipseLink Examples http://wiki.eclipse.org/EclipseLink/Examples/JPA/MappingSelectionCriteria

• "Customizers" http://wiki.eclipse.org/EclipseLink/UserGuide/JPA/Advanced_JPA_Development/Customizers

@DeleteAll

Use @DeleteAll to indicate that when an relationship is deleted, EclipseLink should use a delete all query. This typically happens if the relationship is PrivateOwned and its owner is deleted. In that case, the members of the relationship will be deleted without reading them in.

Annotation Elements

There are no elements for this annotation.

Usage

Examples

Example 2-38 shows how to use @DeleteAll on a relationship mapping.

@Entity
public class Department {
  ...
  @OneToMany(mappedBy = "department")
  @PrivateOwned
  @DeleteAll
  public List<Equipment> getEquipment() {
    return equipment;
    }
  ...
  }
 

Example 2-38 shows how to use the <delete-all> element in the eclipselink-orm.xml file.

<entity class="Department">
  ...
  <attributes>
    <one-to-many name="equipment" target-entity="Equipment" mapped-by="department">
      <private-owned/>
      <delete-all/>
    </one-to-many>
...
</attributes>
</entity>

See Also

For more information, see:

• "@PrivateOwned"

@DiscriminatorClass

Use @DiscriminatorClass with a @VariableOneToOne annotation to determine which entities will be added to the list of types for the mapping.

Annotation Elements

Table 2-19 describes this annotation's elements.

Usage

The @DiscriminatorClass annotation can be specified only within a @VariableOneToOne mapping.

Examples

See "@VariableOneToOne" for an example of a variable one-to-one mapping with @DiscriminatorClass.

See Also

For more information, see:

• "@VariableOneToOne"

• Understanding EclipseLink

@ExcludeDefaultMappings

Use @ExcludeDefaultMappings to specify that no default mapping should be added to a specific class. Instead, EclipseLink will use only mappings that are explicitly defined by annotations or the XML mapping file.

Annotation Elements

There are no elements for this annotation.

Usage

You can specify @ExcludeDefaultMappings on an Entity, MappedSuperclass, or Embeddable class.

Examples

Example 2-40 shows how to use the @ExcludeDefaultMapping annotation.

@ExcludeDefaultMappings
@Entity
public class Dealer {
    @Id
    private long id;
    @Basic
    private String name;
    // These would be ignored
    private List<Card> deck;
    private List<Card> hand;
    ...
}

See Also

For more information, see:

• "Building Blocks for a EclipseLink Project" in Understanding EclipseLink

@ExistenceChecking

Use @ExistenceChecking to specify how EclipseLink should check to determine if an entity is new or exists.

On merge() operations, use @ExistenceChecking to specify if EclipseLink uses only the cache to determine if an object exists, or if the object should be read (from the database or cache). By default the object will be read from the database.

Annotation Elements

Table 2-20 describes this annotation's elements.

Usage

You can specify @ExistenceChecking on an Entity or MappedSuperclass.

EclipseLink supports the following existence checking types:

• ASSUME_EXISTENCE – If the object's primary key does not include null then it must exist. You may use this option if the application guarantees or does not care about the existence check.

• ASSUME_NON_EXISTENCE – Assume that the object does not exist. You may use this option if the application guarantees or does not care about the existence check. This will always force an INSERT operation.

• CHECK_CHACHE – If the object's primary key does not include null and it is in the cache, then it must exist.

• CHECK_DATABASE – Perform a SELECT on the database.

Examples

Example 2-41 shows how to use this annotation.

@Entity
@Cache(type=CacheType.HARD_WEAK,  expiryTimeOfDay=@TimeOfDay(hour=1))
@ExistenceChecking(ExistenceType.CHECK_DATABASE)
public  class  Employee  implements  Serializable  { 
...
}

See Also

For more information, see:

• "@Cache"

• "Enhancing Performance" in Solutions Guide for EclispeLink

@FetchAttribute

Use @FetchAttribute to improve performance within a fetch group; it allows on-demand loading of a group of an object's attributes. As a result, the data for an attribute might not be loaded from the datasource until an explicit access call occurs.

This avoids loading all the data of an object's attributes if the user requires only some of the attributes.

Annotation Elements

Table 2-21 describes this annotation's elements.

Usage

EclipseLink provides two types of fetch groups:

• Pre-defined fetch groups at the Entity or MappedSuperclass level

• Dynamic (use case) fetch groups at the query level

You should extensively review your use cases when using fetch groups. In many cases, additional round-trips will offset any gains from deferred loading.

Examples

Example 2-42 shows how to use @FetchAttribute within a @FetchGroup annotation.

@Entity
@FetchGroup(name="basic-fetch-group", attributes={
        @FetchAttribute(name="id"), 
        @FetchAttribute(name="name"),
        @FetchAttribute(name="address")}) 
public class Person {
 
   @Id
   private int id;
 
   private String name;
 
   @OneToOne(fetch=LAZY)
   private Address address;
 
   @ManyToOne(fetch=EAGER)
   private ContactInfo contactInfo;

<fetch-group name="basic-fetch-group">
    <attribute name="id"/>
    <attribute name="name"/>
    <attribute name="address"/>
</fetch-group>

See Also

For more information, see:

• Understanding EclipseLink

• "@FetchGroup"

@FetchGroup

Use @FetchGroup to load a group of attributes on demand, as needed.

This avoids wasteful practice of loading all data of the object's attributes, if the user is interested in only partial of them. However, it also means that the data for an attribute might not be loaded from the underlying data source until an explicit access call for the attribute first occurs.

Annotation Elements

Table 2-22 describes this annotation's elements.

Usage

You should perform a careful use case analysis when using @FetchGroup; any gains realized from the deferred loading could be offset by the extra round-trip.

EclipseLink supports fetch groups at two levels:

• Pre-defined fetch groups at the Entity or MappedSuperclass level

• Dynamic (use case) fetch groups at the query level

You can use fetch groups only when using weaving or when individual classes that define them explicitly implement the org.eclipse.persistence.queries.FetchGroupTracker interface.

When using a fetch group, you can define a subset of an object's attributes and associate the fetch group with a query. When you execute the query, EclipseLink retrieves only the attributes in the fetch group. EclipseLink automatically executes a query to fetch all the attributes excluded from this subset when and if you call a get method on any one of the excluded attributes.

You can define more than one fetch group for a class. You can optionally designate at most one such fetch group as the default fetch group. If you execute a query without specifying a fetch group, EclipseLink will use the default fetch group, unless you configure the query otherwise.

Before using fetch groups, it is recommended that you perform a careful analysis of system use. In many cases, the extra queries required to load attributes not in the fetch group could well offset the gain from the partial attribute loading.

Examples

Example 2-44 shows how to use this annotation.

@FetchGroup(name="names", attributes={
    @FetchAttribute(name="firstName"), 
    @FetchAttribute(name="lastName")})

Example 2-45 shows how to use this feature in the eclipselink-orm.xml file.

<entity class="model.Employee">
    <secondary-table name="SALARY" />
    <fetch-group name="names">
        <attribute name="firstName" />
        <attribute name="lastName" />
    </fetch-group>
...

You can also use a named fetch group with a query, as shown in Example 2-46.

TypedQuery query = em.createQuery("SELECT e FROM Employee e", Employee.class);
 
query.setHint(QueryHints.FETCH_GROUP_NAME, "names");

See Also

For more information, see:

• Understanding EclipseLink

• "@FetchAttribute"

• "@FetchGroups"

@FetchGroups

Use @FetchGroups to define a group of @FetchGroup.

Annotation Elements

Table 2-23 describes this annotation's elements.

Usage

You can specify @FetchGroups on an Entity or MappedSuperclass.

You can also enable or disable fetch groups through weaving for the persistence unit.

Examples

See "@FetchGroup" for an example of using fetch groups.

Example 2-47 shows how to configure fetch groups in the persistence unit persistence.xml file or by importing a property map.

<property name="eclipselink.weaving.fetchgroups" value="false"/>

import org.eclipse.persistence.config.PersistenceUnitProperties;
propertiesMap.put(PersistenceUnitProperties.WEAVING_FETCHGROUPS, "false");

See Also

For more information, see:

• "@FetchGroup"

• "@FetchAttribute"

• "weaving"

@Field

Use @Field to define a structured data type's field name for an object mapped to NoSql data.

Annotation Elements

Table 2-24 describes this annotation's elements.

Usage

The @Field annotation is a generic form of the @Column annotation, which is not specific to relational databases. You can use @Field to map EIS and NoSQL data.

Examples

See "@NoSql" for an example of the @Field annotation.

See Also

For more information, see:

• "@NoSql"

@HashPartitioning

Use @HashPartitioning to partition access to a database cluster by the hash of a field value from the object (such as the object's location or tenant). The hash indexes into the list of connection pools.

Annotation Elements

Table 2-25 describes this annotation's elements.

Usage

All write or read requests for objects with the hash value are sent to the server. Queries that do not include the field as a parameter will be:

• Sent to all servers and unioned

  or

• Handled based on the session's default behavior.

You can enable partitioning on an Entity, relationship, query, or session/persistence unit. Partition policies are globally named (to allow reuse) and must set using the @Partitioned annotation.

The persistence unit properties support adding named connection pools in addition to the existing configuration for read/write/sequence. A named connection pool must be defined for each node in the database cluster.

If a transaction modifies data from multiple partitions, you should use JTA to ensure proper two-phase commit of the data. You can also configure an exclusive connection in the EntityManager to ensure that only a single node is used for a single transaction.

Examples

See "@Partitioned" for an example of partitioning with EclipseLink.

See Also

For more information, see:

• "Data Partitioning"http://wiki.eclipse.org/EclipseLink/UserGuide/JPA/Advanced_JPA_Development/Data_Partitioning

• "@Partitioned"

@Index

An index is a database structure defined for a table, to improve query and look-up performance for a set of columns. Use the @Index annotation in code or the <index> element in the eclipselink-orm.xml descriptor to create an index on a table.

An index can be defined on an entity or on an attribute. For the entity it must define a set of columns to index.

Index creation is database specific. Some databases may not support indexes. Most databases auto-index primary key and foreign key columns. Some databases support advanced index DDL options. To create more advanced index DDL, a DDL script or native query can be used.

Annotation Elements

Table 2-26 describes this annotation's elements.

Usage

Use @Index annotation to index any attributes or columns that will commonly be used in queries.

Examples

This example defines three indexes, one on first name, one on last name, and a multiple column index on first name and last name.

@Entity
@Index(name="EMP_NAME_INDEX", columns={"F_NAME","L_NAME"})
public class Employee{
    @Id
    private long id;
    @Index
    @Column(name="F_NAME")
    private String firstName;
    @Index
    @Column(name="L_NAME")
    private String lastName;
    ...
}

You can also create an index in the eclipselink-orm.xml descriptor using <index>, as shown in the following example. Define columns using the <column> subelement. All the attributes supported in the @Index annotation are also supported in the <index> element.

<index name="EMP_NAME_INDEX" table="EMPLOYEE" unique="true">
    <column>F_NAME</column>
    <column>L_NAME</column>
</index>

See Also

For more information see:

• "@Indexes"

@Indexes

Use @Indexes to define a set of database indexes for an Entity.

Annotation Elements

Table 2-27 describes this annotation's elements.

Examples

See "@Index" for an example of using the @Index annotation.

See Also

For more information see:

• "@CopyPolicy"

• "@CloneCopyPolicy"

• "@Index"

@InstantiationCopyPolicy

Use @InstantiationCopyPolicy to set an org.eclipse.persistence.descriptors.copying.InstantiationCopyPolicy on an Entity.

Annotation Elements

There are no elements for this annotation.

Usage

The copy policy specifies how EclipseLink clones objects to and from the shared cache. With @InstantiationCopyPolicy, in order to clone an object EclipseLink will create a new instance of the object and copy each persistent attribute. Alternative methods include @CloneCopyPolicy, which clones the object.

Cloning is more efficient than creating a new instance and maintains transient or non-persistent attribute values. If you do not need transient or non-persistent attribute values in the shared cache, then use @InstantiationCopyPolicy.

The default EclipseLink copy policy depends on your configuration:

• When using weaving.internal (and field access), EclipseLink generates a specialized clone method to copy objects.

• Without weaving, EclipseLink uses instantiation to copy objects.

You can specify @InstantiationCopyPolicy on an Entity, MappedSuperclass, or Embeddable entity.

Examples

Example 2-50 shows how to use this annotation.

@Entity
@InstantiationCopyPolicy
public class Employee {
    ...
    transient List events = new ArrayList();
}

Example 2-51 shows how to use this extension in the eclipselink-orm.xml file.

<entity name="Employee" class="org.acme.Employee" access="FIELD">
    <instantiation-copy-policy/>
    ...
</entity>

See Also

For more information, see:

• "@CopyPolicy"

• "@CloneCopyPolicy"

• "weaving.internal"

@JoinFetch

Use the @JoinFetch annotation to enable the joining and reading of the related objects in the same query as the source object.

Annotation Elements

Table 2-28 describes this annotation's elements.

Usage

You can specify the @JoinFetch annotation for the following mappings:

• @OneToOne

• @OneToMany

• @ManyToOne

• @ManyToMany

• @ElementCollection

Alternatively, you can use batch fetching which is more efficient, especially for collection relationships.

Examples

The following example shows how to use the @JoinFetch annotation to specify Employee field managedEmployees.

@Entity
 public class Employee implements Serializable {
    ...
    @OneToMany(cascade=ALL, mappedBy="owner")
    @JoinFetch(value=OUTER)
    public Collection<Employee> getManagedEmployees() {
        return managedEmployees;
    }
    ...
 }

Example 2-53 shows how to use this extension in the eclipselink-orm.xml file.

<one-to-many name="managedEmployees">
    <join-fetch>OUTER</join-fetch>
</one-to-many>

See Also

For more information, see:

• Understanding EclipseLink

• "Enhancing Performance" in Solutions Guide for EclispeLink

• "@BatchFetch"

@JoinField

Use @JoinField to define a structured data type's foreign key field for an object mapped to NoSql data.

Annotation Elements

Table 2-29 describes this annotation's elements.

Usage

The @JoinField annotation is a generic form of the @JoinColumn annotation, which is not specific to relational databases. You can use @JoinField to map EIS and NoSQL data.

Examples

These examples show how to use this extension as an annotation and in XML.

@Entity
@NoSql
public class Order {
    ...
    @ManyToOne
    @JoinField(name="customerId")
    private Customer customer;
}

<entity name="Order" class="org.acme.Order">
    <no-sql/>
    ...
    <many-to-one name="customer">
        <join-field name="customerId"/>
    </many-to-one>
</entity>

See Also

For more information, see:

• "Mappings"http://wiki.eclipse.org/EclipseLink/UserGuide/JPA/Advanced_JPA_Development/NoSQL/Mappings

• "@JoinFields"

@JoinFields

Use @JoinFields to define a set of @JoinField annotations on a relationship.

Annotation Elements

Table 2-30 describes this annotation's elements.

Examples

See "@JoinField" for an example of using the @Index annotation.

See Also

For more information, see:

• "@JoinField"

@MapKeyConvert

Use @MapKeyConvert to specify a named converter to be used with the corresponding mapped attribute key column.

Annotation Elements

Table 2-31 describes this annotation's elements.

Usage

Use @MapKeyConvert to convert the key value used in a @MapKeyColumn to have a different type or value than the database column.

The @MapKeyConvert annotation has the following reserved names:

• serialized: Will use a SerializedObjectConverter on the associated mapping. When using a SerializedObjectConverter the database representation is a binary field holding a serialized version of the object and the object-model representation is a the actual object

• class-instance: Will use an ClassInstanceConverter on the associated mapping. When using a ClassInstanceConverter the database representation is a String representing the Class name and the object-model representation is an instance of that class built with a no-args constructor

• none - Will place no converter on the associated mapping. This can be used to override a situation where either another converter is defaulted or another converter is set.

If you do not use one of these reserved names, you must define a custom converter, using the @Converter annotation.

Examples

Example 2-56 shows using a @MapKeyConvert annotation to apply a converter to a map's key.

@Entity
public class Entity
 …
    @ElementCollection
    @MapKeyColumn(name=”BANK”)
    @Column(name=”ACCOUNT”)
    @Convert(”Long2String”)
    @MapKeyConvert(”CreditLine”)
    public Map<String,Long> getCreditLines() {
        return creditLines;
    }

Example 2-57 shows how to use the <map-key-convert> element in the eclipselink-orm.xml file.

<element-collection name="creditLines">
  <map-key-convert>CreditLine</map-key-convert>
  <map-key-column name="BANK"/>
  <column name="ACCOUNT"/>
  <convert>Long2String</convert>
  <object-type-converter name="CreditLine">
    <conversion-value data-value="RBC" object-value="RoyalBank"/>
    <conversion-value data-value="CIBC" object-value="CanadianImperial"/>
    <conversion-value data-value="SB" object-value="Scotiabank"/>
    <conversion-value data-value="TD" object-value="TorontoDominion"/>
  </object-type-converter>
  <type-converter name="Long2String" data-type="String" object-type="Long"/>
  <collection-table name="EMP_CREDITLINES">
    <join-column name="EMP_ID"/>
  </collection-table>
</element-collection>

See Also

For more information, see:

• "@Converter"

• "@Convert"

@Multitenant

The @Multitenant annotation specifies that a given entity is shared among multiple tenants of an application. The multitenant type specifies how the data for these entities are to be stored on the database for each tenant. Multitenancy can be specified at the entity or mapped superclass level.

Annotation Elements

Table 2-32 describes this annotation's elements.

Usage

To use the @Multitenant annotation, include the annotation with an @Entity or @MappedSuperclass annotation. For example:

@Entity
@Multitenant
...
public class Employee() {
  ...
}
 

Three types of multitenancy are available:

• Single-Table Multitenancy

• Table-Per-Tenanat Multitenancy

• VPD Multitenancy

Example

Example 2-58 shows a simple example of a @Multitenant annotation. In this example, the Player entity has rows for multiple tenants stored in its default PLAYER table and that the default TENANT_ID column is used as a discriminator along with the default context property eclipselink.tenant-id.

@Entity
@Multitenant
public class Player  {
}

Map<String, Object> emProperties = new HashMap<String, Object>();

emProperties.set("eclipselink.tenant-id", "HTHL");

EntityManager em = emf.createEntityManager(emProperties);

Review "Single-Table Multitenancy", "Table-Per-Tenanat Multitenancy", and "VPD Multitenancy" for more detailed examples.

Single-Table Multitenancy

The SINGLE_TABLE multitenant type specifies that any table to which an entity or mapped superclass maps can include rows for multiple tenants. Access to tenant-specific rows is restricted to the tenant.

Tenant-specific rows are associated with the tenant by using tenant discriminator columns. The discriminator columns are used with application context values to limit what a persistence context can access.

The results of queries on the mapped tables are limited to the tenant discriminator value(s) provided as property values. This applies to all insert, update, and delete operations on the table. When multitenant metadata is applied at the mapped superclass level, it is applied to all subentities unless they specify their own multitenant metadata.

For more information how to use tenant discriminator columns to configure single-table multitenancy, see "@TenantDiscriminatorColumn".

Examples

The following example uses @Multitenant, @TenantDiscriminatorColumn, and a context property to define single-table multitenancy on an entity:

@Entity 
@Table(name=”EMP”) 
@Multitenant(SINGLE_TABLE) 
@TenantDiscriminatorColumn(name = ”TENANT_ID”, 
   contextProperty = "employee-tenant.id")

The following example uses the <multitenant> element to specify a minimal single-table multitenancy. SINGLE_TABLE is the default value and therefore does not have to be specified.

<entity class="model.Employee">
  <multitenant/>
  <table name="EMP"/>
  ...
</entity>

Table-Per-Tenanat Multitenancy

The TABLE_PER_TENANT multitenant type specifies that the table(s) (Table and SecondaryTable) for an entity are tenant-specific tables based on the tenant context.. Access to these tables is restricted to the specified tenant. Relationships within an entity that use a join or collection table are also assumed to exist within that context.

As with other multitenant types, table-per-tenant multitenancy can be specified at the entity or mapped superclass level. At the entity level, a tenant context property must be provided on each entity manager after a transaction has started.

Table-per-tenant entities can be mixed with other multitenant-type entities within the same persistence unit.

All read, insert, update, and delete operations for the tenant apply only to the tenant's table(s).

Tenants share the same server session by default. The table-per-tenant identifier must be set or updated for each entity manager. ID generation is assumed to be unique across all the tenants in a table-per-tenant strategy.

To configure table-per-tenant multitenancy, you must specify:

• A table-per-tenant property to identify the user. This can be set per entity manager, or it can be set at the entity manager factory to isolate table-per-tenant per persistence unit.)

• A tenant table discriminator to identify and isolate the tenant's tables from other tenants' tables. The discriminator types are SCHEMA, SUFFIX, and PREFIX. For more information about tenant discriminator types, see "@TenantTableDiscriminator".

Examples

The following example shows the @Multitenant annotation used to define table-per-tenant multitenancy on an entity. @TenantTableDiscriminator(SCHEMA) specifies that the discriminator table is identified by schema.

@Entity
@Table(name=”EMP”)
@Multitenant(TABLE_PER_TENANT)
@TenantTableDiscriminator(SCHEMA)
public class Employee {
    ...
}

The following example shows the <multitenant> element and the <tenant-table-discriminator> elements used to define a minimal table-per-tenant multitenancy.

<entity class="Employee">
  <multitenant type="TABLE_PER_TENANT">
    <tenant-table-discriminator type="SCHEMA"/>
  </multitenant>
  <table name="EMP">
  ...
</entity>

VPD Multitenancy

The VPD (Virtual Private Database) multitanancy type specifies that the database handles the tenant filtering on all SELECT, UPDATE and DELETE queries. To use this type, the platform used with the persistence unit must support VPD.

To use EclipseLink VPD multitenancy, you must first configure VPD in the database and then specify multitenancy on the entity or mapped superclass, using @Multitenant and @TenantDiscriminatorColumn:

Examples

Example 2-63 shows VPD multitenancy defined on an entity. As noted above, VPD in the database must also be configured to enable VPD multitenancy. In this case, the VPD database was configured to use the USER_ID column to restrict access to specified rows by specified clients. Therefore, USER_ID is also specified as the tenant discriminator column for the EclipseLink multitenant operations.

@Entity
@Multitenant(VPD)
@TenantDiscriminatorColumn(name = "USER_ID", contextProperty = "tenant.id")
@Cacheable(false)
 
public class Task implements Serializable {
...
...

The following example shows...

<entity class="model.Employee"> 
  <multitenant type="VPD">
    <tenant-discriminator-column name="USER_ID" context-property="tenant.id"/> 
  </multitenant>
  <table name="EMPLOYEE"/>
  ...
</entity>

See Also

• "@TenantDiscriminatorColumn"

• "@TenantDiscriminatorColumns"

• "Using Multitenancy" in Solutions Guide for EclispeLink

• Multitenant Examples at http://wiki.eclipse.org/EclipseLink/Examples/JPA/Multitenant

@Mutable

Use @Mutable on a @Basic mapping to specify if the value of a complex field type can be changed (or not changed) instead of being replaced. Mutable mappings may affect the performance of change tracking; attribute change tracking can only be weaved with non-mutable mappings.

Annotation Elements

Table 2-33 describes this annotation's elements.

Usage

Most basic types (such as int, long, float, double, String, and BigDecimal) are not mutable.

By default, Date and Calendar types are assumed to be not mutable. To make these types mutable, use the @Mutable annotation. You can also use the global persistence property eclipselink.temporal.mutable to set the mappings as mutable.

By default, serialized types are assumed to be mutable. You can set the @Mutable annotation to false to make these types not mutable.

You can also configure mutable mappings for Date and Calendar fields in the persistence unit in the persistence.xml file.

Examples

Example 2-65 shows how to use the @Mutable annotation to specify Employee field hireDate.

@Entity
public class Employee implements Serializable {

    ...

    @Temporal(DATE)
    @Mutable
    public Calendar getHireDate() {
        return hireDate;
    }

..
}

Example 2-66 shows how to configure mutable mappings in the persistence unit persistence.xml file or by importing a property map.

<property name="eclipselink.temporal.mutable" value="true"/>

import org.eclipse.persistence.config.PersistenceUnitProperties;
propertiesMap.put(PersistenceUnitProperties.TEMPORAL_MUTABLE, "false");

See Also

For more information, see:

• "Mapping Annotations"

@NamedPLSQLStoredFunctionQueries

Use the @NamedPLSQLStoredFunctionQueries annotation to define multiple NamedPLSQLStoredFunctionQuery items.

Annotation Elements

Table 2-34 describes this annotation's elements.

See Also

For more information, see:

• "@NamedPLSQLStoredFunctionQueries"

@NamedPLSQLStoredFunctionQuery

Use the @NamedPLSQLStoredFunctionQuery annotation to define queries that call Oracle PLSQL stored functions as named queries

Annotation Elements

Table 2-36 describes this annotation's elements.

Usage

This annotation adds support for complex PLSQL types such as RECORD and TABLE, that are not accessible from JDBC.

You can specify @NamedPLSQLStoredFunctionQuery on an Entity or MappedSuperclass.

Examples

Example 2-67 shows how to use this annotation.

@NamedPLSQLStoredFunctionQuery(
    name="getEmployee", 
    functionName="EMP_PKG.GET_EMP",
    returnParameter=@PLSQLParameter(
        name="RESULT", 
        databaseType="EMP_PKG.EMP_TABLE"
    )
)
@Embeddable
@Struct(name="EMP_TYPE", fields={"F_NAME", "L_NAME", "SALARY"})
@PLSQLRecord(
    name="EMP_PKG.EMP_REC", 
    compatibleType="EMP_TYPE",
    javaType=Employee.class,
    fields={
        @PLSQLParameter(name="F_NAME"), 
        @PLSQLParameter(name="L_NAME"),
        @PLSQLParameter(
            name="SALARY", 
            databaseType="NUMERIC_TYPE"
        )
    }
)

public class Employee { ...}

See Also

For more information, see:

• Oracle PL/SQL
  http://www.oracle.com/technetwork/database/features/plsql/index.html

@NamedPLSQLStoredProcedureQueries

Use the @NamedPLSQLStoredProcedureQueries annotation to define multiple NamedPLSQLStoredProcedureQuery items.

Annotation Elements

Table 2-36 describes this annotation's elements.

Examples

Example 2-68 shows how to use this annotation.

@NamedPLSQLStoredProcedureQueries({ 
    @NamedPLSQLStoredProcedureQuery(name="getEmployee", 
    functionName="EMP_PKG.GET_EMP", 
    parameters={ @PLSQLParameter( name="EMP_OUT", direction=:Direction.OUT, databaseType="EMP_PKG.EMP_REC") } )
    })

See Also

For more information, see:

• "@NamedPLSQLStoredProcedureQuery"

• "Stored Procedures" in Understanding EclipseLink

• Oracle PL/SQL http://www.oracle.com/technetwork/database/features/plsql/index.html

• PLSQL Stored Procedure Exampleshttp://wiki.eclipse.org/EclipseLink/Examples/JPA/PLSQLStoredFunction

@NamedPLSQLStoredProcedureQuery

Use the @NamedPLSQLStoredProcedureQuery annotation to define queries that call Oracle PLSQL stored procedures as named queries.

Annotation Elements

Table 2-37 describes this annotation's elements.

Usage

This annotation adds support for complex PLSQL types such as RECORD and TABLE, that are not accessible from JDBC.

You can specify @NamedPLSQLStoredProcedureQuery on an Entity, Embeddable, or MappedSuperclass.

Examples

Example 2-69 shows how to use this annotation.

@NamedPLSQLStoredProcedureQuery(
    name="getEmployee",
    procedureName="MyStoredProcedure",
    functionName="EMP_PKG.GET_EMP", 
    parameters={
        @PLSQLParameter(
            name="EMP_OUT", 
            direction=Direction.OUT,
            databaseType="EMP_PKG.EMP_REC"
        )
    }
)
@Embeddable
@Struct(name="EMP_TYPE", fields={"F_NAME", "L_NAME", "SALARY"})
@OracleObject(
    name="EMP_PKG.EMP_REC",
    compatibleType="EMP_TYPE",
    javaType=Employee.class,
    fields={
        @PLSQLParameter(name="F_NAME"),
        @PLSQLParameter(name="L_NAME"),
        @PLSQLParameter(
            name="SALARY",
            databaseType="NUMERIC_TYPE"
        )
    }
)
 
public class Employee { ...}

See Also

For more information, see:

• "Stored Procedures" in Understanding EclipseLink

• Oracle PL/SQL http://www.oracle.com/technetwork/database/features/plsql/index.html

• PLSQL Stored Procedure Exampleshttp://wiki.eclipse.org/EclipseLink/Examples/JPA/PLSQLStoredFunction

@NamedStoredFunctionQueries

Use the @NamedStoredFunctionQueries annotation to define multiple NamedStoredFunctionQuery items.

Annotation Elements

Table 2-38 describes this annotation's elements.

Examples

Example 2-70 shows how to use this annotation.

@NamedStoredFunctionQueries{(
    @NamedStoredFunctionQuery(
        name="StoredFunction_In",
        functionName="StoredFunction_In",
        parameters={
            @StoredProcedureParameter(direction=IN, name="P_IN", queryParameter="P_IN", type=Long.class)
        },
        returnParameter=@StoredProcedureParameter(queryParameter="RETURN", type=Long.class)
    )
)}

To define multiple named stored procedures in the eclipselink-orm.xml file, create a list of multiple <named-stored-function_query> elements.

See Also

For more information, see:

• "@NamedStoredFunctionQuery"

@NamedStoredFunctionQuery

Use @NamedStoredFunctionQuery to define queries that call stored functions as named queries.

Annotation Elements

Table 2-39 describes this annotation's elements.

Usage

You can specify @NamedStoredFunctionQuery on an Entity or MappedSuperclass.

Examples

Example 2-71 shows how to use this annotation.

@Entity
@Table(name="CMP3_ADDRESS")
 
@NamedStoredFunctionQuery(
  name="StoredFunction_In",
  functionName="StoredFunction_In",
  parameters={
    @StoredProcedureParameter(direction=IN, name="P_IN", queryParameter="P_IN", type=Long.class)
    },
  returnParameter=@StoredProcedureParameter(queryParameter="RETURN", type=Long.class)
  )
public class Address implements Serializable {
...
}

Example 2-72 shows how to use the <named-stored-function-query> element in the eclipselink-orm.xml file.

<named-stored-function-query name="StoredFunction_In" procedure-name="StoredFunction_In">
    <parameter direction="IN" name="P_IN" query-parameter="P_IN" type="Long"/>
</named-stored-function-query>

See Also

For more information, see:

• "@NamedStoredFunctionQueries"

@NamedStoredProcedureQueries

Use the @NamedStoredProcedureQueries annotation to define multiple NamedStoredProcedureQuery items.

Annotation Elements

Table 2-40 describes this annotation's elements.

Examples

Example 2-73 shows how to use this annotation.

@Entity
@Table(name="EMPLOYEE")
@NamedStoredProcedureQueries({
  @NamedStoredProcedureQuery(
    name="ReadEmployeeInOut",
     resultClass=org.eclipse.persistence.testing.models.jpa.customfeatures.Employee.class,
    procedureName="Read_Employee_InOut",
    parameters={
      @StoredProcedureParameter(direction=IN_OUT, name="employee_id_v", queryParameter="ID", type=Integer.class),
      @StoredProcedureParameter(direction=OUT, name="nchar_v", queryParameter="NCHARTYPE", type=Character.class)}
    ),
    @NamedStoredProcedureQuery(
      name="ReadEmployeeCursor",
      resultClass=org.eclipse.persistence.testing.models.jpa.customfeatures.Employee.class,
      procedureName="Read_Employee_Cursor",
      parameters={
        @StoredProcedureParameter(direction=IN, name="employee_id_v", queryParameter="ID", type=Integer.class),
        @StoredProcedureParameter(direction=OUT_CURSOR, queryParameter="RESULT_CURSOR")})
})
public class Employee implements Serializable {

To define multiple named stored procedure queries in the eclipselink-orm.xml file, simply create a list of multiple <named-stored-procedure_query> elements.

See Also

For more information, see:

• "@NamedStoredProcedureQuery"

• "Stored Procedures" in Understanding EclipseLink

@NamedStoredProcedureQuery

Use the @NamedStoredProcedureQuery annotation to define queries that call stored procedures as named queries.

Annotation Elements

Table 2-41 describes this annotation's elements.

Usage

You can specify @NamedStoredProcedureQuery on an Entity or MappedSuper class.

Examples

Example 2-74 shows how to use @NamedStoredProcedureQuery to define a stored procedure.

@NamedStoredProcedureQuery(name="findAllEmployees", procedureName="EMP_READ_ALL", resultClass=Employee.class, parameters={
    @StoredProcedureParameter(queryParameter="result", name="RESULT_CURSOR", direction=Direction.OUT_CURSOR})
@Entity
public class Employee {
 ...
}

Example 2-75 shows how to use the <named-stored-procedure-query> element in the eclipselink-orm.xml file.

<named-stored-procedure-query name="SProcXMLInOut" result-class="Address" procedure-name="SProc_Read_XMLInOut">
    <parameter direction="IN_OUT" name="address_id_v" query-parameter="ADDRESS_ID" type="Long"/>
    <parameter direction="OUT" name="street_v" query-parameter="STREET" type="String"/>
</named-stored-procedure-query>

See Also

For more information, see:

• "@NamedStoredProcedureQueries"

• "Stored Procedures" in Understanding EclipseLink

• "Stored Procedures Examples" http://wiki.eclipse.org/EclipseLink/Examples/JPA/StoredProcedures

@Noncacheable

Use @Noncacheable to configure caching behavior for relationships. If used on a relationship, that relationship will not be cached, even though the parent Entity may be cached.

Annotation Elements

There are no elements for this annotation.

Usage

Each time EclipseLink retrieves the Entity, the relationship will be reloaded from the datasource. This may be useful for situations where caching of relationships is not desired or when using different EclipseLink cache types and having cached references extends the cache lifetime of related Entities using a different caching scheme. For instance Entity A references Entity B, Entity A is Full and Entity B is Weak. Without removing the caching of the relationsip the Entity B's cache effectively become Full.

Examples

Example 2-76 shows how to use @Noncacheable to create a protected cache.

@Entity
@Cache(
  isolation=CacheIsolationType.PROTECTED
)
public class Employee {
  @Id
  private long id;
  ...
  @OneToMany(mappedBy="manager")
  @Noncacheable
  private List<Employee> managedEmployees;
  ...
}

Example 2-77 shows using the <noncacheable> XML element in the eclipselink-orm.xml file.

<?xml version="1.0"?>
<entity-mappings
    xmlns="http://www.eclipse.org/eclipselink/xsds/persistence/orm"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://www.eclipse.org/eclipselink/xsds/persistence/orm http://www.eclipse.org/eclipselink/xsds/eclipselink_orm_2_4.xsd"
    version="2.4">
    <entity name="Employee" class="org.acme.Employee" access="FIELD">
        <cache isolation="PROTECTED"/>
        <attributes>
            <id name= "id"/>
            <one-to-many name="managedEmployees" mapped-by="manager">
                <noncacheable/>
            </one-to-many>
        </attributes>
    </entity>
</entity-mappings

See Also

For more information, see:

• "Caching"http://wiki.eclipse.org/EclipseLink/UserGuide/JPA/Basic_JPA_Development/Caching

• "EclipseLink Caches" in Understanding EclipseLink

• "Scaling EclipseLink Applications in Clusters" in Solutions Guide for EclispeLink

@NoSql

Use @NoSql to specify a non-relational (that is, no SQL) data source. EclipseLink can map non-relational data to objects and access that data through JPA.

Annotation Elements

Table 2-42 describes this annotation's elements.

Usage

The dataFormat depends on the NoSQL platform used:

• For MongoDB, use MAPPED.

• For Oracle NoSQL, use MAPPED (for key/value data) or XML (for a single XML document).

• For XML files and XML messaging, use XML.

Supported Datasources

EclipseLink supports several NoSQL and EIS platforms, as well as generic NoSQL and EIS datasources through the JavaEE Connector Architecture CCI (Common Client Interface) API. You can also define your own EISPlatform subclass and JCA adapter

EclipseLink supports the following datasources:

• MongoDB

• Oracle NoSQL

• XML Files

• JMS

• Oracle AQ

Examples

Example 2-78 shows using @NoSql with an XML data source.

@Entity
@NoSql(dataType="order")
public class Order {
  @Id
  @GeneratedValue
  @Field(name="@id")
  private long id;
  @Basic
  @Field(name="@description")
  private String description;
  @Embedded
  @Field(name="delivery-address")
  private Address deliveryAddress
  @ElementCollection
  @Field(name="orderLines/order-line")
  private List<OrderLine> orderLines;
  @ManyToOne
  @JoinField(name="customer-id")
  private Customer customer;
}
 
@Embeddable
@NoSql
public class OrderLine {
    @Field(name="@line-number")
    private int lineNumber;
    @Field(name="@item-name")
    private String itemName;
    @Field(name="@quantity")
    private int quantity;  
}

<order id="4F99702B271B1948027FAF06" description="widget order">
  <deliveryAddress street="1712 Hasting Street" city="Ottawa" province="ON" postalCode="L5J1H5"/>
  <order-lines>
      <order-line lineNumber="1" itemName="widget A" quantity="5"/>
      <order-line lineNumber="2" itemName="widget B" quantity="1"/>
      <order-line lineNumber="3" itemName="widget C" quantity="2"/>
  <order-lines>
  <customer-id>4F99702B271B1948027FAF08</customer-id>
<order>

Example 2-79 shows using @NoSql with a JSON data source.

@Entity
@NoSql(dataType="orders", dataFormat=DataFormatType.MAPPED)
public class Order {
  @Id
  @GeneratedValue
  @Field(name="_id")
  private long id;
  @Basic
  @Field(name="description")
  private String description;
  @Embedded
  @Field(name="deliveryAddress")
  private Address deliveryAddress
  @ElementCollection
  @Field(name="orderLines")
  private List<OrderLine> orderLines;
  @ManyToOne
  @JoinField(name="customerId")
  private Customer customer;
}
 
@Embeddable
@NoSql(dataFormat=DataFormatType.MAPPED)
public class OrderLine {
    @Field(name="lineNumber")
    private int lineNumber;
    @Field(name="itemName")
    private String itemName;
    @Field(name="quantity")
    private int quantity;  
}

{
  "_id": "4F99702B271B1948027FAF06",
  "description": "widget order",
  "deliveryAddress": {
      "street": "1712 Hasting Street",
      "city": "Ottawa",
      "province": "ON",
      "postalCode": "L5J1H5",
  },
  "orderLines": [
      {"lineNumber": "1", "itemName": "widget A", "quantity": "5"},
      {"lineNumber": "2", "itemName": "widget B", "quantity": "1"},
      {"lineNumber": "3", "itemName": "widget C", "quantity": "2"}
  ],
  "customerId": "4F99702B271B1948027FAF08",
}

See Also

For more information, see:

• @NoSQL http://wiki.eclipse.org/EclipseLink/UserGuide/JPA/Advanced_JPA_Development/NoSQL

• NoSQL Persistence Units http://wiki.eclipse.org/EclipseLink/UserGuide/JPA/Advanced_JPA_Development/NoSQL/Persistence_Units

• Examples http://wiki.eclipse.org/EclipseLink/Examples/JPA/NoSQL

• Oracle Coherence Integration Guide for EclipseLink with Coherence Grid

• "Using Non-SQL Databases" in Understanding EclipseLink

• "Using NoSQL Databases" in Understanding EclipseLink

• "Using EclipseLink with Nonrelational Databases" in Solutions Guide for EclispeLink

• "nosql.property"

• EclipseLink Platform Incubator http://wiki.eclipse.org/EclipseLink/Development/Incubator/Platform

• Supported NoSQL and EIS Datasources http://wiki.eclipse.org/EclipseLink/UserGuide/JPA/Advanced_JPA_Development/NoSQL/Supported_Data-sources

@ObjectTypeConverter

The @ObjectTypeConverter annotation specifies an org.eclipse.persistence.mappings.converters.ObjectTypeConverter that converts a fixed number of database data value(s) to Java object value(s) during the reading and writing of a mapped attribute.

Annotation Elements

Table 2-43 describes this annotation's elements.

Usage

EclipseLink also includes @TypeConverter and @StructConverter converters.

Examples

Example 2-80 shows how to use the @ObjectTypeConverter annotation to specify object converters for the gender field.

public class Employee implements Serializable{
     ...
     @ObjectTypeConverter (
         name="genderConverter",
         dataType=java.lang.String.class,
         objectType=java.lang.String.class,
         conversionValues={
             @ConversionValue(dataValue="F", objectValue="Female"),
             @ConversionValue(dataValue="M", objectValue="Male")}
     )
     @Convert("genderConverter")
     public String getGender() {
         return gender;
     }
     ...
 }

<object-type-converter name="gender-converter" object-type="model.Gender"     data-type="java.lang.String">
    <conversion-value object-value="Male" data-value="M" />
    <conversion-value object-value="Female" data-value="F" />
</object-type-converter>

See Also

For more information, see:

• "@TypeConverter"

• "@StructConverter"

• "@ConversionValue"

@ObjectTypeConverters

Use @ObjectTypeConverters to define multiple ObjectTypeConverter items.

Annotation Elements

Table 2-44 describes this annotation's elements.

Examples

Example 2-82 shows how to use this annotation.

@Entity(name="Employee")
@Table(name="CMP3_FA_EMPLOYEE")
@ObjectTypeConverters({
  @ObjectTypeConverter(
    name="sex",
    dataType=String.class,
    objectType=org.eclipse.persistence.testing.models.jpa.fieldaccess.advanced.Employee.Gender.class,
    conversionValues={
      @ConversionValue(dataValue="F", objectValue="Female"),
      @ConversionValue(dataValue="M", objectValue="Male")
    }
  )
})

To define multiple object type converts in the eclipselink-orm.xml file, simply create a list of multiple <object-type-converter> elements.

See Also

For more information, see:

• "@ObjectTypeConverter"

@OptimisticLocking

Use @OptimisticLocking to specify the type of optimistic locking EclipseLink should use when updating or deleting entities.

Annotation Elements

Table 2-45 describes this annotation's elements.

Usage

You can specify @OptimisticLocking on an Entity or MappedSuperclass.

Examples

Example 2-83 shows how to use the @OptimisticLocking annotation for all columns

@Table(name = "EMPLOYEES")
  @OptimisticLocking(type=OptimisticLockingType.ALL_COLUMNS)
  public class Employee implements Serializable {
      ...
  }

Example 2-83 shows how to use the <optimistic-locking> element in the eclipselink-orm.xml file for a single column.

<entity name="Employee" class="my.Employee" access="PROPERTY" change-tracking="DEFERRED">
...
    <optimistic-locking type="SELECTED_COLUMNS" cascade="false">
      <selected-column name="id"/>
      <selected-column name="firstName"/>
    </optimistic-locking>
...
</entity>

See Also

For more information, see:

• "Scaling EclipseLink Applications in Clusters" in Solutions Guide for EclispeLink

@OracleArray

Use the @OracleArray annotation to define an Oracle database VARRAY type, which you can use within PLSQL procedure calls.

Annotation Elements

Table 2-46 describes the annotation's elements.

Examples

Example 2-85 shows how to use the @OracleArray annotation to define a VARRAY type.

@NamedPLSQLStoredFunctionQuery(
name="getEmployee", 
functionName="EMP_PKG.GET_EMP",
parameters={
   @PLSQLParameter(
     name="EMP_OUT",
     direction=Direction.OUT,
     databaseType="EMP_PKG.EMP_REC"
     )
   }
)
@Embeddable
@Struct(name="EMP_TYPE", fields={"F_NAME",
"L_NAME","SALARY"})
@OracleArray(
   name="EMP_PKG.EMP_REC",
   nestedType=VARCHAR_TYPE
   javaType=Employee.class,
)
public class Employee{...}

See Also

For more information, see:

• "@NamedPLSQLStoredProcedureQuery"

• "@OracleArrays"

@OracleArrays

Use the @OracleArrays annotation to define multiple VARRAY types.

Annotation Elements

Table 2-47 describes the annotation's elements.

Examples

See "@OracleArray" for an example of how to use this annotation.

See Also

For more information, see:

• "@OracleArray"

@OracleObject

Use the @OracleObject annotation to define an Oracle database OBJECT type, which you can use within PLSQL procedure calls.

Annotation Elements

Table 2-48 describes the annotation's elements.

Examples

Example 2-86 shows how to use the @OracleObject annotation to define an Oracle OBJECT type.

@NamedPLSQLStoredFunctionQuery(
name="getEmployee",
functionName="EMP_PKG.GET_EMP",
parameters={
   @PLSQLParameter(
     name="EMP_OUT",
     direction=Direction.OUT,
     databaseType="EMP_PKG.EMP_REC"
     )
   }
)
@Embeddable
@Struct(name="EMP_TYPE", fields={"F_NAME",
"L_NAME","SALARY"})
@OracleObject(
   name="EMP_PKG.EMP_REC",
   javaType=Employee.class,
   fields={
     @PLSQLParameter(name="F_NAME"),
     @PLSQLParameter(name="L_NAME"),
     @PLSQLParameter(
      name="SALARY",
      databaseType="NUMERIC_TYPE"
     )
   }
)
public class Employee{...}

See Also

For more information, see:

• "@NamedPLSQLStoredProcedureQuery"

• "@OracleObjects"

@OracleObjects

Use the @OracleObjects annotation to define multiple Oracle OBJECT types.

Annotation Elements

Table 2-49 describes the annotation's elements.

Examples

See "@OracleObject" for an example of how to use this annotation.

See Also

For more information, see:

• "@OracleObject"

@OrderCorrection

Use @OrderCorrection to specify a strategy to use if the order list read from the database is invalid (for example, it has nulls, duplicates, negative values, or values greater than or equal to the list size).

To be valid, an order list of n elements must be {0, 1,..., n-1}

Annotation Elements

Table 2-50 describes this annotation's elements.

Usage

When using @OrderCorrection, you can specify how EclipseLink should handle invalid list orders:

• EXCEPTION – When OrderCorrectionType=EXCEPTION, EclipseLink will not correct the list. Instead, EclipseLink will throw a QueryException with error code QueryException.LIST_ORDER_FIELD_WRONG_VALUE

  For example, given the following list of three objects in the database:

  {null, objectA}; {2, objectB}, {5, ObjectC}; 
  

  When read into the application, EclipseLink will throw an exception.

• READ – When OrderCorrectionType=READ, EclipseLink corrects the list read into application, but does not retain any information about the invalid list order that remains in the database. Although this is not an issue in read-only uses of the list, if the list is modified and then saved into the database, the order will most likely differ from the cache and be invalid.

  The READ mode is used as the default when the mapped attribute is not a List.

  For example, given the following list of three objects in the database:

  {null, objectA}; {2, objectB}, {5, ObjectC}
  

  • When read as a list: {objectA, objectB, objectC}

  • When adding a new element to the list: {objectA, objectB, objectC, objectD}

  • When saving the updated list to the database: {null, objectA}, {2, objectB}, {5, objectC}, {3, objectD}

  • When reading the list again: {objectA, objectB, objectD, objectC}

• READ_WRITE – When OrderCorrectionType=READ_WRITE, EclipseLink corrects the order of the list read into application and remembers the invalid list order left in the database. If the list is updated and saved to the database, the order indexes are saved ensuring that the list order in the data base will be exactly the same as in cache (and therefore valid).

  The READ_WRITE mode is used as the default when the mapped attribute is either a List or Vector (that is, it is assignable from the EclipseLink internal class IndirectList). In JPA, if the mode is not specified, READ_WRITE is used by default.

  For example, given the following list of three objects in the database:

  {null, objectA}; {2, objectB}, {5, ObjectC}
  

  • When read as a list: {objectA, objectB, objectC}

  • When adding a new element to the list: {objectA, objectB, objectC, objectD}

  • When saving the updated list to the database: {0, objectA}, {1, objectB}, {2, objectC}, {3, objectD}

  • When reading the list again: {objectA, objectB, objectC, objectD}

Examples

Example 2-87 shows how to use this annotation.

@OrderColumn(name="ORDER_COLUMN")
@OrderCorrection(EXCEPTION)
List<String> designations;

Example 2-88 shows how to use this extension in the eclipselink-orm.xml file.

<element-collection name="designations">
    <order-column name="ORDER_COLUMN" correction-type="EXCEPTION"/>
</element-collection>

See Also

For more information see:

• "Entity Annotations"

@Partitioned

Use @Partitioned to specify a partitioning policy to use for an Entity or relationship.

Annotation Elements

Table 2-51 describes this annotation's elements.

Usage

Use partitioning to partition the data for a class across multiple databases or a database cluster (such as Oracle RAC). Partitioning can provide improved scalability by allowing multiple database machines to service requests.

You can specify @Partitioned on an Entity, relationship, query, or session/persistence unit.

Partitioning Policies

To configure data partitioning, use the @Partitioned annotation and one or more partitioning policy annotations. The annotations for defining the different kinds of policies are:

• @HashPartitioning: Partitions access to a database cluster by the hash of a field value from the object, such as the object's ID, location, or tenant. The hash indexes into the list of connection pools/nodes. All write or read request for objects with that hash value are sent to the same server. If a query does not include the hash field as a parameter, it can be sent to all servers and unioned, or it can be left to the session's default behavior.

• @PinnedPartitioning: Pins requests to a single connection pool/node. This allows for vertical partitioning.

• @RangePartitioning: Partitions access to a database cluster by a field value from the object, such as the object's ID, location, or tenant. Each server is assigned a range of values. All write or read requests for objects with that value are sent to the same server. If a query does not include the field as a parameter, then it can either be sent to all server's and unioned, or left to the session's default behavior.

• @ReplicationPartitioning: Sends requests to a set of connection pools/nodes. This policy is for replicating data across a cluster of database machines. Only modification queries are replicated.

• @RoundRobinPartitioning: Sends requests in a round-robin fashion to the set of connection pools/nodes. It is for load balancing read queries across a cluster of database machines. It requires that the full database be replicated on each machine, so it does not support partitioning. The data should either be read-only, or writes should be replicated.

• @UnionPartitioning: Sends queries to all connection pools and unions the results. This is for queries or relationships that span partitions when partitioning is used, such as on a ManyToMany cross partition relationship.

• @ValuePartitioning: Partitions access to a database cluster by a field value from the object, such as the object's location or tenant. Each value is assigned a specific server. All write or read requests for objects with that value are sent to the same server. If a query does not include the field as a parameter, then it can be sent to all servers and unioned, or it can be left to the session's default behavior.

• @Partitioning: Partitions access to a database cluster by a custom partitioning policy. A PartitioningPolicy class must be provided and implemented.

Partitioning policies are globally-named objects in a persistence unit and are reusable across multiple descriptors or queries. This improves the usability of the configuration, specifically with JPA annotations and XML.

The persistence unit properties support adding named connection pools in addition to the existing configuration for read/write/sequence. A named connection pool must be defined for each node in the database cluster.

If a transaction modifies data from multiple partitions, JTA should be used to ensure 2-phase commit of the data. An exclusive connection can also be configured in the EntityManager to ensure only a single node is used for a single transaction.

Clustered Databases and Oracle RAC

Some databases support clustering the database across multiple machines. Oracle RAC allows for a single database to span multiple different server nodes. Oracle RAC also supports table and node partitioning of data. A database cluster allows for any of the data to be accessed from any node in the cluster. However, it is generally it is more efficient to partition the data access to specific nodes, to reduce cross node communication.

EclipseLink partitioning can be used in conjunction with a clustered database to reduce cross node communication, and improve scalability.

To use partitioning with a database cluster to following is required:

• Partition policy should not enable replication, as database cluster makes data available to all nodes.

• Partition policy should not use unions, as database cluster returns the complete query result from any node.

• A data source and EclipseLink connection pool should be defined for each node in the cluster.

• The application's data access and data partitioning should be designed to have each transaction only require access to a single node.

• Usage of an exclusive connection for an EntityManager is recommended to avoid having multiple nodes in a single transaction and avoid 2-phase commit.

Examples

Example 2-89 shows how to partition Employee data by location. The two primary sites, Ottawa and Toronto are each stored on a separate database. All other locations are stored on the default database. Project is range partitioned by its ID, as shown in Example 2-90. Each range of ID values are stored on a different database. The employee/project relationship is an example of a cross partition relationship. To allow the employees and projects to be stored on different databases a union policy is used and the join table is replicated to each database.

@Entity
@IdClass(EmployeePK.class)
@UnionPartitioning(
        name="UnionPartitioningAllNodes",
        replicateWrites=true)
@ValuePartitioning(
        name="ValuePartitioningByLOCATION",
        partitionColumn=@Column(name="LOCATION"),
        unionUnpartitionableQueries=true,
        defaultConnectionPool="default",
        partitions={
            @ValuePartition(connectionPool="node2", value="Ottawa"),
            @ValuePartition(connectionPool="node3", value="Toronto")
        })
@Partitioned("ValuePartitioningByLOCATION")
public class Employee {
    @Id
    @Column(name = "EMP_ID")
    private Integer id;
 
    @Id
    private String location;
    ...
 
    @ManyToMany(cascade = { PERSIST, MERGE })
    @Partitioned("UnionPartitioningAllNodes")
    private Collection<Project> projects;
    ...
}

@Entity
@RangePartitioning(
        name="RangePartitioningByPROJ_ID",
        partitionColumn=@Column(name="PROJ_ID"),
        partitionValueType=Integer.class,
        unionUnpartitionableQueries=true,
        partitions={
            @RangePartition(connectionPool="default", startValue="0", endValue="1000"),
            @RangePartition(connectionPool="node2", startValue="1000", endValue="2000"),
            @RangePartition(connectionPool="node3", startValue="2000")
        })
@Partitioned("RangePartitioningByPROJ_ID")
public class Project {
    @Id
    @Column(name="PROJ_ID")
    private Integer id;
    ...
}

See Also

For more information, see:

• "@Partitioning"

• "@HashPartitioning"

• "@PinnedPartitioning"

• "@RangePartition"

• "@ReplicationPartitioning"

• "@RoundRobinPartitioning"

• "@UnionPartitioning"

• "@ValuePartitioning"

• "Data Partitioning"http://wiki.eclipse.org/EclipseLink/UserGuide/JPA/Advanced_JPA_Development/Data_Partitioning

• Partitioning Exampleshttp://wiki.eclipse.org/EclipseLink/Examples/JPA/Partitioning

@Partitioning

Use @Partitioning to configure a custom PartitioningPolicy.

Annotation Elements

Table 2-52 describes this annotation's elements.

Usage

Data partitioning allows for an application to scale its data across more than a single database machine. EclipseLink supports data partitioning at the Entity level to allow a different set of entity instances for the same class to be stored in a different physical database or different node within a database cluster. Both regular databases and clustered databases are supported. Data can be partitioned both horizontally and vertically.

Partitioning can be enabled on an entity, a relationship, a query, or a persistence unit.

Examples

Example 2-91 shows a custom partitioning policy.

@Entity
@Partitioning(name="order", partitioningClass=OrderPartitioningPolicy.class)
@public class Order {
    ...
}
 
public class OrderPartitioningPolicy extends PartitioningPolicy {
 
    public List<Accessor> getConnectionsForQuery(AbstractSession session, DatabaseQuery query, AbstractRecord arguments) {
        
        List<Accessor> accessors = new ArrayList<Accessor>(1);
        accessors.add(getAccessor(ACMEPool.leastBusy(), session, query, false));
        return accessors;
    }
}

See Also

For more information, see:

• "@Partitioned"

• "@HashPartitioning"

• "@PinnedPartitioning"

• "@RangePartitioning"

• "@ReplicationPartitioning"

• "@RoundRobinPartitioning"

• "@UnionPartitioning"

• "@ValuePartitioning"

• "partitioning"

• "Data Partitioning" http://wiki.eclipse.org/EclipseLink/UserGuide/JPA/Advanced_JPA_Development/Data_Partitioning

• EclipseLink Examples http://wiki.eclipse.org/EclipseLink/Examples/JPA/Partitioning

@PinnedPartitioning

Use @PinnedPartitionPolicy to pin requests to a single connection pool, allowing for vertical partitioning (that is, having an entity, query, or session always access a single database).

Annotation Elements

Table 2-53 describes this annotation's elements.

Usage

Partition policies are globally named, to allow reuse. You must also set the partitioning policy with the @Partitioned annotation.

You can specify @PinnedPartitioning on an Entity, relationship, query, or session/persistence unit.

The persistence unit properties support adding named connection pools in addition to the existing configuration for read/write/sequence. A named connection pool must be defined for each node in the database cluster.

If a transaction modifies data from multiple partitions, you should use JTA ensure proper two-phase commit of the data. You can also configure an exclusive connection in the EntityManager to ensure that only a single node is used for a single transaction.

Examples

See "Using Partitioning" for an example of partitioning with EclipseLink.

See Also

For more information, see:

• "Data Partitioning"http://wiki.eclipse.org/EclipseLink/UserGuide/JPA/Advanced_JPA_Development/Data_Partitioning

• "@Partitioned"

@PLSQLParameter

Use @PLSQLParameter within a NamedPLSQLStoredProcedureQuery or PLSQLRecord annotation.

Annotation Elements

Table 2-54 describes this annotation's elements.

Usage

Use the @PLSQLParameter annotation to configure the parameter and type for Oracle PLSQL stored procedures and record types that use extended PLSQL types instead of regular SQL types. They support PLSQL RECORD, TABLE, BOOLEAN and other extend PLSQL types.

Examples

See "@NamedPLSQLStoredProcedureQuery" for an example using the @PLSQLParameter annotation.

See Also

For more information:

• "@NamedPLSQLStoredProcedureQuery"

• "@PLSQLRecord"

• PLSQL Stored Procedure Exampleshttp://wiki.eclipse.org/EclipseLink/Examples/JPA/PLSQLStoredFunction

@PLSQLRecord

Use @PLSQLRecord to define a database PLSQL RECORD type for use within PLSQL procedures.

Annotation Elements

Table 2-55 describes this annotation's elements.

Usage

Oracle PLSQL RECORD types are structured database types. Although JDBC does not provide a mechanism for returning these types, EclipseLink provides support to translate these types into OBJECT types. You must create an OBJECT type on the database to mirror the RECORD type and provide it as the compatibileType in the @PLSQLRecord.

You can then map the RECORD to a Java class, map the Java class as an @Embeddable, use the @Struct annotations to map the Java class to the OBJECT type that mirrors the RECORD type.

You can then call and return the Java class as parameters to the PLSQL stored procedure query.

Examples

Example 2-92 shows how to use this annotation.

@NamedPLSQLStoredFunctionQuery(name="getEmployee", functionName="EMP_PKG.GET_EMP",
    returnParameter=@PLSQLParameter(name="RESULT", databaseType="EMP_PKG.EMP_REC"))
@Embeddable
@Struct(name="EMP_TYPE", fields={"F_NAME", "L_NAME", "SALARY"})
@PLSQLRecord(name="EMP_PKG.EMP_REC", compatibleType="EMP_TYPE", javaType=Employee.class,
    fields={@PLSQLParameter(name="F_NAME"), @PLSQLParameter(name="L_NAME"), @PLSQLParameter(name="SALARY", databaseType="NUMERIC_TYPE")})
public class Employee {
 ...
}

See Also

For more information, see:

• "Stored Procedures" in Understanding EclipseLink

• "@NamedPLSQLStoredProcedureQuery"

• "@PLSQLRecords"

• Oracle PL/SQL http://www.oracle.com/technetwork/database/features/plsql/index.html

• PLSQL Stored Procedure Exampleshttp://wiki.eclipse.org/EclipseLink/Examples/JPA/PLSQLStoredFunction

@PLSQLRecords

Use @PLSQLRecords to define multiple PLSQLRecord.

Annotation Elements

Table 2-56 describes this annotation's elements.

Examples

See "@PLSQLRecord" for an example of how to use this annotation.

See Also

For more information, see:

• "Stored Procedures" in Understanding EclipseLink

• "@NamedPLSQLStoredProcedureQuery"

• "@PLSQLRecord"

• Oracle PL/SQL http://www.oracle.com/technetwork/database/features/plsql/index.html

• PLSQL Stored Procedure Exampleshttp://wiki.eclipse.org/EclipseLink/Examples/JPA/PLSQLStoredFunction

@PLSQLTable

Use the @PLSQLTable annotation to define a database PLSQL TABLE type, which you can use within PLSQL procedure calls.

Annotation Elements

Table 2-57 describes this annotation's elements.