EclipseLink persistence provider applies the first annotation that it finds; it ignores other mapping annotations, if specified. In most cases, EclipseLink does not log warnings or throw exceptions for duplicate or incompatible mapping annotations.

If EclipseLink persistence provider does not find any of the mapping annotations from the preceding list, it applies the defaults defined by the JPA specification: not necessarily the @Basic annotation.

How to Use the @BasicCollection Annotation

You can use the @BasicCollection annotation to map an org.eclipse.persistence.mappings.DirectCollectionMapping, which stores a collection of simple types, such as String, Number, Date, and so on, in a single table. The table must store the value and the foreign key to the source object.

Use the @BasicCollection annotation in conjunction with a @CollectionTable annotation. You can also use it in conjunction with @Convert to modify the data value(s) during reading and writing of the collection, as well as with the @JoinFetch annotation.

This table lists attributes of the @BasicCollection annotation.

Attributes of the @BasicCollection Annotation

Attribute

Description

Default

Required or Optional

fetch

The javax.persistence.FetchType enumerated type that defines whether EclipseLink should lazily load or eagerly fetch the value of the field or property.

FetchType.LAZY

optional

valueColumn

The name of the value column (javax.persistence.Column) that holds the direct collection data.

@ColumnNote: EclipseLink persistence provider sets the default to the name of the field or property.

optional

Note: If you specify @BasicCollection on an attribute of type Map, EclipseLink will throw an exception: the type must be Collection, Set or List. If you specify the fetch type as LAZY, Collection implementation classes will also not be valid.

This example shows how to use the @BasicCollection annotation to specify Employee field responsibilities.

How to Use the @BasicMap Annotation

You can use the @BasicMap annotation to map an org.eclipse.persistence.mappings.DirectMapMapping, which stores a collection of key-value pairs of simple types, such as String, Number, Date, and so on, in a single table. The table must store the value and the foreign key to the source object.

@Convert – an equivalent of specifying @Convert("none") resulting in no converter added to the direct map key.

optional

Note: If you specify @BasicMap on an attribute of type Collection, EclipseLink will throw an exception: the type must be Map. If you specify the fetch type as LAZY, Map implementation classes are also not valid.

This example shows how to use the @BasicMap annotation to specify Employee field licenses.

How to Use the @CollectionTable Annotation

You can use the @CollectionTable annotation in conjunction with a @BasicCollection annotation or the @BasicMap annotation. If you do not specify the @CollectionTable, EclipseLink persistence provider will use the defaults.

empty String
Note: EclipseLink persistence provider applies the following concatenated String as a default: the name of the source entity + "_" + the name of the relationship property or field of the source entity.

Set this attribute to an array of javax.persistence.PrimaryKeyJoinColumn instances to specify a primary key column that is used as a foreign key to join to another table. If the source entity uses a composite primary key, you must specify a primary key join column for each field of the composite primary key. If the source entity uses a single primary key, you may choose to specify a primary key join column (optional). Otherwise, EclipseLink persistence provider will apply the following defaults:

javax.persistence.PrimaryKeyJoinColumnname – the same name as the primary key column of the primary table of the source entity;

javax.persistence.PrimaryKeyJoinColumn referencedColumnName – the same name of the primary key column of the primary table of the source entity.

If the source entity uses a composite primary key and you failed to specify the primary key join columns, EclipseLink will throw an exception.

empty PrimaryKeyJoinColumn array

optional

uniqueConstraints

Set this attribute to an array of javax.persistence.UniqueConstraint instances that you want to place on the table. These constraints are only used if table generation is in effect.

empty UniqueConstraint array

optional

This example shows how to use the @CollectionTable annotation to specify Employee field responsibilities.

If you remove the reference to a target from a source, then delete the target.

Do not configure privately owned relationships to objects that might be shared. An object should not be the target in more than one relationship if it is the target in a privately owned relationship.

The exception to this rule is the case when you have a many-to-many relationship in which a relation object is mapped to a relation table and is referenced through a one-to-many relationship by both the source and the target. In this case, if the one-to-many mapping is configured as privately owned, then when you delete the source, all the association objects will be deleted.

You can override this configuration using @Mutable(value=true). For example, if you need to call Date or Calendar set methods, you can decorate a Date or Calendar persistent field using @Mutable(value=true).

Note: The @Transformation annotation is optional for transformation mappings: if you specify either a @ReadTransformer, @WriteTransformer or @WriteTransformers annotation,
the mapping would become a transformation mapping by default, without you specifying
the @Transformation annotation.

This table lists attributes of the @Transformation annotation.

Attributes of the @Transformation Annotation

Attribute

Description

Default

Required or Optional

fetch

The javax.persistence.FetchType enumerated type that defines whether EclipseLink should lazily load or eagerly fetch the value of the field or property.

FetchType.EAGER

optional

optional

Set this attribute to define whether or not the value of the field or property may be null.

Note: the value you set is disregarded for primitive types, which are considered mandatory.

How to Use the @ReadTransformer Annotation

Use the @ReadTransformer annotation with the @Transformation mapping to define transformation of one or more database column values into an attribute value. Note that you can only use this annotation if the @Transformation mapping is not write-only.

Set this attribute to the String method name that the mapped class must have. This method does not assign a value to the attribute; instead, it returns the value to be assigned to the attribute.

empty String

required/optional1

transformerClass

Set this attribute to the Class that implements the org.eclipse.persistence.mappings.transformers.AttributeTransformer interface. This will instantiate the class and use its buildAttributeValue method to create the value to be assigned to the attribute.

1 You must specify either the transformerClass or method, but not both

How to Use the @WriteTransformer Annotation

Use the @WriteTransformer annotation with the @Transformation mapping to define transformation of an attribute value to a single database column value. Note that you can only use this annotation if the @Transformation mapping is not read-only.

Set this attribute to the String method name that the mapped class must have. This method returns the value to be written into the database column.

Note: for proper support of DDL generation and returning policy, define the method to return not just an Object, but a particular type, as the following example shows:

public Time getStartTime()

The method may require a @Transient annotation to avoid being mapped as the @Basic by default.

empty String

required/optional 1

transformerClass

Set this attribute to the Class that implements the org.eclipse.persistence.mappings.transformers.FieldTransformer interface. This will instantiate the class and use its buildFieldValue method to create the value to be written into the database column.

How to Use the @VariableOneToOne Annotation

You can use the @VariableOneToOne annotation to map an org.eclipse.persistence.mappings.VariableOneToOneMapping, which you use to represent a pointer references between a Java object and an implementer of an interface. This mapping is typically represented by a single pointer (stored in an instance variable) between the source and target objects. In the relational database tables, these mappings are usually implemented using a foreign key and a type code.

Set this attribute to an array of javax.persistence.CascadeType objects to indicate operations that must be cascaded to the target of the association.

{}

optional

discriminatorClasses

Set this attribute to an array of org.eclipse.persistence.annotations.DiscriminatorClass objects to provide a list of discriminator types that can be used with this variable one-to-one mapping.

If none are specified, then those entities within the persistence unit that implement the target interface will be added to the list of types. In this case, the discriminator type will default as follows:

If the javax.persistence.DiscriminatorColumn type is STRING, it is Entity.name()

If the DiscriminatorColumn type is CHAR, it is the first letter of the Entity class

If the DiscriminatorColumn type is INTEGER it is the next integer after the highest integer explicitly added.

{}

optional

discriminatorColumn

Set this attribute to the javax.persistence.DiscriminatorColumn that will hold the type indicators.

If the discriminator column is not specified, the name of the discriminator column defaults to "DTYPE", and the discriminator type - to STRING.

@javax.persistence.DiscriminatorColumn

optional

fetch

The javax.persistence.FetchType enumerated type that defines whether EclipseLink should lazily load or eagerly fetch the value of the field or property.

FetchType.EAGER

optional

optional

Set this attribute to define whether or not the association is optional.

The following are valid values:

true - The association is optional.

false - A non-null relationship must always exist.

true

optional

targetInterface

Set this attribute to an interface class that is the target of the association.

If not specified, it will be inferred from the type of the object being referenced.

void.class

optional

How to Use the Persistence Unit Properties for Mappings

This table lists the persistence unit properties that you can define in a persistence.xml file to configure EclipseLink mappings.

EclipseLink JPA Persistence Unit Properties for Mappings

Property

Usage

Default

eclipselink.temporal.mutable

Specify whether or not EclipseLink JPA should handle all Date and Calendar persistent fields as mutable objects.

How to Use the @TypeConverter Annotation

The @TypeConverter is an EclipseLink-specific annotation. You can use it to specify an org.eclipse.persistence.mappings.converters.TypeConversionConverter for modification of the data value(s) during the reading and writing of a mapped attribute.

How to Use the @ObjectTypeConverter Annotation

You can use the @ObjectTypeConverter annotation to specify 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.

Set this attribute to the String name for your converter. Ensure that this name is unique across the persistence unit

no default

required

dataType

Set this attribute to the type stored in the database.

void.class1

optional

objectType

Set the value of this attribute to the type stored on the entity.

void.class1

optional

conversionValues

Set the value of this attribute to the array of conversion values (instances of ConversionValue: String objectValue and String dataValue. See the Usage of the @ObjectTypeConverter Annotation example, to be used with the object converter.

no default

required

defaultObjectValue

Set the value of this attribute to the default object value. Note that this argument is for dealing with legacy data if the data value is missing.

empty String

optional

1 The default is inferred from the type of the persistence field or property.

This example shows how to use the @ObjectTypeConverter annotation to specify the Employee field gender.

How to Use the @StructConverter Annotation

The @StructConverter is an EclipseLink-specific annotation. You can add it to an org.eclipse.persistence.platform.database.DatabasePlatform using its addStructConverter method to enable custom processing of java.sql.Struct types.

Using Structure Converters to Configure Mappings

In EclipseLink, a DatabasePlatform (see Database Platforms) holds a structure converter. An org.eclipse.persistence.database.platform.converters.StructConverter affects all objects of a particular type read into the Session that has that DatabasePlatform. This prevents you from configuring the StructConverter on a mapping-by-mapping basis. To configure mappings that use the StructConverter, you call their setFieldType(java.sql.Types.STRUCT) method. You must call this method on all mappings that the StructConverter will affect – if you do not call it, errors might occur.

The JPA specification requires all @Basic mappings (see @Basic) that map to a non-primitive or a non-primitive-wrapper type have a serialized converter added to them. This enables certain STRUCT types to map to a field without serialization.

You can use the existing @Convert annotation with its value attribute set to the StructConverter name – in this case, EclipseLink will apply appropriate settings to the mapping. This setting will be required on all mappings that use a type for which a StructConverter has been defined. Failing to configure the mapping with the @Convert will cause an error.

EclipseLink also provides a number of persistence unit properties that you can specify to configure the EclipseLink cache (see How to Use the Persistence Unit Properties for Caching). These properties may compliment or provide an alternative to the usage of annotations.

How to Use the @Cache Annotation

EclipseLink uses identity maps to cache objects in order to enhance performance, as well as maintain object identity. You can control the cache and its behavior by decorating your entity classes with the @Cache annotation.

Note: If you define the @Cache annotation on an inheritance subclass, the annotation will be ignored.

Attributes of the @Cache Annotation

Attribute

Description

Default

Required or Optional

Override with Persistence Unit Property

type

Set this attribute to the type (org.eclipse.persistence.annotations.CacheType enumerated type) of the cache that you will be using.

The following are the valid values for the CacheType:

FULL – This option provides full caching and guaranteed identity: all objects are cached and not removed. Note: this process may be memory-intensive when many objects are read.

WEAK – This option is similar to FULL, except that objects are referenced using weak references. This option uses less memory than FULL, allows complete garbage collection and provides full caching and guaranteed identity. We recommend using this identity map for transactions that, once started, stay on the server side.

SOFT – This option is similar to WEAK except that the map holds the objects using soft references. This identity map enables full garbage collection when memory is low. It provides full caching and guaranteed identity.

SOFT_WEAK – This option is similar to WEAK except that it maintains a most frequently used subcache that uses soft references. The size of the subcache is proportional to the size of the identity map. The subcache uses soft references to ensure that these objects are garbage-collected only if the system is low on memory. We recommend using this identity map in most circumstances as a means to control memory used by the cache.

HARD_WEAK – This option is similar to SOFT_WEAK except that it maintains a most frequently used subcache that uses hard references. Use this identity map if soft references are not suitable for your platform.

CACHE – With this option, a cache identity map maintains a fixed number of objects that you specify in your application. Objects are removed from the cache on a least-recently-used basis. This option allows object identity for the most commonly used objects. Note: this option furnishes caching and identity, but does not guarantee identity.

NONE – This option does not preserve object identity and does not cache objects. We do not recommend using this option.

Set this attribute to an int value to define the size of cache to use (number of objects).

100

shared

Set this attribute to a boolean value to indicate whether cached instances should be in the shared cache or in a client isolated cache (see Isolated Client Session Cache).

The following are the valid values:

true - use shared cache for cached instances;

false - use client isolated cache for cached instances.

true

optional

expiry

Set this attribute to the int value to enable the expiration of the cached instance after a fixed period of time (milliseconds). Queries executed against the cache after this will be forced back to the database for a refreshed copy.

-1 (no expiry)

optional

expiryTimeOfDay

Set this attribute to a specific time of day (org.eclipse.persistence.annotations.TimeOfDay) when the cached instance will expire. Queries executed against the cache after this will be forced back to the database for a refreshed copy.

@TimeOfDay(specified=false)

optional

alwaysRefresh

Set this attribute to a boolean value of true to force all queries that go to the database to always refresh the cache.

false

optional

refreshOnlyIfNewer

Set this attribute to a boolean value of true to force all queries that go to the database to refresh the cache only if the data received from the database by a query is newer than the data in the cache (as determined by the optimistic locking field).

Note: This option only applies if one of the other refreshing options, such as alwaysRefresh, is already enabled.

What You May Need to Know About Version Fields

By default, EclipseLink persistence provider assumes that the application is responsible for data consistency.

Use the @Version annotation (see Configuring Locking) to enable the JPA-managed optimistic locking by specifying the version field or property of an entity class that serves as its optimistic lock value (recommended).

When choosing a version field or property, ensure that the following is true:

there is only one version field or property per entity;

you choose a property or field persisted to the primary table (see Section 9.1.1 "Table Annotation" of the JPA Specification);

A session cache is a shared cache that services clients attached to a given session. When you read objects from or write objects to the data source using a client session, EclipseLink saves a copy of the objects in the parent server session's cache and makes them accessible to child client sessions. From a JPA perspective, an EntityManagerFactory wraps an org.eclipse.persistence.sessions.server.ServerSession; entity managers wrap an org.eclipse.persistence.sessions.UnitOfWork and org.eclipse.persistence.sessions.server.ClientSession. For more information about sessions, see Introduction to EclipseLink Sessions.

The following are the valid values for the use in a persistence.xml file and for the org.eclipse.persistence.config.CacheType:

Full – This option provides full caching and guaranteed identity: objects are never flushed from memory unless they are deleted.For more information, see Full Identity Map.

Weak – This option is similar to Full, except that objects are referenced using weak references. This option uses less memory than Full, but does not provide a durable caching strategy across client/server transactions. We recommend using this identity map for transactions that, once started, stay on the server side.For more information, see Weak Identity Map.

Soft – This option is similar to Weak except that the map holds the objects using soft references. This identity map enables full garbage collection when memory is low. It provides full caching and guaranteed identity.For more information, see Soft Identity Map.

SoftWeak – This option is similar to Weak except that it maintains a most frequently used subcache that uses soft references. We recommend using this identity map in most circumstances as a means to control memory used by the cache.For more information, see Soft Cache Weak Identity Map and Hard Cache Weak Identity Map.

The default for whether or not the EclipseLink session cache is shared by multiple client sessions.

The following are the valid values:

true – The session cache services all clients attached to the session. When you read objects from or write objects to the data source using a client session, EclipseLink saves a copy of the objects in the parent server session's cache and makes them accessible to all other processes in the session.

false – The session cache services a single, isolated client exclusively. The isolated client can reference objects in a shared session cache but no client can reference objects in the isolated client's exclusive cache.

The maximum number of JPA entities of the type denoted by JPA entity name <ENTITY> allowed in an EclipseLink cache. For more information on entity names, see Section 8.1 "Entity" of the JPA Specification.

Whether or not the EclipseLink session cache is shared by multiple client sessions for JPA entities of the type denoted by JPA entity name <ENTITY>.For more information on entity names, see Section 8.1 "Entity" of the JPA Specification.

The following are the valid values:

true – The session cache services all clients attached to the session. When you read objects from or write objects to the data source using a client session, EclipseLink saves a copy of the objects in the parent server session's cache and makes them accessible to all other processes in the session.

false – The session cache services a single, isolated client exclusively. The isolated client can reference objects in a shared session cache but no client can reference objects in the isolated client's exclusive cache.

Defines the EntityManager cache behaviour after a call to the flush method followed by a call to the clear method. You can specify this property while creating either an EntityManagerFactory (either in the map passed to the createEntityManagerFactory method, or in the persistence.xml file), or an EntityManager (in the map passed to the createEntityManager method). Note that the latter overrides the former.

The following are the valid values for the use in a persistence.xml file and for the org.eclipse.persistence.config.FlushClearCache:

Drop – The call to the clear method results in a drop of the entire EntityManager’s cache. This mode is the fastest and uses the least memory. However, after commit the shared cache might potentially contain stale data.

DropInvalidate – Even though the call to the clear method results in a drop of the entire EntityManager’s cache, classes that have at least one object updated or deleted are invalidated in the shared cache at commit time. This mode is slower than Drop, but as efficient memory usage-wise, and prevents stale data.

Merge – The call to the clear method results in a drop from the EntityManager’s cache of objects that have not been flushed. This mode leaves the shared cache in a perfect state after commit. However, it is the least memory-efficient mode; the memory might even run out in a very large transaction.

Set this attribute to the type (org.eclipse.persistence.annotations.ExistenceType enumerated type) of the existence checking that you will be using to determine if an insert or an update operation should occur for an object.

The following are the valid values for the ExistenceType:

CHECK_CACHE – This option assumes that if the object's primary key does not include null and it is in the cache, then this object must exist.

CHECK_DATABASE – This option triggers the object existence check on a database.

ASSUME_EXISTENCE – This option assumes that if the object's primary key does not include null, then the object must exist.You may choose this option if your application guarantees the existence checking, or is not concerned about it.

ASSUME_NON_EXISTENCE – This option assumes that the object does not exist.You may choose this option if your application guarantees the existence checking, or is not concerned about it.If you specify this option, EclipseLink will force the call of an insert operation.

One of the following default values applies:

ExistenceType.CHECK_CACHE - If either an @ExistenceChecking annotation or an XML element exists, but the value attribute is not set.

How to Use the @Customizer Annotation

Use the @Customizer annotation to specify a class that implements the org.eclipse.persistence.config.DescriptorCustomizer interface and that is to be run against a class' descriptor after all metadata processing has been completed. See eclipselink.descriptor.customizer.<ENTITY> for more information.

Specify an EclipseLink exception handler class: a Java class that implements the org.eclipse.persistence.exceptions.ExceptionHandler interface and provides a default (zero-argument) constructor. Use this class’ handleException method, which takes a java.lang.RuntimeException, to rethrow the exception, throw a different exception, or retry a query or a database operation.

Control whether or not the weaving of the entity classes is performed. The EclipseLink JPA persistence provider uses weaving to enhance JPA entities for such things as lazy loading, change tracking, fetch groups, and internal optimizations.

The following are the valid values:

true – weave entity classes dynamically.

false – do not weave entity classes.

static – weave entity classes statically.

This assumes that classes have already been statically woven. Run the static weaver on the classes before deploying them.

true – enable the AttributeLevelChangeTracking through weaving. When enabled, only classes with all mappings allowing change tracking have change tracking enabled.

false – disable the AttributeLevelChangeTracking through weaving. Use this setting if the following applies:

you cannot weave at all;

you do not want your classes to be changed during weaving (for example, for debugging purposes);

you wish to disable this feature for configurations that do not support it (for example, you are mutating the java.util.Date or java.util.Calendar, you are using property access but modifying the underlying instance variables).

Note: you may set this option only if the eclipselink.weaving option is set to true. The purpose of the eclipselink.weaving.changetracking option is to provide more granular control over weaving.

Specify an EclipseLink descriptor customizer class – a Java class that implements the org.eclipse.persistence.config.DescriptorCustomizer interface and provides a default (zero-argument) constructor. Use this class's customize method, which takes an org.eclipse.persistence.descriptors.ClassDescriptor, to programmatically access advanced EclipseLink descriptor and mapping API for the descriptor associated with the JPA entity named <ENTITY>.

For more information on entity names, see Section 8.1 "Entity" of the JPA Specification

QueryMonitor – Monitor query executions and cache hits (org.eclipse.persistence.tools.profiler.QueryMonitor class).This option provides a simple low-overhead means for measuring performance of query executions and cache hits. You may want to use this option for performance analysis in a complex system.

NoProfiler – Do not use a performance profiler.

Custom profiler – Use your own custom profiler class. Create it by implementing the org.eclipse.persistence.sessions.SessionProfiler interface and providing a no-argument constructor.

Specify whether or not the Java VM is allowed to manage the number of objects within the persistence context using Java’s weak references.

In cases where your application cannot use the EntityManagerclear method to clear an extended persistence context, use this setting to enable the VM to remove unreferenced and unchanged objects from the persistence context, resulting in making resources available for other uses.

You can set this property either during the EntityManagerFactorycreateEntityManager(Map) call, or globally in the persistence.xml file.

The following are the valid values for the use in a persistence.xml file and for the org.eclipse.persistence.sessions.factories.ReferenceMode:

HARD - Use this option to specify that all references to all objects will be through hard references. These objects will not be available for garbage collection until the referencing artifact (such as persistence context or unit of work) is released/cleared or closed.

WEAK - Use this option to specify that references to objects supporting active attribute change tracking (see Attribute Change Tracking Policy) will be held by weak references. That is, any object no longer referenced directly or indirectly will be available for garbage collection. When a change is made to a change-tracked object, that object is moved to a hard reference and will not be available for garbage collection until flushed.New and removed objects, as well as objects that do not support active attribute change tracking, will also be held by hard references and will not be available for garbage collection.

FORCE_WEAK - Use this option to specify that all objects, including non-change-tracked objects, are to be held by weak references. When a change is made to a change-tracked object, that object is moved to a hard reference and will not be available for garbage collection until flushed. However, any objects that do not support active attribute change tracking may be garbage collected before their changes are flushed to a database, which can potentially result in a loss of changes.New and removed objects will be held by hard references and will not be available for garbage collection.

Using Java, you can configure reference mode through the EclipseLink Session's acquireUnitOfWork(ReferenceMode mode) method. To specify a persistence unit- or session-wide default, use the Session's setDefaultReferenceMode method.

Set this attribute to the String method name that EclipseLink will use to create a clone to enable comparison by EclipseLink's deferred change detection policy) that you want to apply to your entity's descriptor.

Note: you have to set either this attribute, or the workingCopyMethod, or both.

no default

optional/required

workingCopyMethod

Set this attribute to the String method name that EclipseLink will use to create the object returned when registering an Object in an EclipseLink unit of work.

Note: you have to set either this attribute, or the method, or both.

no default

optional/required

How to Use the @InstantiationCopyPolicy Annotation

Instantiation copy policy is the default copy policy in EclipseLink. Use the @InstantiationCopyPolicy annotation to override other types of copy policies for an Entity.

Using EclipseLink JPA Extensions for Returning Policy

The returning policy enables INSERT or UPDATE operations to return values back into the object being written. These values include table default values, trigger or stored procedures computed values. For more information, see Configuring Returning Policy.

Using EclipseLink JPA Extensions for Optimistic Locking

How to Use the @OptimisticLocking Annotation

You can use the @OptimisticLocking annotation to specify the type of optimistic locking that EclipseLink should use when updating or deleting entities.

Note: EclipseLink supports additional optimistic locking policies beyond what is supported through the JPA specification (such as @Version - see Section 9.1.17 "Version Annotation" of the JPA Specification). When mapping to a database schema where a version column does not exist and cannot be added, these locking policies enable the concurrency protection.

Set this attribute to the type (org.eclipse.persistence.annotations.OptimisticLockingType enumerated type) of the optimistic locking policy that you will be using.

The following are the valid values for the OptimisticLockingType:

ALL_COLUMNS – Use this type of locking policy to compare every field in the table in the WHERE clause during an update or a delete operation. If any field has been changed, EclipseLink will throw an optimistic locking exception.

CHANGED_COLUMNS – Use this type of locking policy to compare changed fields in the table in the WHERE clause during an update operation. If any field has been changed, EclipseLink will throw an optimistic locking exception.

Note: performing the same during a delete operation will only compare primary keys.

SELECTED_COLUMNS – Use this type of locking policy to compare selected fields in the table in the WHERE clause during an update or a delete operation. If any field has been changed, EclipseLink will throw an optimistic locking exception.

Note: specified fields must be mapped and must not be primary keys.

Note: EclipseLink will throw an exception if you set the SELECTED_COLUMNS type, but fail to specify the selectedColumns. You must also specify the name attribute of the Column.

VERSION_COLUMN – Use this type of locking policy to compare a single version number in the WHERE clause during an update operation.

Note: the version field must be mapped and must not be the primary key.

Note: this functionality is equivalent to the functionality of the @Version annotation (see Section 9.1.17 "Version Annotation" of the JPA Specification) in JPA. If you use this option, you must also provide the @Version annotation on the version field or property.For more information, see What You May Need to Know About Version Fields.

OptimisticLockingType.VERSION_COLUMN

optional

selectedColumns

Set this attribute to an array of javax.persistence.Column instances.

For an optimistic locking policy of type SELECTED_COLUMNS, this annotation member becomes a required field.

Note: EclipseLink will throw an exception if you set the SELECTED_COLUMNS type, but fail to specify the selectedColumns. You must also specify the name attribute of the Column.

empty Column array

optional

cascade

Set the value of this attribute to a boolean value of true to specify that the optimistic locking policy should cascade the lock.

By enabling cascading you configure EclipseLink to automatically force a version field update on a parent object when its privately owned child object's version field changes.

Note: In the current release, only supported with VERSION_COLUMN locking.

Note: Setting an @OptimisticLocking may override any @Version specification (see Section 9.1.17 "Version Annotation" of the JPA Specification) on the entity: EclipseLink will not throw an exception, but will log a warning.

You can specify @Version without any @OptimisticLocking specification to define a version locking policy (org.eclipse.persistence.descriptors.VersionLockingPolicy) on the source entity.

This example shows how to use the @OptimisticLocking annotation with the ALL_COLUMNS type.

Using EclipseLink JPA Extensions for JDBC

EclipseLink JPA provides persistence unit properties that you can define in a persistence.xml file to configure how EclipseLink will use the connections returned from the data source used. These properties are divided into the two following categories:

You can set this property while creating either an EntityManagerFactory (either in the map passed to the createEntityManagerFactory method, or in the persistence.xml file), or an EntityManager (in the map passed to the createEntityManager method). Note that the latter overrides the former.

The following are the valid values for the use in a persistence.xml file and for the org.eclipse.persistence.config.ExclusiveConnectionMode:

Transactional - Create an isolated client session (see Isolated Client Sessions) if some or all entities require isolated cache 4 ; otherwise, create a client session.Note: EclipseLink keeps the connection exclusive for the duration of the transaction. Inside the transaction, EclipseLink performs all writes and reads through the exclusive connection. However, outside the Eclipelink transaction, a new connection is acquired from the connection pool for each read and released back immediately after the query is executed.

Isolated - Create an exclusive isolated client session if reading an isolated Entity; otherwise, raise an error.Note: EclipseLink keeps the connection exclusive for the lifetime of the owning EntityManager. Inside the transaction, EclipseLink performs all writes and reads through the exclusive connection. However, outside the Eclipelink transaction only isolated entities are read through the exclusive connection; for nonisolated entities, a new connection is acquired from the connection pool for each read and released back immediately after the query is executed.

Always - Create an exclusive isolated client session (see Isolated Client Sessions) if reading an isolated Entity; otherwise, create an exclusive client session.Note: EclipseLink keeps the connection exclusive for the lifetime of the owning EntityManager and performs all writes and reads through the exclusive connection.

1 This property applies when used in a Java SE environment.2 This property applies when used both in a Java SE and Java EE environment.3 This property applies when used in a Java SE environment or a resource-local persistence unit (see Section 5.5.2 "Resource-Local Entity Managers" and Section 6.2.1.2 "transaction-type" of the JPA Specification).4 To do this, set the eclipselink.cache.shared.<ENTITY> property for one or more entities to false; Use the eclipselink.cache.shared.default property if you want to use the isolated cache for all entities.

For information about the use of annotations as opposed to persistence unit properties and vice versa, see the following:

ServerLogger – the java.util.logging logger org.eclipse.persistence.platform.server.ServerLog. Integrates with the application server's logging as define in the org.eclipse.persistence.platform.server.ServerPlatform.

Fully qualified class name of a custom logger. The custom logger must implement the org.eclipse.persistence.logging.SessionLog interface.

Control whether the exceptions thrown from within the EclipseLink code are logged prior to returning the exception to the calling application. Ensures that all exceptions are logged and not masked by the application code.

This table lists the EclipseLink JPA persistence unit properties that you can define in a persistence.xml file to configure EclipseLink extensions for session, as well as the target database and application server.

Specify the name by which the EclipseLink session is stored in the static session manager. Use this option if you need to access the EclipseLink shared session outside of the context of the JPA or to use a pre-existing EclipseLink session configured through an EclipseLink sessions.xml file.

Valid values: a valid EclipseLink session name that is unique in a server deployment.

You can use this option as an alternative to annotations and deployment XML. If you specify this property, EclipseLink will override all class annotation and the object relational mapping from the persistence.xml, as well as ORM.xml and other mapping files, if present. For more information, see hat You May Need to Know About EclipseLink JPA Overriding Mechanisms.

Indicate the session by setting the eclipselink.session-name property.

Note: If you do not specify the value for this property, sessions.xml file will not be used.

The following are the valid values for the use in a persistence.xml file and for the org.eclipse.persistence.config.TargetDatabase:

Attunity – configure the persistence provider to use an Attunity database.

Auto – EclipseLink accesses the database and uses the metadata that JDBC provides to determine the target database. Applicable to JDBC drives that support this metadata.

Cloudscape – configure the persistence provider to use a Cloudscape database.

Database – configure the persistence provider to use a generic choice if your target database is not listed here and your JDBC driver does not support the use of metadata that the Auto option requires.

DB2 – configure the persistence provider to use a DB2 database.

DB2Mainframe – configure the persistence provider to use a DB2Mainframe database.

DBase – configure the persistence provider to use a DBase database.

Derby – configure the persistence provider to use a Derby database.

HSQL – configure the persistence provider to use an HSQL database.

Informix – configure the persistence provider to use an Informix database.

JavaDB – configure the persistence provider to use a JavaDB database.

MySQLPlatform – configure the persistence provider to use a MySQLPlatform database.

Oracle – configure the persistence provider to use an Oracle Database.

PointBase – configure the persistence provider to use a PointBase database.

PostgreSQL – configure the persistence provider to use a PostgreSQL database.

SQLAnywhere – configure the persistence provider to use an SQLAnywhere database.

SQLServer – configure the persistence provider to use an SQLServer database.

Sybase – configure the persistence provider to use a Sybase database.

TimesTen – configure the persistence provider to use a TimesTen database.

You can also set the value to the fully qualified classname of a subclass of the org.eclipse.persistence.platform.DatabasePlatform class.

The following are the valid values for the org.eclipse.persistence.config.PersistenceUnitProperties:

NONE – see none.

CREATE_ONLY – see create-tables.

DROP_AND_CREATE – see drop-and-create-tables.

If you are using persistence in a Java SE environment and would like to create the DDL files without creating tables, additionally define a Java system property INTERACT_WITH_DB and set its value to false.

Valid values: a file specification to a directory in which you have write access. The file specification may be relative to your current working directory or absolute. If it does not end in a file separator, EclipseLink will append one valid for your operating system.

"."+File.separator or <tt>PersistenceUnitProperties.DEFAULT_APP_LOCATION</tt>

eclipselink.create-ddl-jdbc-file-name

Specify the file name of the DDL file that EclipseLink generates containing SQL statements to create tables for JPA entities. This file is written to the location specified by eclipselink.application-location when eclipselink.ddl-generation is set to create-tables or drop-and-create-tables.

How to Use the @ChangeTracking Annotation

Note: This is an optimization feature that lets you tune the way EclipseLink detects changes. You should choose the strategy based on the usage and data modification patterns of the entity type as different types may have different access patterns and hence different settings, and so on.

OBJECT – This option uses weaving to detect if the object has been changed, but uses a backup copy of the object to determine what fields or properties changed. This is more efficient than the DEFERRED option, but less efficient than the ATTRIBUTE option. You must enable weaving to use this option. This option supports additional mapping configuration to attribute.

DEFERRED – This option defers all change detection to the UnitOfWork's change detection process. This option uses a backup copy of the object to determine which fields or properties changed. This is the least efficient option, but does not require weaving and supports additional mapping configurations to attribute and object.

AUTO – This option does not set any change tracking policy. The policy is determined by the EclipseLink agent: if the class can be weaved for change tracking the ATTRIBUTE option is used; otherwise, the DEFERRED option is used.AUTO is the only change tracking value where EclipseLink chooses the value; any other value will explicitly cause EclipseLink to use that value, so if you decide to explicitly set it, you must set it correctly and use your model correctly to ensure the change tracking detects your changes.

Note: For every option, objects with changed attributes will be processed at the commit time to include any changes in the results of the commit. Unchanged objects will be ignored.

Note: The weaving of change tracking is the same for attribute and object change tracking.

The attribute change tracking will not detect object changes made through reflection or direct field access to fields mapped as properties.

How to Use the Persistence Unit Properties for Change Tracking

This table lists the persistence unit properties that you can define in a persistence.xml file to configure EclipseLink change tracking.

EclipseLink JPA Persistence Unit Properties for Change Tracking

Property

Usage

Default

eclipselink.weaving.changetracking

Enable or disable the AttributeLevelChangeTracking through weaving.

The following are the valid values:

true – enable the AttributeLevelChangeTracking through weaving. When enabled, only classes with all mappings allowing change tracking have change tracking enabled.

false – disable the AttributeLevelChangeTracking through weaving. Use this setting if the following applies:

you cannot weave at all;

you do not want your classes to be changed during weaving (for example, for debugging purposes);

you wish to disable this feature for configurations that do not support it (for example, you are mutating the java.util.Date or java.util.Calendar, you are using property access but modifying the underlying instance variables).

Note: you may set this option only if the eclipselink.weaving option is set to true. The purpose of the eclipselink.weaving.changetracking option is to provide more granular control over weaving.

Even if the descriptors contain mappings that are not directly supported by change tracking weaving, EclipseLink assumes that you will either use your set methods to ensure that your changes are captured, or raise the events for these mappings.

ATTRIBUTE

false

Do not weave change tracking.

You must implement the org.eclipse.persistence.annotations.ChangeTracking interface and raise the change events. Otherwise, an error will occur on descriptor initialization.

OBJECT

true

Object change tracking is used and change tracking is woven.

Note: Weaving is identical for object and attribute change tracking.

OBJECT

false

Do not weave change tracking.

You must implement the org.eclipse.persistence.annotations.ChangeTracking interface and raise the change events. Otherwise, an error will occur on descriptor initialization.

DEFERRED

true

Do not weave change tracking.

Deferred change tracking is used.

DEFERRED

false

Do not weave change tracking.

Deferred change tracking is used.

AUTO

true

Weave change tracking if the descriptor does not use any mappings that do not support change tracking.

Cache Usage

The eclipselink.cache-usage hint specifies how the query should interact with the EclipseLink cache.

EclipseLink JPA uses a shared cache mechanism that is scoped to the entire persistence unit. When operations are completed in a particular persistence context, the results are merged back into the shared cache so that other persistence contexts can use them. This happens regardless of whether the entity manager and persistence context are created in Java SE or Java EE. Any entity persisted or removed using the entity manager will always be kept consistent with the cache.

The following are the valid values for the org.eclipse.persistence.config.CacheUsage:

DoNotCheckCache – Always go to the database.

CheckCacheByExactPrimaryKey – If a read-object query contains an expression where the primary key is the only comparison, you can obtain a cache hit if you process the expression against the object in memory

CheckCacheByPrimaryKey – If a read-object query contains an expression that compares at least the primary key, you can obtain a cache hit if you process the expression against the objects in memory.

CheckCacheThenDatabase – You can configure any read-object query to check the cache completely before you resort to accessing the database.

CheckCacheOnly – You can configure any read-all query to check only the parent session cache (shared cache) and return the result from it without accessing the database.

ConformResultsInUnitOfWork – You can configure any read-object or read-all query within the context of a unit of work to conform the results with the changes to the object made within that unit of work. This includes new objects, deleted objects and changed objects.For more information, see Using Conforming Queries and Descriptors.

UseEntityDefault – Use the cache configuration as specified by the EclipseLink descriptor API for this entity.Note: the entity default value is to not check the cache (DoNotCheckCache). The query will access the database and synchronize with the cache. Unless refresh has been set on the query, the cached objects will be returned without being refreshed from the database. EclipseLink does not support the cache usage for native queries or queries that have complex result sets such as returning data or multiple objects.

Default:
CacheUsage.UseEntityDefaultNote: this default is DoNotCheckCache.

Query Type

The eclipselink.query-type hint specifies the EclipseLink query type to use for the query.

For most JP QL queries, the org.eclipse.persistence.queries.ReportQuery or org.eclipse.persistence.queries.ReadAllQuery are used. The eclipselink.query-type hint lets you use other query types, such as org.eclipse.persistence.queries.ReadObjectQuery for queries that are know to return a single object.

Fetch Size

The eclipselink.jdbc.fetch-size hint specifies the number of rows that should be fetched from the database when more rows are needed1

For large queries that return a large number of objects you can configure the row fetch size used in the query to improve performance by reducing the number database hits required to satisfy the selection criteria. Most JDBC drivers default to a fetch size of 10, so if you are reading 1000 objects, increasing the fetch size to 256 can significantly reduce the time required to fetch the query's results. The optimal fetch size is not always obvious. Usually, a fetch size of one half or one quarter of the total expected result size is optimal. Note that if you are unsure of the result set size, incorrectly setting a fetch size too large or too small can decrease performance.

A value of 0 means the JDBC driver default will be used.

Valid values: 0 to Integer.MAX_VALUE (depending on your JDBC driver) as a String.

Default: 0

Note: this value indicates that the JDBC driver default will be used.

1 This property is dependent on the JDBC driver support.

Timeout

The eclipselink.jdbc.timeout hint specifies the number of seconds EclipseLink will wait on a query before throwing a DatabaseException1

A value of 0 means EclipseLink will never time-out a query.

Valid values: 0 to Integer.MAX_VALUE (depending on your JDBC driver) as a String.

Default: 0

1 This property is dependent on the JDBC driver support.

Pessimistic Lock

The eclipselink.pessimistic-lock hint controls whether or not pessimistic locking is used.

The following are the valid values for the org.eclipse.persistence.config.PessimisticLock:

Batch

The eclipselink.batch hint supplies EclipseLink with batching information so subsequent queries of related objects can be optimized in batches instead of being retrieved one-by-one or in one large joined read. Batch reading is more efficient than joining because it avoids reading duplicate data.

Batching is only allowed on queries that have a single object in their select clause.

Read Only

The eclipselink.read-only hint retrieves read-only results back from the query: on nontransactional read operations, where the requested entity types are stored in the shared cache, you can request that the shared instance be returned instead of a detached copy.

Note: you should never modify objects returned from the shared cache.

The following are the valid values for the org.eclipse.persistence.config.HintValues:

Result Collection Type

The eclipselink.result-collection-type hint configures the concrete class that EclipseLink should use to return its query result.

This lets you specify the type of collection in which the result will be returned.

Valid values: Java Class that implements the Collection interface.

Note: typically, you would execute these queries by calling the getResultsList method, which returns the java.util.List, on the Query. This means that the class specified in this hint must implement the List interface, if you are invoking it using the getResultsList method.

Note: specify the class without the ".class" notation. For example, java.util.Vector would work, not java.util.Vector.classEclipseLink will throw an exception, if you use this hint with a class that does not implement the Collection interface.

EclipseLink expressions offer the following advantages over SQL when you access a database:

Expressions are easier to maintain because the database is abstracted.

Changes to descriptors or database tables do not affect the querying structures in the application.

Expressions enhance readability by standardizing the Query interface so that it looks similar to traditional Java calling conventions.For example, the Java code required to get the street name from the Address object of the Employee class looks like this:

emp.getAddress().getStreet().equals("Meadowlands");

The expression to get the same information is similar:

emp.get("address").get("street").equal("Meadowlands");

Expressions allow read queries to transparently query between two classes that share a relationship. If these classes are stored in multiple tables in the database, EclipseLink automatically generates the appropriate join statements to return information from both tables.

Expressions simplify complex operations.For example, the following Java code retrieves all employees that live on "Meadowlands" whose salary is greater than 10,000:

The following example shows how to cast a JPA query from an entity manager to access an EclipseLink persistence provider setDatabaseQuery method that takes an EclipseLink DataReadQuery initialized with an EclipseLink SQLCall object that specifies a SELECT. This query will return one or more objects.

The following example shows how to cast a JPA query from an entity manager to access an EclipseLink persistence provider setDatabaseQuery method that takes an EclipseLink DataModifyQuery initialized with an EclipseLink SQLCall object that specifies an UPDATE. This query will modify one or more objects; however, this query will not update the managed objects within the persistence context.

Creating a JPA Query Using an EclipseLink Call Object

Using DatabaseQuery method setCall, you can define your own EclipseLink Call to accommodate a variety of data source options, such as SQL stored procedures and stored functions, EJB QL queries, and EIS interactions.

This example shows how to cast a JPA query from an entity manager to access an EclipseLink persistence provider getDatabaseQuery method to set a new SQLCall.

You can easily re-use the same parameter in more than one place in the query, as the following example shows. In this example, the query string will be SELECT * FROM EMPLOYEE WHERE F_NAME LIKE "D%" AND L_NAME LIKE "D%".

Using JDBC-Style Positional Parameters in a Native Query

Using EclipseLink, you can specify positional parameters in a native query using the JDBC-style positional parameter ? convention.

This example shows how to specify positional parameters using the ? convention. Each occurrence of ? must be matched by a corresponding setParameter call. In this example, the query string will be SELECT * FROM EMPLOYEE WHERE F_NAME LIKE "D%" AND L_NAME LIKE "C%".

If you want to re-use the same parameter in more than one place in the query, you must repeat the same parameter, as this example shows. In this example, the query string will be SELECT * FROM EMPLOYEE WHERE F_NAME LIKE "D%" AND L_NAME LIKE "D%".

How to Configure Dynamic Weaving for JPA Entities Using the EclipseLink Agent

Use this option to weave applicable class files one at a time, as they are loaded at run time. Consider this option when the number of classes to weave is few or the time taken to weave the classes is short.

EclipseLink weaves applicable class files one at a time, as they are loaded at run time.

How to Configure Static Weaving for JPA Entities

Use this option to weave all applicable class files at build time so that you can deliver pre-woven class files. Consider this option to weave all applicable class files at build time so that you can deliver prewoven class files. By doing so, you can improve application performance by eliminating the runtime weaving step required by dynamic weaving (see How to Configure Dynamic Weaving for JPA Entities Using the EclipseLink Agent).

In addition, consider using this option to weave in Java environments where you cannot configure an agent.

Note: If source and target point to the same location and, if the source is a directory (not a JAR file), EclipseLink will weave in place. If source and target point to different locations, or if the source is a JAR file (as the EclipseLink weave Ant Task example shows), EclipseLink cannot weave in place.

Configure the weave task with an appropriate <classpath> element, as the EclipseLink weave Ant Task example shows, so that EclipseLink can load all required source classes.

Execute the Ant task using the command line that this example shows.In this example, the weave Ant task is in the build.xml file: EclipseLink weave Ant Task Command Line

ant -lib C:\eclipselink.jar -f build.xml weave

Note: You must specify the eclipselink.jar file (the JAR that contains the EclipseLink weave Ant task) using the Ant command line -lib option instead of using the taskdef attribute classpath.

Specifies the location of the Java source files to weave: either a directory or a JAR file.

If the persistence.xml file is not in this location, you must specify the location of the persistence.xml using the -persistenceinfo attribute.

Required

<target>

Specifies the output location: either a directory or a JAR file.

Required

Note: If <source> and <target> point to the same location and if the <source> is a directory (not a JAR file), EclipseLink will weave in place. If <source> and <target> point to different locations, or if the source is a JAR file (as the Executing StaticWeave on the Command Line example shows), EclipseLink cannot weave in place.

Configure your persistence.xml file with a eclipselink.weaving extension set to static, as this example shows: Setting eclipselink.weaving in the persistence.xml File

What You May Need to Know About EclipseLink JPA Lazy Loading

JPA specifies that lazy loading is a hint to the persistence provider that data should be fetched lazily when it is first accessed, if possible.

If you are developing your application in a Java EE environment, you only have to set fetch to javax.persistence.FetchType.LAZY, and EclipseLink persistence provider will supply all the necessary functionality.

When using a one-to-one or many-to-one mapping in a Java SE environment, to configure EclipseLink JPA to perform lazy loading when the fetch attribute is set to FetchType.LAZY, configure either dynamic or static weaving.

When using a one-to-one or many-to-one mapping in a Java SE environment that does not permit the use of -javaagent on the JVM command line, to configure EclipseLink JPA to perform lazy loading when annotation attribute fetch is set to javax.persistence.FetchType.LAZY, you can use static weaving.

All object relational XML metadata is contained within the entity-mappings root element of the mapping file. The subelements of entity-mappings can be categorized into four main scoping and functional groups: persistence unit defaults, mapping file defaults, queries and generators, and managed classes and mappings. There is also a special setting that determines whether annotations should be considered in the metadata for the persistence unit (see Disabling Annotations).

For more information and examples, see Section 10.1 "XML Overriding Rules" of the JPA Specification.

Disabling Annotations

JPA provides a mechanism that you can use to disable annotations. If you do not feel the need for annotations in your application, you can use the xml-mapping-metadata-complete and metadata-complete mapping file elements to disable any existing annotations. Setting this options causes the processor to completely ignore annotations.

When you specify the xml-mapping-metadata-complete element, all annotations in the persistence unit will be ignored, and only mapping files in the persistence unit will be considered as the total set of provided metadata. Only entities (see Section 8.1 "Entity" of the JPA Specification), mapped superclasses (see @MappedSuperclass), and embedded objects (see @Embedded) that have entries in a mapping file will be added to the persistence unit. The xml-mapping-metadata-complete element has to be in only one of the mapping files in the persistence unit. You specify it as an empty subelement of the persistence-unit-metadata element, as this example shows:

You can also use the metadata-complete attribute of the entity, mapped-superclass, and embeddable elements. If you specify this attribute, all annotations on the specified class and on any fields or properties in the class will be ignored – only metadata in the mapping file will be considered as the set of metadata for the class. However, even though the annotations are ignored, the default mapping still applies, so any fields or properties that should not be mapped must still be marked as transient in the XML file, as this example demonstrates.

In the preceding example, the entity mappings in the annotated class are disabled by the metadata-complete attribute, and because the fields are not mapped in the mapping file, the default mapping values will be used. The name and salary fields will be mapped to the NAME and SALARY columns, respectively.

For more information, see Section 10.1 "XML Overriding Rules" of the JPA Specification.

Advantages and Disadvantages of Using Annotations

Metadata annotations are relatively simple to use and understand. They provide in-line metadata located with the code that this metadata is describing – you do not need to replicate the source code context of where the metadata applies.

On the other hand, annotations unnecessarily couple the metadata to the code. Thus, changes to metadata require changing the source code.

Advantages and Disadvantages of Using XML

The following are the advantages of using XML:

no coupling between the metadata and the source code;

compliance with the existing, pre-EJB 3.0 development process;

support in IDEs and source control systems.

The main disadvantages of mapping with XML are the complexity and the need for replication of the code context.

Similar to EclipseLink annotations, properties expose some features of EclipseLink that are currently not available through the use of JPA metadata.

Note: If multiple instances of the same property are set, then EclipseLink will use the values from the last entry in the list. However, the properties Map provided in the createEntityManagerFactory method will always have precedence.

You can also specify the persistence information in the EclipseLink session configuration file – sessions.xml (see Session Configuration and the sessions.xml File). By setting the eclipselink.sessions-xml persistence unit property you enable EclipseLink to replace all class annotations and object relational mappings that you defined in the persistence.xml file, as well as mapping files (if present). Through the sessions.xml file the eclipselink.sessions-xml property lets you provide session-level configurations that are not supported by persistence unit properties (for example, cache coordination).

Note: You can use the eclipselink.sessions-xml property as an alternative to annotations and deployment XML.

For more information on creating and configuring the sessions.xml file, see the following:

In summary, EclipseLink JPA possesses an overriding mechanism that you can use in the following ways:

You can combine the use of JPA annotations, object relational mapping files (such as orm.xml) and persistence unit properties.In this case, EclipseLink persistence provider builds metadata starting with applying defaults, then JPA annotations, and then overrides that with elements of the object relational mapping file. This results in creation of an in-memory EclipseLink session and project. Then EclipseLink persistence provider applies persistence unit properties specified in persistence.xml file, as the following illustration shows.

Alternatively, you can set a vendor extensions in the Map of properties you pass into a call to javax.persistence.Persistence method createEntityManagerFactory, as the Configuring a Vendor Extension when Creating an EntityManagerFactory example shows. You can override extensions set in the persistence.xml file in this way. When you set an extension in a map of properties, you can set the value using the public static final field in the appropriate configuration class in org.eclipse.persistence.config, including the following:

CacheType

TargetDatabase

TargetServer

PersistenceUnitProperties

The following example shows how to set the value of extension eclipselink.cache.type.default using the CacheType configuration class.