Java Persistence API (JPA) Extensions Reference for EclipseLink, Release 2.6
  Go To Table Of Contents
 Search
 PDFComments
Comments
Previous Next  

5 Persistence Property Extensions Reference

This chapter describes the persistence property extensions.You configure persistence units in the JPA persistence descriptor file: persistence.xml. EclipseLink includes many persistence property enhancements and extensions that can be configured in the persistence.xml file.

This chapter includes the following sections:

Functional Listing of Persistence Property Extensions

The following lists the EclipseLink persistence property (persistence.xml file) extensions, categorized by function:

Weaving

EclipseLink includes the following persistence property extensions for weaving:

Customizers

EclipseLink includes the following persistence property extensions for customizing descriptors and sessions:

Validation and Optimization

EclipseLink includes the following persistence property extensions for validation.

Logging

EclipseLink includes the following persistence property extensions for logging.

Caching

EclipseLink includes the following persistence property extensions for caching:

Mapping

EclipseLink includes the following persistence property extensions for mappings:

Schema generation

EclipseLink includes the following persistence property extensions for mappings:

JDBC configuration

EclipseLink includes the following persistence property extensions for configuring JDBC connections and connection pooling:

Concurrency manager

EclipseLink includes the following persistence property extensions for concurrency management:

Alphabetical Listing of Persistence Property Extensions

The following lists the EclipseLink persistence property (persitence.xml file) extensions, in alphabetical order:

application-location

Use the eclipselink.application-location property to specify the file system directory in which EclipseLink writes (outputs) DDL files.


Values

Table 5-1 describes this persistence property's values.

Table 5-1 Valid Values for application-location

Value Description

value

Directory location. The path must be fully qualified. For Windows, use a backslash. For UNIX use a slash.


Usage

You may set this option only if the value of eclipselink.ddl-generation.output-mode is sql-script or both.


Examples

Example 5-1 shows how to use this property in the persistence.xml file.

Example 5-1 Using application-location in persistence.xml

<property name="eclipselink.application-location" value="c:/YOURDIRECTORY/"/>

Example 5-2 shows how to use this property in a property map.

Example 5-2 Using application-location in a Property Map

import org.eclipse.persistence.config.PersistenceUnitProperties;
propertiesMap.put(PersistenceUnitProperties.APPLICATION_LOCATION,
"c:/YOURDIRECTORY/");


See Also

For more information, see:

cache.coordination.channel

Use the eclipselink.cache.coordination.channel property to configure cache coordination for a clustered environment.


Values

Table 5-2 describes this persistence property's values.

Table 5-2 Valid Values for cache.coordination.channel

Value Description

channel name

The channel used for cache coordination. All persistence units using the same channel will be coordinated.

Default: EclipseLinkCommandChannel


Usage

If multiple EclipseLink deployments reside on the same network, they should be in different channels.


Examples

Example 5-3 shows how to use this property in the persistence.xml file.

Example 5-3 Using application-location in persistence.xml

<property name="eclipselink.cache.coordination.channel" value="EmployeeChannel" />

Example 5-4 shows how to use this property in a property map.

Example 5-4 Using cache.coordination.channel in a Property Map

import org.eclipse.persistence.config.PersistenceUnitProperties;
propertiesMap.put(PersistenceUnitProperties.CACHE_COORDINATION_CHANNEL,
"myChannel");


See Also

For more information, see:

cache.coordination.jms.factory

Use the eclipselink.cache.coordination.jms.factory property to configure the JMS topic connection factory name, when using JMS coordination for a clustered environment.


Values

Table 5-3 describes this persistence property's values.

Table 5-3 Valid Values for cache.coordination.jms.factory

Value Description

name

The JMS topic connection factory name.

Default: jms/EclipseLinkTopicConnectionFactory


Usage

Use this property for JMS coordination (when eclipselink.cache.coordination.protocol = jms).


Examples

See Example 5-13 for information on how to use this property.


See Also

For more information, see:

cache.coordination.jms.host

Use the eclipselink.cache.coordination.jms.host property to configure the URL of the JMS server that hosts the topic, when using JMS coordination for a clustered environment.


Values

Table 5-4 describes this persistence property's values.

Table 5-4 Valid Values for cache.coordination.jms.host

Value Description

url

The fully-qualified URL for the JMS server.

This is not required if the topic is distributed across the cluster (that is, it can be looked up in local JNDI).


Usage

Use this property for JMS coordination (when eclipselink.cache.coordination.protocol = jms). You must use a fully qualified URL.


Examples

See Example 5-13 for information on how to use this property.


See Also

For more information, see:

cache.coordination.jms.reuse-topic-publisher

Use the eclipselink.cache.coordination.jms.reuse-topic-publisher property to specify if the JSM transport manager should cache a TopicPubliser and reuse it for all cache coordination publishing.


Values

Table 5-5 describes this persistence property's values.

Table 5-5 Valid Values for cache.coordination.jms.reuse-topic-publisher

Value Description

true

Caches the topic publisher.

false

(Default) Does not cache the topic publisher.


Usage

Use this property for JMS coordination (when eclipselink.cache.coordination.protocol = jms).


Examples

See Example 5-13 for information on how to use this property.


See Also

For more information, see:

cache.coordination.jms.topic

Use the eclipselink.cache.coordination.jms.topic property to set the JMS topic name, when using JMS coordination for a clustered environment.


Values

Table 5-6 describes this persistence property's values.

Table 5-6 Valid Values for cache.coordination.jms.topic

Value Description

name

Set the JMS topic name.

Default: jms/EclipseLinkTopic


Usage

Use this property for JMS coordination (when eclipselink.cache.coordination.protocol = jms).


Examples

See Example 5-13 for information on how to use this property.


See Also

For more information, see:

cache.coordination.jndi.initial-context-factory

Use the eclipselink.cache.coordination.jndi.initial-context-factory property to set the JNDI InitialContext factory, when using cache coordination for a clustered environment.


Values

Table 5-7 describes this persistence property's values.

Table 5-7 Valid Values for cache.coordination.jndi.initial-context-factory

Value Description

name

Name of the JNDI InitialContext factory.


Usage

Normally, you will not need this property when connecting to the local server.


Examples

Example 5-5 shows how to use this property in the persistence.xml file.

Example 5-5 Using cache.coordination.jndi.initial-context-factory in persistence.xml.

<property name="eclipselink.cache.coordination.jndi.initial-context-factory"
value="weblogic.jndi.WLInitialContextFactory/>

Example 5-6 shows how to use this property in a property map.

Example 5-6 Using cache.coordination.jndi.initial-context-factory in a property map

import org.eclipse.persistence.config.PersistenceUnitProperties;
propertyMap.put
(PersistenceUnitProperties.CACEH_COORDINATION_JNDI_INITIAL_CONTEXT_FACTORY,
"weblogic.jndi.WLInitialContextFactory");


See Also

For more information, see:

cache.coordination.jndi.password

Use the eclipselink.cache.coordination.jndi.password property to set the password for the cache.coordination.jndi.user, when using cache coordination for a clustered environment.


Values

Table 5-8 describes this persistence property's values.

Table 5-8 Valid Values for cache.coordination.jndi.password

Value Description

value

Password for the cache.coordination.jndi.user.


Usage

Normally, you will not need this property when connecting to the local server.


Examples

Example 5-7 shows how to use this propery in the persistence.xml file.

Example 5-7 Using cache.coordination.jndi.password in persistence.xml

<property name="eclipselink.cache.coordination.jndi.user" value="USERNAME"/>
<property name="eclipselink.cache.coordination.jndi.password" value="PASSWORD"/>

Example 5-8 shows how to use this property in a property map.

Example 5-8 Using cache.coordination.jndi.password in a Property Map

import org.eclipse.persistence.config.PersistenceUnitProperties;
propertyMap.put(PersistenceUnitProperties.CACHE_COORDINATION_JNDI_USER,
"USERNAME");
propertyMap.put(PersistenceUnitProperties.CACHE_COORDINATION_JNDI_PASSWORD,
"PASSWORD");


See Also

For more information, see:

cache.coordination.jndi.user

Use the eclipselink.cache.coordination.jndi.user property to set JNDI naming service user, when using cache coordination for a clustered environment.


Values

Table 5-9 describes this persistence property's values.

Table 5-9 Valid Values for cache.coordination.jndi.user

Value Description

value

The JNDI user.


Usage

Normally, you will not need this property when connecting to the local server.


Examples

See Example 5-13 for information on how to use this property.


See Also

For more information, see:

cache.coordination.naming-service

Use the eclipselink.cache.coordination.naming-service property to specify the naming service to use, when using cache coordination for a clustered environment.


Values

Table 5-10 describes this persistence property's values.

Table 5-10 Valid Values for cache.coordination.naming-service

Value Description

jndi

Uses JNDI.

rmi

Configures RMI.


Usage

Cache coordination must be enabled.


Examples

Example 5-9 shows how to use this property in the persistence.xml file.

Example 5-9 Using cache.coordination.naming-service in persistence.xml

<property name="eclipselink.cache.coordination" value="true"/>
<property name="eclipselink.cache.coordination.naming-service" value="jndi"/>

Example 5-10 shows how to use this property in a property map.

Example 5-10 Using cache.coordination.naming-service in a Property Map

import org.eclipse.persistence.config.PersistenceUnitProperties;
propertyMap.put(PersistenceUnitProperties.CACHE_COORDINATION_NAMING_SERVICE,
"jndi");


See Also

For more information, see:

cache.coordination.propagate-asynchronously

Use the eclipselink.cache.coordination.propagate-asynchronously property to specify if the coordination broadcast should occur asynchronously with the committing thread.

The property configures cache coordination for a clustered environment. Set if the coordination broadcast should occur asynchronously with the committing thread. This means the coordination will be complete before the thread returns from the commit of the transaction.


Values

Table 5-11 describes this persistence property's values.

Table 5-11 Valid Values for cache.coordination.propagate-asynchronously

Value Description

true

(Default) EclipseLink will broadcast asynchronously. The coordination will be complete before the thread returns from the committing the transaction.

false

EclipseLink will broadcast synchronously.


Usage

JMS cache coordination is always asynchronous, regardless of this setting.

By default, RMI cache coordination is asynchronous. Use synchronous (eclipselink.cache.coordination.propagate-asynchronously = false) to ensure that all servers are updated before the request returns.


Examples

Example 5-11 shows how to use this property in the persistence.xml file.

Example 5-11 Using cache.coordination.propagate-asynchronously in persistence.xml

<property name="eclipselink.cache.coordination.propagate-asynchronously"
value="false" />

Example 5-12 shows how to use this property in a property map.

Example 5-12 Using cache.coordination.propagate-asynchronously in a Property Map

import org.eclipse.persistence.config.PersistenceUnitProperties;
propertyMap.put
(PersistenceUnitProperties.CACHE_COORDINATION_PROPAGATE_ASYNCHRONOUSLY,
"false");


See Also

For more information, see:

cache.coordination.protocol

Use the eclipselink.cache.coordination.protocol property to specify the cache coordination protocol to use. Depending on the cache configuration for each descriptor, this will broadcast cache updates or inserts to the cluster to update or invalidate each session's cache.


Values

Table 5-12 describes this persistence property's values.

Table 5-12 Valid Values for cache.coordination.protocol

Value Description

jms

Use Java Message Service (JMS) to broadcast changes.

jms-publishing

Use an EJB MessageDrivenBean to be used to broadcast changes. You must configure the MessageDrivenBean separately.

rmi

Use Java Remote Method Invocation (RMI) to broadcast changes.

rmi-iiop

Use RMI over the Internet Inter-Orb Protocol (IIOP) to broadcast changes.

ClassName

The name of a subclass implementation of the TransportManager abstract class


Usage

You must specify the cache.coordination.protocol for every persistence unit and session in the cluster.


Examples

Example 5-13 shows how configure JMS cache coordination in the persistence.xml file.

Example 5-13 Configuring JMS Cache Coordination in persistence.xml

<property name="eclipselink.cache.coordination.protocol" value="jms" />
<property name="eclipselink.cache.coordination.jms.topic"
value="jms/EmployeeTopic" />
<property name="eclipselink.cache.coordination.jms.factory"
value="jms/EmployeeTopicConnectionFactory" />

If your application is not running in a cluster, you must provide the URL:

<property name="eclipselink.cache.coordination.jms.host"
value="t3://myserver:7001/" />

You can also include a username and password, if required, to access the server (for example, if on a separate domain):

<property name="eclipselink.cache.coordination.jndi.user" value="weblogic" />
<property name="eclipselink.cache.coordination.jndi.password" value="welcome1" />

Example 5-14 shows how to configure RMI cache coordination in the persistence.xml file.

Example 5-14 Configuring RMI Cache Coordination in persistence.xml

<property name="eclipselink.cache.coordination.protocol" value="rmi" />

If your application is not running in a cluster, you must provide the URL:

<property name="eclipselink.cache.coordination.rmi.url"
value="t3://myserver:7001/" />

You can also include a username and password, if required, to access the server (for example, if on a separate domain):

<property name="eclipselink.cache.coordination.jndi.user" value="weblogic" />
<property name="eclipselink.cache.coordination.jndi.password" value="welcome1" />

By default, RMI cache coordination broadcasts are asynchronous. You can override this, if needed:

<property name="eclipselink.cache.coordination.propagate-asynchronously"
value="false" />

If you have multiple applications on the same server or network, you can specify a separate cache coordination channel for each application:

<property name="eclipselink.cache.coordination.channel" value="EmployeeChannel" />

RMI cache coordination uses a multicast socket to allow servers to find each other. You can configure the multicast settings, if needed:

<property name="eclipselink.cache.coordination.rmi.announcement-delay"
value="1000" />
<property name="eclipselink.cache.coordination.rmi.multicast-group"
value="239.192.0.0" />
<property name="eclipselink.cache.coordination.rmi.multicast-group.port"
value="3121" />
<property name="eclipselink.cache.coordination.packet-time-to-live" value="2" />


See Also

For more information, see:

cache.coordination.remove-connection-on-error

Use the eclipselink.cache.coordination.remove-connection-on-error property to specify if the connection should be removed if EclipseLink encounters a communication error when coordinating the cache.


Values

Table 5-13 describes this persistence property's values.

Table 5-13 Valid Values for cache.coordination.remove-connection-on-error

Value Description

true

Removes the connection if a communication error occurs. EclipseLink will reconnect when the server becomes available.

false

(Default) Does not remove the connection if a communication error occurs.


Usage

Normally, this is used for RMI connections in the event that a server goes down.


Examples

Example 5-15 shows how to use this property in the persistence.xml file.

Example 5-15 Using cache.coordination.remove-connection-on-error in peristence.xml

<property name="eclipselink.cache.coordination.remove-connection-on-error"
value="true"/>

Example 5-16 shows how to use this property in a property map.

Example 5-16 Using cache.coordination.remove-connection-on_error in a property map

import org.eclipse.persistence.config.PersistenceUnitProperties;
propertyMap.put
(PersistenceUnitProperties.CACHE_COORDINATION_REMOVE_CONNECTION_ON_ERROR,"true");


See Also

For more information, see:

cache.coordination.rmi.announcement-delay

Use the eclipselink.cache.coordination.rmi.announcement-delay property to set the time (in milliseconds) to wait for announcements from other cluster members on startup.


Values

Table 5-14 describes this persistence property's values.

Table 5-14 Valid Values for cache.coordination.rmi.announcement-delay

Value Description

Numeric

Time (in milliseconds) to wait for announcements, on startup.

Default: 1000


Usage

Use this property for RMI coordination (when eclipselink.cache.coordination.protocol = rmi).


Examples

See Example 5-14 for information on how to use this property.


See Also

For more information, see:

cache.coordination.rmi.multicast-group

Use the eclipselink.cache.coordination.rmi.multicast-group property to set the multicast socket group address (used to find other members of the cluster), when using cache coordination for a clustered environment.


Values

Table 5-15 describes this persistence property's values.

Table 5-15 Valid Values for cache.coordination.rmi.multicast-group

Value Description

Numeric

Set the multicast socket group address

Default: 239.192.0.0


Usage

Use this property for RMI coordination (when eclipselink.cache.coordination.protocol = rmi).


Examples

See Example 5-14 for information on how to use this property.


See Also

For more information, see:

cache.coordination.rmi.multicast-group.port

Use the eclipselink.cache.coordination.rmi.multicast-group.port property to set the multicast socket group port (used to find other members of the cluster), when using cache coordination for a clustered environment.


Values

Table 5-16 describes this persistence property's values.

Table 5-16 Valid Values for cache.coordination.rmi.multicast-group.port

Value Description

Numeric

Set the multicast socket group port.

Default: 3121


Usage

Use this property for RMI coordination (when eclipselink.cache.coordination.protocol = rmi).


Examples

See Example 5-14 for information on how to use this property.


See Also

For more information, see:

cache.coordination.rmi.packet-time-to-live

Use the eclipselink.cache.coordination.rmi.packet-time-to-live property to set the number of hops the session announcement data packets will take before expiring. The multicast group is used to find other members of the cluster.


Values

Table 5-17 describes this persistence property's values.

Table 5-17 Valid Values for cache.coordination.rmi.packet-time-to-live

Value Description

Numeric

Number of hops the session announcement data packets will take before expiring.

Default: 2


Usage

If sessions are hosted on different LANs that are part of WAN, the announcement sent by one session may not reach other sessions. In this case, consult your network administrator for the correct time-to-live value or test your network by increasing the value until each session receives announcement sent by others.

Use this property for RMI coordination (when eclipselink.cache.coordination.protocol = rmi).


Examples

See Example 5-14 for information on how to use this property.


See Also

For more information, see:

cache.coordination.rmi.url

Use the eclipselink.cache.coordination.rmi.url property to set the URL of the host server. This is the URL that other cluster member use to connect to this host.


Values

Table 5-18 describes this persistence property's values.

Table 5-18 Valid Values for cache.coordination.rmi.url

Value Description

url

URL of the host server

Default: local


Usage

Use this property for RMI coordination (when eclipselink.cache.coordination.protocol = rmi).

This may not be required in a clustered environment where JNDI is replicated. You can also set the location as a System property or using a SessionCustomizer to avoid requiring a separate persistence.xml file per server.


Examples

See Example 5-14 for information on how to use this property.


See Also

For more information, see:

cache.coordination.thread.pool.size

Use the eclipselink.cache.coordination.thread.pool.size property to configure the size of the thread pool, for cache coordination threads.


Values

Table 5-19 describes this persistence property's values.

Table 5-19 Valid Values for cache.coordination.thread.pool.size

Value Description

Numeric

Size of the thread pool. If 0, EclipseLink does not use a thread pool; instead threads are spawned when required.

Default: 32


Usage

For RMI cache coordination, EclipseLink spawns one thread per node to send change notifications and one thread to listen for new node notifications.

For JMS cache coordination, EclipseLink spawns one thread to receive JMS change notification messages (unless MDB is used) and one thread to process the change notification (unless MDB is used).


Examples

Example 5-17 shows how to use this property in the persistence.xml file.

Example 5-17 Using cache.coordination.thread.pool.size in persistence.xml

<property name="eclipselink.cache.coordination.thread.pool.size" 
value="48"/>

Example 5-18 shows how to use this property in a property map.

Example 5-18 Using cache.coordination.thread.pool.size in a Property Map

import org.eclipse.persistence.config.PersistenceUnitProperties;
propertyMap.put(PersistenceUnitProperties.CACHE_COORDINATION_THREAD_POOL_SIZE,
"48");


See Also

For more information, see:

cache.database-event-listener

Use the eclipselink.cache.database-event-listener property to integrate EclipseLink with a database event notification service, such as Oracle QCN/DCN (Query Change Notification/Database Change Notification).


Values

Table 5-20 describes this persistence property's values.

Table 5-20 Valid Values for cache.database-event-listener

Value Description

Class

The name of a class that implements DatabaseEventListener, such as the OracleChangeNotificationListener (org.eclipse.persistence.platform.database.oracle.dcn.OracleChangeNotificationListener).

You can also use DCN and QCN for Oracle.


Usage

You can use this property to allow the EclipseLink cache to be invalidated by database change events, triggers, or other services.


Examples

Example 5-19 shows how to use this property with Oracle DCN.

Example 5-19 Using cache.database-event-listener in persistence.xml

<?xml version="1.0" encoding="UTF-8"?>
<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.database-event-listener" value=
"org.eclipse.persistence.platform.database.oracle.dcn.OracleChangeNotificationList
ener"/>
        </properties>
    </persistence-unit>
</persistence>


See Also

For more information, see:

cache.shared

Use the eclipselink.cache.shared property prefix to indicate whether an entity's cache is shared (non-isolated).


Values

Table 5-21 describes this persistence property prefix's values.

Table 5-21 Valid Values for cache.shared

Value Description

true

(Default) Shares an entity's cache. The value is case insensitive.

false

Prevents sharing of an entity's cache. The value is case insensitive.


Usage

Form a property name by appending either a valid entity name or class name to class.shared, indicating that the property values apply only to a particular entity. As an alternative, you can append the default suffix to the cache.shared property prefix to form a property name that sets the default for all entities.


Examples

See Example 2-12 for information on how to use this property.

cache.size

Use the eclipselink.cache.size property prefix to specify the cache size for a specific entity type.


Values

Table 5-22 describes this persistence property prefix's values.

Table 5-22 Valid Values for cache.size

Value Description

integer

The size of the cache. Default: 100 Bytes.


Usage

Form a property name by appending either a valid entity name or class name to cache.size, indicating that the property values apply only to a particular entity. As an alternative, you can append the default suffix to the cache.size property prefix, indicating that the property value applies to all entities.

For most cache types, the size is only the initial size, not a fixed or maximum size. For CacheType.SoftCache and CacheType.HardCache types, the size is the sub-cache size. The default cache size is 100 Bytes.


Examples

See Example 2-12 for information on how to use this property.

cache.type

Use the eclipselink.cache.type property prefix to set the type of cache.


Values

Table 5-23 describes this persistence property prefix's values

Table 5-23 Valid values for cache.type

Value Description

Weak

Holds all objects in use by the application, and allows any unreferenced objects to be free for garbage collection. This cache type guarantees object identity and allows optimal garbage collection, but provides little caching benefit.

Soft

Holds all objects read by the application, and allows any unreferenced objects to be free for garbage collection only when the JVM decides that memory is low. This cache type guarantees object identity, allows for garbage collection when memory is low, and provides optimal caching benefit.

SoftWeak

(Default)Holds all objects read by the application, and a fixed-size subcache of MRU objects using Soft references.The SoftWeak cache allows any unreferenced objects not in the sub-cache to be free for garbage collection. The objects in the sub-cache are free to garbage collect only when the JVM decides that memory is low. This cache type guarantees object identity, allows configurable garbage collection, and provides configurable caching benefit.

HardWeak

Holds all objects in use by the application, and a fixed-size subcache of MRU objects using normal Hard references. This type allows any unreferenced objects not in the subcache to be free for garbage collection, but not objects in the subcache. This cache type guarantees object identity, allows configurable garbage collection, and provides configurable caching benefit.

Full

Holds all objects read by the application. This cache type does not allow garbage collection. This guarantees object identity, allows no garbage collection, and provides complete caching benefit.

WARNING: Use this cache type only for a fixed number of objects; otherwise, memory leakage will occur eventually.

NONE

Does not cache any objects, and frees any unreferenced objects for garbage collection. This provides no object identity, allows complete garbage collection, and provides no caching benefit.

WARNING: This cache type should normally not be used. Instead, disable the shared cache through PersistenceUnitProperties.CACHE_SHARED. Lack of object identity can lead to infinite loops for objects that have circular references and no indirection.


Usage

Form a property name by appending a valid entity name or class name to cache.type, indicating that the property values apply only to a particular entity. As an alternative, you can append the default suffix to the cache.type prefix to form a property name that sets the default for all entities.

Valid values for cache.type properties are declared in the CacheType class. The default is SoftWeak.

If you do not want to cache entities, set the cache.shared property.


Examples

See Example 2-12 for information about how to use this property.


See Also

For more information, see:

classloader

Use the eclipselink.classloader property to create an EntityMangerFactory in the property map to be passed to Persistence.createEntityManagerFactory.


Values

Table 5-24 describes this persistence property's values.

Table 5-24 Valid Values for classloader

Value Description

value

Classloader to use.


Usage

This is a dynamic property that must be set at runtime, in the property map. You cannot configure this property in the persistence.xml file.


Examples

Example 5-20 shows how to use this property in a property map.

Example 5-20 Using classloader in a Property Map

properties.put("eclipselink.classloader", this.getClass().getClassLoader());

composite-unit

Use the eclipselink.composite-unit property to specify if the persistence unit is a composite persistence unit.


Values

Table 5-25 describes this persistence property's values.

Table 5-25 Valid Values for composite-unit

Value Description

true

Persistence unit is a composite persistence unit.

false

(Default) Persistence unit is not a composite persistence unit.


Usage

The property must be specified in persistence.xml of a composite persistence unit. The composite persistence unit must contain all persistence units found in JAR files specified by the persistence.xml file.


NoteNote:

If this property is passed to the createEntityManagerFactory method or if it is set in system properties, it is ignored.)


Examples

Example 5-21 shows how to use this property in the persistence.xml file.

Example 5-21 Using composite-unit in persistence.xml

<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_1_0.xsd" version="1.0">
    <persistence-unit name="compositePu" transaction-type="JTA">
        <provider>
            org.eclipse.persistence.jpa.PersistenceProvider
        </provider>
 
        <jar-file>member1.jar</jar-file>
        <jar-file>member2.jar</jar-file>
 
        <properties>
            <property name="eclipselink.composite-unit" value="true"/>
            <property name="eclipselink.target-server" value="WebLogic_10"/>
        </properties>
    </persistence-unit>
</persistence>


See Also

For more information, see:

composite-unit.member

Use the eclipselink.composite-unit.member property to specify if the persistence unit is a member composite persistence unit.


Values

Table 5-26 describes this persistence property's values.

Table 5-26 Valid Values for composite-unit.member

Value Description

true

The persistence unit must be a member of a composite persistence unit and cannot be used as an independent persistence unit.

false

(Default) The persistence unit does not have to be a member of a composite persistence unit.


Usage

Setting this property to true indicates that the persistence unit has dependencies on other persistence units.


NoteNote:

If this property is passed to the createEntityManagerFactory method or if it is set in system properties, it is ignored.)

If this property is true, you may still create EntityManagerFactory, but it cannot be connected. Any attempt to create an entity manger will cause an exception.

Query Hint

When executing a native query on a composite persistence unit, use composite-unit.member to specify the name of the composite member persistence unit on which to execute the query.


Examples

Example 5-22 shows how to use this property in the persistence.xml file.

Example 5-22 Using composite-unit.member in persistence.xml

Composite member persistence unit memberPu2 is defined in the member2.jar file. It has dependency on a class defined in member1.jar and cannot be used independently.

<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_1_0.xsd"
version="1.0">
    <persistence-unit name="memberPu2">
        <provider>
            org.eclipse.persistence.jpa.PersistenceProvider
        </provider>
        <mapping-file>META-INF/advanced-entity-mappings2.xml</mapping-file>
        <jta-data-source>jdbc/MySqlJtaDS</jta-data-source>
        <exclude-unlisted-classes>false</exclude-unlisted-classes>
        <properties>
            <property name="eclipselink.composite-unit.member" value="true"/>
            <property name="eclipselink.target-database"
value="org.eclipse.persistence.platform.database.MySQLPlatform"/>
        </properties>
    </persistence-unit>
</persistence>


See Also

For more information, see:

composite-unit.properties

Use the eclipselink.composite-unit.properties property to configure the properties for persistence unit members.


Values

Table 5-27 describes this persistence property's values.

Table 5-27 Valid Values for composite-unit.properties

Value Description

Map of properties

Properties to be passed to the persistence unit. Use the persistence unit's name as the key.


Usage

Pass this property to createEntityManager method of a composite persistence unit to pass properties to its member persistence units.


Examples

Example 5-23 shows how to use this property in a property map

Example 5-23 Using composite-unit.properties in a Property Map

Map props1 = new HashMap();
 
   props1.put("javax.persistence.jdbc.user", "user1");
   props1.put("javax.persistence.jdbc.password", "password1");
   props1.put("javax.persistence.jdbc.driver", "oracle.jdbc.OracleDriver");
   props1.put("javax.persistence.jdbc.url", "jdbc:oracle:thin:@oracle_db_url:1521:db");
 
Map props2 = new HashMap();
 
   props2.put("javax.persistence.jdbc.user", "user2");
   props2.put("javax.persistence.jdbc.password", "password2");
   props2.put("javax.persistence.jdbc.driver", "com.mysql.jdbc.Driver");
   props2.put("javax.persistence.jdbc.url", " jdbc:mysql://my_sql_db_url:3306/user2");
 
Map memberProps = new HashMap();
   memberProps.put("memberPu1", props1);
   memberProps.put("memberPu2", props2);
 
Map props = new HashMap();
   props.put("eclipselink.logging.level", "FINEST");
   props.put("eclipselink.composite-unit.properties", memberProps);
 
EntityManagerFactory emf = Persistence.createEntityManagerFactory("compositePu", props);


See Also

For more information, see:

concurrency.manager.waittime

This property in milliseconds can control thread management in org.eclipse.persistence.internal.helper.ConcurrencyManager. It control how much time loop wait before it try acquire lock for current thread again. It value is set above above 0 dead lock detection mechanism and related extended logging will be activated.


Values

Table 5-30 describes this persistence property's values.

Table 5-30 Valid Values for concurrency.manager.waittime

Value Description

Wait time

How much time loop wait before it try acquire lock for current thread again. Default value is 0 (unit is ms). Allowed values are: long


Examples

Example 5-24 shows how to use this property in the persistence.xml file.

Example 5-24 Using concurrency.manager.waittime in persistence.xml

<property name="eclipselink.concurrency.manager.waittime" value="100" />

concurrency.manager.maxsleeptime

This system property in milliseconds can control thread management in org.eclipse.persistence.internal.helper.ConcurrencyManager. It control how long we are willing to wait before firing up an exception.


Values

Table 5-30 describes this persistence property's values.

Table 5-30 Valid Values for concurrency.manager.maxsleeptime

Value Description

Wait time

It control how long we are willing to wait before firing up an exception. Default value is 40000 (unit is ms). Allowed values are: long


Examples

Example 5-24 shows how to use this property in the persistence.xml file.

Example 5-24 Using concurrency.manager.maxsleeptime in persistence.xml

<property name="eclipselink.concurrency.manager.maxsleeptime" value="100" />

concurrency.manager.maxfrequencytodumptinymessage

This system property in milliseconds can control thread management in org.eclipse.persistence.internal.helper.ConcurrencyManager and org.eclipse.persistence.internal.helper.ConcurrencyUtil. It control how frequently the tiny dump log message is created.


Values

Table 5-30 describes this persistence property's values.

Table 5-30 Valid Values for concurrency.manager.maxfrequencytodumptinymessage

Value Description

Wait time

It control how frequently the tiny dump log message is created. Default value is 40000 (unit is ms). Allowed values are: long


Examples

Example 5-24 shows how to use this property in the persistence.xml file.

Example 5-24 Using concurrency.manager.maxfrequencytodumptinymessage in persistence.xml

<property name="eclipselink.concurrency.manager.maxfrequencytodumptinymessage" value="100000" />

concurrency.manager.maxfrequencytodumpmassivemessage

This system property in milliseconds can control thread management in org.eclipse.persistence.internal.helper.ConcurrencyManager and org.eclipse.persistence.internal.helper.ConcurrencyUtil. It control how frequently the massive dump log message is created.


Values

Table 5-30 describes this persistence property's values.

Table 5-30 Valid Values for concurrency.manager.maxfrequencytodumpmassivemessage

Value Description

Wait time

It control how frequently the massive dump log message is created. Default value is 60000 (unit is ms). Allowed values are: long


Examples

Example 5-24 shows how to use this property in the persistence.xml file.

Example 5-24 Using concurrency.manager.maxfrequencytodumpmassivemessage in persistence.xml

<property name="eclipselink.concurrency.manager.maxfrequencytodumpmassivemessage" value="100000" />

concurrency.manager.allow.interruptedexception

In the places where use this property normally if a thread is stuck it is because it is doing object building. Blowing the threads ups is not that dangerous. It can be very dangerous for production if the dead lock ends up not being resolved because the productive business transactions will become cancelled if the application has a limited number of retries to for example process an MDB. However, the code spots where we use this constant are not as sensible as when the write lock manager is starving to run commit.


Values

Table 5-30 describes this persistence property's values.

Table 5-30 Valid Values for concurrency.manager.allow.interruptedexception

Value Description

true

(Default) If we want the to fire up an exception to try to get the current thread to release all of its acquired locks and allow other threads to progress.

false

If aborting frozen thread is not effective it is preferable to not fire the interrupted exception let the system.


Examples

Example 5-24 shows how to use this property in the persistence.xml file.

Example 5-24 Using concurrency.manager.allow.interruptedexception in persistence.xml

<property name="eclipselink.concurrency.manager.allow.interruptedexception" value="true" />

concurrency.manager.allow.concurrencyexception

See valid values table.


Values

Table 5-30 describes this persistence property's values.

Table 5-30 Valid Values for concurrency.manager.allow.concurrencyexception

Value Description

true

(Default) If we want the to fire up an exception to try to get the current thread to realease all of its acquired locks and allow other threads to progress.

false

If aborting frozen thread is not effective it is preferable to not fire the concurrency exception let the system freeze and die and force the administration to kill the server. This is preferable to aborting the transactions multiple times without success in resolving the dead lock and having business critical messages that after 3 JMS retries are discarded out. Failing to resolve a dead lock can have terrible impact in system recovery unless we have infinite retries for the business transactions.


Examples

Example 5-24 shows how to use this property in the persistence.xml file.

Example 5-24 Using concurrency.manager.allow.concurrencyexception in persistence.xml

<property name="eclipselink.concurrency.manager.allow.concurrencyexception" value="true" />

concurrency.manager.allow.readlockstacktrace

Collect debug/trace information during ReadLock acquisition.


Values

Table 5-30 describes this persistence property's values.

Table 5-30 Valid Values for concurrency.manager.allow.readlockstacktrace

Value Description

true

(Default) Collect debug/trace information during ReadLock acquisition.

false

Don't collect debug/trace information during ReadLock acquisition


Examples

Example 5-24 shows how to use this property in the persistence.xml file.

Example 5-24 Using concurrency.manager.allow.readlockstacktrace in persistence.xml

<property name="eclipselink.concurrency.manager.allow.readlockstacktrace" value="true" />

connection-pool

Use the eclipselink.connection-pool property to configure the various connection pool properties.


Values

Table 5-28 describes this persistence property's values.

Table 5-28 Valid Values for connection-pool

Value Description

initial

Starting (initial) number of connections.

min

Minimum number of connections.

max

Maximum number of connections.

wait

Amount of time (in milliseconds) to wait for a connection from the pool.

url

URL of the JDBC for the connection.

shared

For read connection pools, indicates that read connections are shared across threads.

jtaDataSource

JTA DataSource name to use for the connection, if different than the default.

nonJtaDataSource

Non-JTA DataSource name to use for the connection, if different than the default.

user

Username to use for this connection (if different than the default).

password

Password of the user for this connection (if different than the default).


Usage

Append the name of the connection pool and property to be configured. If connection pool is specified, EclipseLink configures the default (write) pool.


Examples

Example 5-24 shows how to use this property in the persistence.xml file.

Example 5-24 Using connection-pool in persistence.xml

<property name="eclipselink.connection-pool.default.initial" value="1" />
<property name="eclipselink.connection-pool.node2.min" value="16"/>
<property name="eclipselink.connection-pool.node2.max" value="16"/>
<property name="eclipselink.connection-pool.node2.url"
value="jdbc:oracle:thin:@node2:1521:orcl"/>


See Also

For more information, see:

connection-pool.read

Use the eclipselink.connection-pool.read property to configure a read connection pool for non-transaction read queries.


Values

Table 5-29 describes this persistence property's values.

Table 5-29 Valid Values for connection-pool.read

Value Description

initial

Starting (initial) number of connection.

min

Minimum number of connections.

max

Maximum number of connections.

wait

Amount of time it takes to get connections from the pool.

url

URL of the JDBC connection.

shared

For read connection pools, indicates that read connections are shared across threads.

jtaDataSource

JTA DataSource name to use for the connection, if different than the default.

nonJtaDataSource

Non-JTA DataSource name to use for the connection, if different than the default.

user

Username to use for this connection (if different than the default).

password

Password of the user for this connection (if different then the default).


Usage

By default, EclipseLink does not use a separate read connection pool; the default pool is used for read queries.


Examples

Example 5-25 shows how to use this property in the persistence.xml file.

Example 5-25 Using connection-pool.read in persistence.xml

<property name="eclipselink.connection-pool.read.min" value="16"/>
<property name="eclipselink.connection-pool.read.max" value="16"/>


See Also

For more information, see:

  • "Connection Pools" in Understanding EclipseLink

  • "Connection Pooling" in Solutions Guide for EclispeLink

  • "connection-pool"

connection-pool.sequence

Use the eclipselink.connection-pool.sequence property to have the connection pool allocate generated IDs.


Values

Table 5-30 describes this persistence property's values.

Table 5-30 Valid Values for connection-pool.sequence

Value Description

true

Uses the internal connection pool to pool connections from a datasource.

false

(Default) Does not use the internal connection pool to pool connections from a datasource.


Usage

This is only required for TABLE sequencing. By default, EclipseLink does not use a separate sequence connection pool; the default pool is used for sequencing.


Examples

Example 5-26 shows how to use this property in the persistence.xml file.

Example 5-26 Using connection-pool.sequence in persistence.xml

<property name="eclipselink.connection-pool.sequence" value="true"/>


See Also

For more information, see:

  • "Connection Pools" in Understanding EclipseLink

  • "Connection Pooling" in Solutions Guide for EclispeLink

  • "connection-pool"

create-ddl-jdbc-file-name

Use the eclipselink.create-ddl-jdbc-file-name property to specify the name of the DDL file generated by EclipseLink that contains the SQL statements to create tables for JPA entities.


Values

Table 5-31 describes this persistence property's values.

Table 5-31 Valid Values for create-ddl-jdbc-file-name

Value Description

File name

A file name valid for your operating system.

You can prefix the file name with a file path if a concatenation of eclipselink.application-location + eclipselink.create-ddl-jdbc-file-name is valid for your operating system.


Usage

If eclipselink.ddl-generation is set to create-tables or drop-and-create-tables, EclipseLink writes this file to the location specified by eclipselink.application-location.


Examples

See Example 5-27 for information on how to use this property.


See Also

For more information, see:

ddl-generation

Use the eclipselink.ddl-generation property to specify how EclipseLink generates DDL (Data Definition Language) for the database schema (tables and constraints) on deployment

Note: EclipseLink does not support mixing EclipseLink defined and JPA defined DDL generation properties. If the eclipselink.ddl-generation property is specified, the javax.persistence.schema-generation.database.action, javax.persistence.schema-generation.scripts.action, and javax.persistence.sql-load-script-source JPA defined properties will be ignored.


Values

Table 5-32 describes this persistence property's values.

Table 5-32 Valid Values for ddl-generation

Value Description

create-tables

EclipseLink will attempt to execute a CREATE TABLE SQL for each table.

If the table already exists, EclipseLink will follow the default behavior of your specific database and JDBC driver combination (when a CREATE TABLE SQL is issued for an already existing table). In most cases an exception is thrown and the table is not created; the existing table will be used. EclipseLink will then continue with the next statement.

create-or-extend-tables

EclipseLink will attempt to create tables. If the table exists, EclipseLink will add any missing columns.

drop-and-create-tables

EclipseLink will attempt to DROP all tables, then CREATE all tables. If any issues are encountered, EclipseLink will follow the default behavior of your specific database and JDBC driver combination, then continue with the next statement.

This is useful in development if the schema frequently changes or during testing when the existing data needs to be cleared.

Note: Using drop-and-create will remove all of the data in the tables when they are dropped. You should never use option on a production schema that has valuable data in the database. If the schema changed dramatically, there could be old constraints in the database that prevent the dropping of the old tables. This may require the old schema to be dropped through another mechanism.

none

(Default) No DDL generated; no schema generated.


Usage

You can use create-or-extend-tables only when eclipselink.ddl-generation.output-mode = database.

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.

DDL_GENERATION must be set in order for this property to take effect.


Examples

Example 5-27 shows how to use this property in the persistence.xml file.

Example 5-27 Using ddl-generation in persistence.xml

<property name="eclipselink.ddl-generation" value="drop-and-create-tables"/>
<property name="eclipselink.create-ddl-jdbc-file-name" value="createDDL_ddlGeneration.jdbc"/>
<property name="eclipselink.drop-ddl-jdbc-file-name" value="dropDDL_ddlGeneration.jdbc"/>
<property name="eclipselink.ddl-generation.output-mode" value="both"/>

Example 5-28 shows how to use this property in a property map.

Example 5-28 Using ddl-generation in a Property Map

import org.eclipse.persistence.config.PersistenceUnitProperties;
propertiesMap.put(PersistenceUnitProperties.DDL_GENERATION,
PersistenceUnitProperties.DROP_AND_CREATE);
propertiesMap.put(PersistenceUnitProperties.DDL_GENERATION_MODE,
PersistenceUnitProperties.BOTH);
propertiesMap.put(PersistenceUnitProperties.CREATE_JDBC_DDL_FILE, "create.sql");


See Also

For more information, see:

ddl-generation.output-mode

Use the eclipselink.ddl-generation.output-mode property to specify where EclipseLink generates and writes the DDL.


Values

Table 5-33 describes this persistence property's values.

Table 5-33 Valid Values for ddl-generation.output-mode

Value Description

both

DDL will be generated and written to both the database and a file.

database

(Default) DDL will be generated and written to the database only.

sql-script

DDL will be generated and written to a file only.


Usage

You can only use ddl-generation.output-mode if you use ddl-generation. Then, you can optimally set other properties.


Examples

See Example 5-27 for information on how to use this property.


See Also

For more information, see:

ddl.table-creation-suffix

Use the eclipselink.ddl.table-creation-suffix property to append a string to generated CREATE Table statements.


Values

Table 5-34 describes this property's values.

Table 5-34 Valid Values for ddl-generation.table-creation-suffix

Value Description

value

The name of the suffix.


Usage

The ddl.generation property must be set.


Examples

Example 5-29 shows how to use this property in the persistence.xml file.

Example 5-29 Using ddl.table-creation-suffix in persistence.xml

<property name="eclipselink.ddl.table-creation-suffix" value="engine=InnoDB"/>


See Also

For more information, see:

deploy-on-startup

Use the eclipselink.deploy-on-startup property to configure deployment on startup (at the creation of the EntityManagerFactory) instead of occurring the first time an EntityManager is created.


Values

Table 5-35 describes this persistence property's values.

Table 5-35 Valid Values for delay-on-startup

Value Description

true

Causes a persistence unit to be created when the EntityManager is created, usually during deployment to a Java EE container or servlet container.

false

(Default) The persistence unit is not initialized until the first EntityManager is created, or until metadata is required from the EntityManagerFactory.


Usage

Using true may increase startup time of a JavaEE server, but will avoid the first request from hanging as the persistence unit is deployed.


Examples

Example 5-30 shows how to use this property in the peristence.xml file.

Example 5-30 Using deploy-on-startup in persistence.xml

<property name="eclipselink.deploy-on-startup" value="true" />

descriptor.customizer

Use the eclipselink.descriptor.customizer property as a prefix for a property to configure a DescriptorCustomizer. 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.


Values

Table 5-36 describes this persistence property's values.

Table 5-36 Valid Values for descriptor.customizer

Value Description

name

Full name for a class that implements DescriptorCustomizer.


Usage

You cannot use multiple descriptor customizers.


Examples

Example 5-31 shows how to use this property in the peristence.xml file.

Example 5-31 Using descriptor.customizer in persistence.xml

<property name="eclipselink.descriptor.customizer.Order" 
value="acme.sessions.MyDesriptorCustomizer"/>

Example 5-32 shows how to use this property with a property map.

Example 5-32 Using descriptor.customizer in a Property Map

import org.eclipse.persistence.config.PersistenceUnitProperties;
propertiesMap.put(PersistenceUnitProperties.DESCRIPTOR_CUSTOMIZER+".Order",
"acme.sessions.MyDescriptorCustomizer");


See Also

For more information, see:

drop-ddl-jdbc-file-name

Use the eclipselink.drop-ddl-jdbc-file-name property to specify the name of the DDL file generated by EclipseLink that contains the SQL statements to drop tables for JPA entities.


Values

Table 5-37 describes this persistence property's values.

Table 5-37 Valid Values for drop-ddl-jdbc-file-name

Value Description

File name

A file name valid for your operating system.

You can prefix the file name with a file path if a concatenation of eclipselink.application-location + eclipselink.create-ddl-jdbc-file-name is valid for your operating system.


Usage

If eclipselink.ddl-generation is set to create-tables, EclipseLink writes this file to the location specified by eclipselink.application-location.


Examples

See Example 5-27 for information on how to use this property.


See Also

For more information, see:

exception-handler

Use the eclipselink.exception-handler property to specify the EclipseLink exception handler class: an exception handler class that implements the org.eclipse.persistence.exceptions.ExceptionHandler interface. The class must provide a default, no-argument constructor.


Values

Table 5-38 describes this persistence property's values.

Table 5-38 Valid Values for exception-handler

Value Description

ExceptionHandler class

Use the handleException method of the class, which takes a java.lang.RuntimeException, to:

  • Re-throw the exception

  • Throw a different exception

  • Retry the query or database operation


Usage

The ExceptionHandler class name must be fully qualified by its package name.


Examples

Example 5-33 shows how to use this property in the persistence.xml file.

Example 5-33 Using exception-handler in persistence.xml

<property name="eclipselink.exception-handler" 
value="my.package.MyExceptionHandler">

Example 5-34 shows how to use this extension in a property map.

Example 5-34 Using exception-handler in a Property Map

import org.eclipse.persistence.config.PersistenceUnitProperties;
propertiesMap.put(PersistenceUnitProperties.EXCEPTION_HANDLER_CLASS, 
"my.package.MyExceptionHandler");


See Also

For more information, see:

  • "orm.throw.exceptions"

  • "Sessions" in Understanding EclipseLink

  • "Managing and Diagnosing Problems" in Solutions Guide for EclispeLink

exclude-eclipselink-orm

Use the eclipselink.exclude-eclipselink-orm property to exclude an EclipseLink ORM mapping file for a specific persistence unit.


Values

Table 5-39 describes this persistence property's values.

Table 5-39 Valid Values for exclude-eclipselink-orm

Value Description

true

Does not use the eclipselink-orm.xml file.

false

(Default) EclipseLink uses the eclipselink-orm.xml file.


Usage

By default the first file found at the resource name: META-INF/eclipselink-orm.xml is processed and overrides configurations specified in annotations and standard mapping files.


Examples

Example 5-35 shows how to use this property in the persistence.xml file.

Example 5-35 Using exclude-eclipselink-orm in persistence.xml

<property name="eclipselink.exclude-eclipselink-orm" value="true"/>


See Also

For more information, see:

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

  • "Using an External Metadata Source" in Solutions Guide for EclispeLink

flush-clear.cache

Use the eclipselink.flush-clear.cache property to specify the EclipseLink EntityManager cache behavior when a clear method follows the flush method.


Values

Table 5-40 describes this persistence property's values.

Table 5-40 Valid Values for flush-clear.cache

Value Description

Drop

EclipseLink drops the entire EntityManager cache.

Although this is the fastest mode and uses the least memory, the shared cache may potentially contain stale data after performing the commit.

DropInvalidate

(Default) EclipseLink drops the entire EntityManager cache. Classes that have at least one updated or deleted object become invalid in the shared cache after performing the commit.

This mode is slower than Drop, but as efficient (in terms of memory usage) and prevents stale data.

Merge

EclipseLink drops objects the EntityManager cache that have not been flushed.

Although this mode leaves the shared cache in a perfect state after performing the commit, it is the least memory-efficient. In a very large transaction you may run out of memory.


Usage

You can specify this property when creating an EntityManagerFactory (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.


Examples

Example 5-36 shows how to use this property in the persistence.xml file.

Example 5-36 Using flush-clear.cache in persistence.xml

<property name="eclipselink.flush-clear.cache" value="Drop"/>

Example 5-37 shows how to use this extension in a property map.

Example 5-37 Using flush-clear.cache in a Property Map

import org.ecliplse.persistence.config.PersistenceUnitProperties;
propertiesMap.put(PersistenceUnitProperties.FLUSH_CLEAR_CACHE,
FlushClearCache.Drop);


See Also

For more information, see:

id-validation

Use the eclipselink.id-validation property to define which primary key components values are considered invalid.


Values

Table 5-41 describes this persistence property's values.

Table 5-41 Valid Values for id-validation

Value Description

Negative

Null, 0 and negative values are invalid for IDs extending Number and primitive int and long IDs.

None

EclipseLink performs no ID validation.

Null

Null is invalid All other values are valid.

Zero

Null, 0 and negative values are invalid for primitive int and long IDs.


Usage

Identity and sequencing (with shouldAlwaysOverrideExistingValue configured as true) will override any existing ID value.


Examples

Example 5-38 shows how to use this property in the persistence.xml file.

Example 5-38 Using id-validation in persistence.xml

<property name="eclipselink.id-validation" value="NULL"/>


See Also

For more information, see:

  • "Persisting Objects" in Understanding EclipseLink

  • "@PrimaryKey"

jdbc.allow-native-sql-queries

Use the eclipselink.jdbc.allow-native-sql-queries property to specify if user-defined (that is, native) SQL is allowed within a persistence unit.


Values

Table 5-42 describes this persistence property's values.

Table 5-42 Valid Values for jdbc.allow-native-sql-queries

Value Description

true

(Default) EclipseLink allows native SQL.

false

EclipseLink does not allow native SQL.


Usage

Within a multitenant, use this option to minimize the potential impact of revealing multitenant information. By default, any persistence unit with a multitenant entity causes EclipseLink to set eclipselink.jdbc.allow-native-sql-queries as false.


Examples

Example 5-39 shows how to use this property in the persistence.xml file.

Example 5-39 Using jdbc.allow-native-sql-queries in persistence.xml

<property name="eclipselink.jdbc.allow-native-sql-queries" value="false" />


See Also

For more information, see:

  • "Querying" in Understanding EclipseLink

jdbc.batch-writing

Use the eclipselink.jdbc.batch-writing property to configure batch writing to optimize transactions with multiple write functions.


Values

Table 5-43 describes this persistence property's values.

Table 5-43 Valid Values for jdbc.batch-writing

Value Description

jdbc

Use JDBC batch writing.

buffered

Do not use JDBC batch writing or the platform's native batch writing.

oracle-jdbc

Use the Oracle platform's native batch writing. In a property map, use OracleJDBC.

Note: This requires an Oracle JDBC driver.

custom-class

A custom class that extends the BatchWritingMechanism class.

none

(Default) Do not use batch writing (that is, turn it off).


Usage

Batch writing allows multiple heterogeneous dynamic SQL statements to be sent to the database as a single execution, or multiple homogeneous parameterized SQL statements to be executed as a single batch execution.


NoteNote:

Not all JDBC drivers or databases support batch writing.

Use eclipselink.jdbc.batch-writing.size to specify the batch size.


Examples

Example 5-40 shows how to use this property in the persistence.xml file.

Example 5-40 Using jdbc.batch-writing in persistence.xml

<property name="eclipselink.jdbc.batch-writing" value="Oracle-JDBC"/>

Example 5-41 shows how to use this property in a property map.

Example 5-41 Using jdbc.batch-writing in a Property Map

import org.eclipse.persistence.config.PersistenceUnitProperties;
propertiesMap.put(PersistenceUnitProperties.BATCH_WRITING,
BatchWriting.OracleJDBC);


See Also

For more information, see:

jdbc.batch-writing.size

Use the eclipselink.jdbc.batch-writing.size property to configure the batch size used for batch writing.


Values

Table 5-44 describes this persistence property's values.

Table 5-44 Valid Values for jdbc.batch-writing.size

Value Description

batch size

For parameterized batch writing, this value is the number of statements to batch (default: 100).

For dynamic batch writing, this value is the size of the batched SQL buffer (default: 32k).


Examples

Example 5-42 shows how to use this property in the persistence.xml file.

Example 5-42 Using jdbc.batch-writing.size in persistence.xml

<property name="eclipselink.jdbc.batch-writing.size" value="1000"/>


See Also

For more information, see:

jdbc.cache-statements

Use the eclipselink.jdbc.cache-statements property to specify if JDBC statements should be cached.


Values

Table 5-45 describes this persistence property's values.

Table 5-45 Valid Values for jdbc.cache-statements

Value Description

true

Enable internal statement caching.

false

(Default) Disable internal statement caching.


Usage

You should use this property when using EclipseLink's internal connection pooling. See "connection-pool" for more information.


Examples

Example 5-43 shows how to use this property in the persistence.xml file.

Example 5-43 Using jdbc.cache-statements in persistence.xml

<property name="eclipselink.jdbc.cache-statements" value="false"/>

Example 5-44 shows how to use this property in a property map.

Example 5-44 Using jdbc.cache-statements in a Property Map

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


See Also

For more information, see:

jdbc.cache-statements.size

Use the eclipselink.jdbc.cache-statements.size property to specify the number of statements held when using internal statement caching.


Values

Table 5-46 describes this persistence property's values.

Table 5-46 Valid Values for jdbc.cache-statements.size

Value Description

size

A string value containing a positive integer or zero (Default: 50).

The maximum value may vary, depending on your JDBC driver.


Examples

Example 5-45 shows how to use this property in the persistence.xml file.

Example 5-45 Using jdbc.cache-statements.size in persistence.xml

<property name="eclipselink.jdbc.cache-statements.size" value="100"/>

Example 5-46 shows how to use this property in a property map.

Example 5-46 Using jdbc.cache-statements.size in a Property Map

import org.eclipse.persistence.config.PersistenceUnitProperties;
propertiesMap.put(PersistenceUnitProperties.CACHE_STATEMENTS_SIZE, "100");


See Also

For more information, see:

jdbc.connector

Use the eclipselink.jdbc.connector property to define a custom connector to connect to the database.


Values

Table 5-47 describes this persistence property's values.

Table 5-47 Valid Values for jdbc.connector

Value Description

Fully qualified class name

A class that implements the Connector interface.


Usage

You can use this property to connect to a non-standard connection pool, or provide customized details on how to obtain a connection.

This property is not required when using a DataSource or JDBC DriverManager.


Examples

Example 5-47 shows how to use this property in the persistence.xml file.

Example 5-47 Using jdbc.connector in persistence.xml

<property name="eclipselink.jdbc.connector" value="package.MyConnector"/>

jdbc.exclusive-connection.is-lazy

Use the eclipselink.jdbc.exclusive-connection.is-lazy property to specify if EclipseLink acquires write connections lazily.


Values

Table 5-48 describes this persistence property's values.

Table 5-48 Valid Values for jdbc.exclusive-connection.is-lazy

Value Description

true

(Default) Acquire write connections lazily.

false

Do not acquire write connections lazily.


Examples

Example 5-48 shows how to use this property in the persistence.xml file.

Example 5-48 Using jdbc.exclusive-connection.is-lazy in persistence.xml

<property name="eclipselink.jdbc.exclusive-connection.is-lazy" value="false"/>

Example 5-49 shows how to use this property in a property map.

Example 5-49 Using jdbc.exclusive-connection.is-lazy in a Property Map

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


See Also

For more information, see:

jdbc.exclusive-connection.mode

Use the eclipselink.jdbc.exclusive-connection.mode property to specify when EclipseLink performs reads through the write connection.


Values

Table 5-49 describes this persistence property's values.

Table 5-49 Valid Values for jdbc.exclusive-connection.mode

Value Description

Transactional

(Default) Create an isolated client session if some or all entities require isolated cache, otherwise create a client session.

Notes:

  • EclipseLink keeps the connection exclusive for the duration of the transaction.

  • Inside the transaction, EclipseLink performs all writes and reads through the exclusive connection.

  • Outside the EclipseLink 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.

Notes:

  • 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.

  • Outside the EclipseLink transaction, only isolated entities are read through the exclusive connection. For non-isolated entities, EclipseLink acquires a new connection from the connection pool for each read and immediately releases the connection after executing the query.

Always

Create an exclusive isolated client session 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.


Usage

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.


Examples

Example 5-50 shows how to use this property in the persistence.xml file.

Example 5-50 Using jdbc.exclusive-connection.mode in persitence.xml

property name="eclipselink.jdbc.exclusive-connection.mode" value="Always"/>

Example 5-51 shows how to use this property in a property map.

Example 5-51 Using jdbc.exclusive-connection.mode in a Property Map

import org.eclipse.persistence.config.PersistenceUnitProperties;
propertiesMap.put(PersistenceUnitProperties.EXCLUSIVE_CONNECTION_MODE, "Always");


See Also

For more information, see:

jdbc.native-sql

Use the eclipselink.jdbc.native-sql property to specify if EclipseLink uses generic SLQ or includes platform-specific (that is, "native") SQL statements.


Values

Table 5-50 describes this persistence property's values.

Table 5-50 Valid Values for jdbc.native-sql

Value Description

true

(Default) Use platform-specific ("native" ) SQL.

false

Use generic SQL.


Usage

When using platform-specific SQL (eclipselink.jdbc.native-sql = true), EclipseLink uses platform-specific SQL to customize join syntax, date operators, using sequencing, and so on.


Examples

Example 5-52 shows how to use this property in the persistence.xml file.

Example 5-52 Using jdbc.native-sql in persistence.xml

<property name="eclipselink.jdbc.native-sql" value="false"/>

Example 5-53 shows how to use this property in a property map.

Example 5-53 Using jdbc.native-sql in a Property Map

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


See Also

For more information, see:

  • "Querying" in Understanding EclipseLink

  • "Query Languages" in Understanding EclipseLink

jdbc.property

Use the eclipselink.jdbc.property prefix to pass JDBC driver-specific connection properties to EclipseLink.


Usage

Append the JDBC driver-specific property name to this property prefix.


Examples

Example 5-54 shows how to use this property prefix in the persistence.xml file.

Example 5-54 Using jdbc.property in persistence.xml

<property name="eclipselink.jdbc.property.defaultRowPrefetch" value="25"/>


See Also

For more information, see:

  • "Using EclipseLink with the Oracle Database" in Solutions Guide for EclispeLink

  • "Introduction to Data Access" in Understanding EclipseLink

jdbc.sql-cast

Use the eclipselink.jdbc.sql-cast property to specify if EclipseLink uses platform-specific (that is, "native") CAST SQL operations.


NoteNote:

Normally, casting is not required. Using it may cause issues.


Values

Table 5-51 describes this persistence property's values.

Table 5-51 Valid Values for jdbc.sql-cast

Value Description

true

Use platform-specific CAST operations.

false

(Default) Do not use platform-specific CAST operations.


Examples

Example 5-55 shows how to use this property in the persistence.xml file.

Example 5-55 Using jdbc.sql-cast in persistence.xml

<property name="eclipselink.jdbc.sql-cast" value="true"/>

jdbc.uppercase-columns

Use the eclipselink.jdbc.uppercase-columns property to force column names from the metadata to be uppercase.


NoteNote:

This parameter has been replaced by jpql.parser, which ensures that both sides use uppercase for comparisons.


Values

Table 5-52 describes this persistence property's values.

Table 5-52 Valid Values for jdbc.uppercase-columns

Value Description

true

Forces all column names from the metadata to uppercase.

false

(Default) Does not force column names from the metadata to uppercase.


Usage

When using native SQL queries, the JDBC metadata may return column names in lower case on some platforms. If the column names are uppercase in the mappings (default), they will not match. You should use this parameter to force all column names from the metadata to uppercase.


Examples

Example 5-56 shows how to use this parameter in the persistence.xml file.

Example 5-56 Using jdbc.uppercase-column-names in persistence.xml

<property name="eclipselink.jpa.uppercase-columns" value="true"/>


See Also

For more information, see:

  • "jpql.parser"

  • "Using EclipseLink with the Oracle Database" in Solutions Guide for EclispeLink

  • "Introduction to Data Access" in Understanding EclipseLink

jpql.parser

Use the eclipselink.jpql.parser property to configure the JPQL parser parameters.


Values

Table 5-53 describes this persistence property's values.

Table 5-53 Valid Values for jpql.parser

Value Description

org.eclipse.persistence.internal.jpa.jpql.HermesParser

(Default) Current parser, starting with EclipseLink 2.4, that provides extended JPQL support.

org.eclipse.persistence.queries.ANTLRQueryBuilder

Old parser, used for backward compatibility (prior to EclipseLink 2.4).


See Also

For more information, see:

jpa.uppercase-column-names

Use the eclipselink.jpa.uppercase-column-names property to specify JPA processing to uppercase all column name definitions (simulating case insensitivity).


Values

Table 5-54 describes this persistence property's values.

Table 5-54 Valid Values for jpa.uppercase-column-names

Value Description

true

JDBC metadata returned from the database is returned in uppercase, ensuring fields are the same case. Sets jdbc.uppercase-columns to true.

false

(Default) Does not return JDBC metadata in uppercase.


Usage

Use this property to correct situations in which user-defined fields do not match the case returned by the database for native queries.


Examples

Example 5-57 shows how to use this property in the persistence.xml file.

Example 5-57 Using jpa.uppercase-column-names in persistence.xml

<property name="eclipselink.jpa.uppercase-column-names" value="true"/>


See Also

For more information, see:

  • "jdbc.uppercase-columns"

  • "Using EclipseLink with the Oracle Database" in Solutions Guide for EclispeLink

  • "Introduction to Data Access" in Understanding EclipseLink

jpql.validation

Use the eclipselink.jpql.parser property to configure the JPQL parser validation level.


Values

Table 5-55 describes this persistence property's values.

Table 5-55 Valid Values for jpql.validation

Value Description

EclipseLink

(Default) Allows EclipseLink JPAL extensions.

JPA 1.0

Allows valid JPA 1.0 JPQL only.

JPA 2.0

Allows valid JPA 2.0 JPQL only.

JPA 2.1

Allows valid JPA 2.1 JPQL only.

None

No JPQL validation.


Usage

This parameter applies only when eclipselink.jpql.parser is HermesParser.


Examples

Example 5-58 shows how to use this property in the persistence.xml file.

Example 5-58 Using jpql.validation in persistence.xml

<property name="eclipselink.jpql.validation" value="JPA 1.0"/>


See Also

For more information, see:

logging.connection

Use the eclipselink.logging.connection property to specify if connections are logged.


Values

Table 5-56 describes this persistence property's values.

Table 5-56 Valid Values for logging.connection

Value Description

true

(Default) Logs the connection name.

false

Does not log the connection name.


Usage

Using this parameter means that all connections are logged and not masked by the application code.


Examples

Example 5-59 shows how to use this parameter in the persistence.xml file.

Example 5-59 Using logging.connection in persistence.xml

<property name="eclipselink.logging.connection" value="false"/>


See Also

For more information, see:

logging.exceptions

Use the eclipselink.logging.exceptions property to specify if exceptions are logged when they are thrown, before returning the exception to the calling application.


Values

Table 5-57 describes this persistence property's values.

Table 5-57 Valid Values for logging.exceptions

Value Description

true

(Default) Logs exceptions when they are thrown.

false

Does not log exceptions when they are thrown.


Usage

Using this property ensures that all exceptions are logged and not masked by the application code.


Examples

Example 5-60 shows how to use this property in the peristence.xml file.

Example 5-60 Using logging.exceptions in persistence.xml file

<property name="eclipselink.logging.exceptions" value="false" />

Example 5-61 shows how to use this property in a property map.

Example 5-61 Using logging.exceptions in a Property Map

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


See Also

For more information, see:

logging.file

Use the eclipselink.logging.file property to specify a file location in which to output the log instead of the standard out.


Values

Table 5-58 describes this persistence property's values.

Table 5-58 Valid Values for logging.file

Value Description

directory name

A string location to a directory in which you have write access. The location may be relative to your current working directory or an absolute location.


Usage

This property applies when used in a Java SE environment.


Examples

Example 5-62 shows how to use this property in the peristence.xml file.

Example 5-62 Using logging.file in persistence.xml file

<property name="eclipselink.logging.file" value="C:\myout\" />

Example 5-63 shows how to use this property in a property map.

Example 5-63 Using logging.file in a Property Map

import org.eclipse.persistence.config.PersistenceUnitProperties;
propertiesMap.put(PersistenceUnitProperties.LOGGING_FILE, "C:\myout\");


See Also

For more information, see:

logging.level

Use the eclipselink.logging.level property to specify a specific logging level and control the amount and detail that is emitted.


Values

Table 5-59 describes this persistence property's values.

Table 5-59 Valid Values for logging.level

Value Description

OFF

Disables logging.

You may want to use OFF during production in order to avoid the overhead of logging.

SEVERE

Logs exceptions indicating that EclipseLink cannot continue, as well as any exceptions generated during login. This includes a stack trace.

WARNING

Logs exceptions that do not force EclipseLink to stop, including all exceptions not logged with SEVERE level. This does not include a stack trace.

INFO

(Default) Logs the login/logout per sever session, including the user name. After acquiring the session, detailed information is logged.

CONFIG

Logs only login, JDBC connection, and database information. You may want to use this log level at deployment time.

FINE

Logs all SQL. You may want to use this log level during debugging and testing, but not at production time.

FINER

Similar to WARNING, but includes stack trace. You may want to use this log level during debugging and testing, but not at production time.

FINEST

Similar to FINER, but includes additional low level information. You may want to use this log level during debugging and testing, but not at production time.

ALL

Logs at the same level as FINEST.


Examples

Example 5-64 shows how to use this property in the peristence.xml file.

Example 5-64 Using logging.level in persistence.xml file

<property name="eclipselink.logging.level" value="OFF" />

Example 5-65 shows how to use this property in a property map.

Example 5-65 Using logging.level in a Property Map

import java.util.logging.Level;
import org.eclipse.persistence.config.PersistenceUnitProperties;
propertiesMap.put(PersistenceUnitProperties.LOGGING_LEVEL, Level.OFF);


See Also

For more information, see:

logging.logger

Use the eclipselink.logging.logger property to define the type of logger to use.


Values

Table 5-60 describes this persistence property's values.

Table 5-60 Valid Values for logging.logger

Value Description

Custom logger

Fully qualified class name of a custom logger which implements org.eclipse.persistence.logging.SessionLog.

JavaLogger

Uses java.util.logging.

ServerLogger

Integrates with the application server's logging.

DefaultLogger

(Default) Uses EclipseLink's native logger, DefaultSessionLog.


Examples

Example 5-66 shows how to use this parameter in the persistence.xml file.

Example 5-66 Using logging.logger in persistence.xml

<property name="eclipselink.logging.logger" value="JavaLogger"/>

Example 5-67 shows how to use this parameter in a property map.

Example 5-67 Using logging.logger in a Property Map

import org.eclipse.persistence.config.PersistenceUnitProperties;
propertiesMap.put(PersistenceUnitProperties.LOGGING_LOGGER,
"acme.loggers.MyCustomLogger";


See Also

For more information, see:

logging.parameters

Use the eclipselink.logging.parameters property to define if SQL bind parameters are included in exceptions and logs.


NoteNote:

This parameter applies to bind parameters only. Parameters are always displayed when not using binding.


Values

Table 5-61 describes this persistence property's values.

Table 5-61 Valid Values for logging.parameters

Value Description

true

(Default) Display the parameters.

false

Do not display the parameters.


Usage

By default, when using logging.level of FINE (or greater), SQL bind parameters are displayed. Use this parameter to override the default behavior.


Examples

Example 5-58 shows how to use this parameter in the persistence.xml file.

Example 5-68 Using logging.parameters in persistence.xml

<paramter name="eclipselink.logging.parameters" value="false"/>


See Also

For more information, see:

logging.session

Use the eclipselink.logging.session property to specify if EclipseLink should include a session identifier in each log message.


Values

Table 5-62 describes this persistence property's values.

Table 5-62 Valid Values for logging.session

Value Description

true

(Default) Log a session identifier.

false

Do not log a session identifier.


Usage

This setting is applicable to messages that require a database connection such as SQL and the transaction information to determine on which underlying session (if any) the message was sent.


Examples

Example 5-69 shows how to use this property in the peristence.xml file.

Example 5-69 Using logging.session in persistence.xml file

<property name="eclipselink.logging.session" value="false" />

Example 5-70 shows how to use this property in a property map.

Example 5-70 Using logging.session in a Property Map

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


See Also

For more information, see:

logging.thread

Use the eclipselink.logging.thread property to specify if EclipseLink should include a thread identifier in each log message.


Values

Table 5-63 describes this persistence property's values.

Table 5-63 Valid Values for logging.thread

Value Description

true

(Default) Log a thread identifier.

false

Do not log a thread identifier.


Usage

You should use this property when running multi-threaded applications. EclipseLink will include a hashcode of the thread.


Examples

Example 5-71 shows how to use this property in the peristence.xml file.

Example 5-71 Using logging.thread in persistence.xml file

<property name="eclipselink.logging.thread" value="false" />

Example 5-72 shows how to use this property in a property map.

Example 5-72 Using logging.thread in a Property Map

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


See Also

For more information, see:

logging.timestamp

Use the eclipselink.logging.timestamp property to specify if EclipseLink should include a timestamp in each log message.


Values

Table 5-64 describes this persistence property's values.

Table 5-64 Valid Values for logging.timestamp

Value Description

true

(Default) Log a timestamp.

false

Do not log a timestamp.


Examples

Example 5-73 shows how to use this property in the peristence.xml file.

Example 5-73 Using logging.timestamp in persistence.xml file

<property name="eclipselink.logging.timestamp" value="false" />

Example 5-74 shows how to use this property in a property map.

Example 5-74 Using logging.timestamp in a Property Map

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


See Also

For more information, see:

metadata-source

Use the eclipselink.metadata-source property to specify the MetadataSource implementation EclipseLink uses to read metadata.


Values

Table 5-65 describes this persistence property's values.

Table 5-65 Valid Values for metadata-source

Value Description

XML

Use XMLMetadataSource.

Custom metadata source

A custom class name which implements MetadataSource.


Usage

Use this property with eclipselink.metadata-source.xml.file to access an external mapping file at a fixed URL for a persistence unit.


Examples

Example 5-75 shows how to use this property in the persistence.xml file.

Example 5-75 Using metadata-source in persistence.xml

<property name="eclipselink.metadata-source" value="xml"/>
<property name="eclipselink.metadata-source.xml.file" value="c:/myfile.xml"/>


See Also

For more information, see:

metadata-source.properties.file

Use the eclipselink.metadata-source.properties.file property to specify the name of the metadata repository properties file to read from, using the classloader to find the resource.


Values

Table 5-66 describes this persistence property's values.

Table 5-66 Valid Values for metadata-repository.properties.file

Value Description

Filename

Name of the metadata source XML file.


Usage

Use this property with eclipselink.metadata-source when using an XML repository.


Examples

Example 5-76 shows how to use this property in the persistence.xml file.

Example 5-76 Using metadata-source.properties.file in persistence.xml

<property name="eclipselink.metadata-source.properties.file"
value="c:\myproperties.xml"/>


See Also

For more information, see:

metadata-source.send-refresh-command

Use the eclipselink.metadata-source.send-refresh-command property with cache coordination for a clustered environment to control how EclipseLink sends RCM refresh metadata commands to the cluster.


Values

Table 5-67 describes this persistence property's values.

Table 5-67 Valid Values for metadata-source.send-refresh-command

Value Description

true

(Default) To propogate refresh commands to the cluster, you must configure RCM and use the eclipselink.deploy-on-startup property.

false

Does not propagate refresh commands to the cluster.


Usage

If cache coordination is configured and the session is deployed on startup, this property controls the sending of RCM refresh metadata commands to the cluster.

These commands will cause the remote instances to refresh their metadata.


Examples

Example 5-77 shows how to use this property in the persistence.xml file.

Example 5-77 Using metadata-source.send-refresh-command in persistence.xml

<property name="eclipselink.metadata-source-refresh-command" value="false"/>

Example 5-78 shows how to use this property in a property map.

Example 5-78 Using metadata-source-refresh-command in a Property Map

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


See Also

For more information, see:

metadata-source.xml.file

Use the eclipselink.metadata-repository.xml.file property to specify the name of the metadata repository XML file to read from, using the classloader to find the resource.


Values

Table 5-68 describes this persistence property's values.

Table 5-68 Valid Values for metadata-source.xml.file

Value Description

filename

Metadata repository.xml file.


Usage

Use this property with the eclipselink.metadata-source property when using an XML repository.


Examples

Example 5-79 shows how to use this property in the persistence.xml file.

Example 5-79 Using metadata-source.xml.file in persistence.xml

<property name="eclipselink.metadata-source" value="xml"/>
<property name="eclipselink.metadata-source.xml.file" value="c:/myfile.xml"/>


See Also

For more information, see:

metadata-source.xml.url

Use the eclipselink.metadata-source.xml.url property to specify the location of an external mapping file.


Values

Table 5-69 describes this persistence property's values.

Table 5-69 Valid Values for metadata-source.xml.url

Value Description

url

Specifies the metadata repository of the XML URL.


Usage

The metadata-source property must be set to XML.


Examples

Example 5-75 shows how to use this property in the persistence.xml file.

Example 5-80 Using metadata-source.xml.url in persistence.xml

<property name="eclipselink.metadata-source" value="xml"/>
<property name="eclipselink.metadata-source.xml.url" value="http://myfile.xml"/>


See Also

For more information, see:

multitenant.tenants-share-cache

Use the eclipselink.multitenant.tenants-share-cache property to specify if multitenant entities will share the L2 cache.


Values

Table 5-70 describes this persistence property's values.

Table 5-70 Valid Values for multitenant.tenants-share-cache

Value Description

true

Multitenant entities will use an protected cache.

false

(Default) Multitenant entities will use an isolated cache.


Usage


WARNING:

When this setting is false, queries that use the cache may return data from other tenants when using the PROTECTED setting.


Examples

Example 5-81shows how to use this property in the persistence.xml file.

Example 5-81 Using multitenant.tenants-share-cache in persistence.xml

<property name="eclipselink.multitenant.tenants-share-cache" value="true" />

Example 5-82 shows how to use this property in a property map.

Example 5-82 Using multitenant.tenants-share-cache in a Property Map

import org.eclipse.persistence.config.PersistenceUnitProperties;
propertiesMap.put(PersistenceUnitProperties.MULTITENANT_TENANTS_SHARE_CACHE,
"true");


See Also

For more information, see:

multitenant.tenants-share-emf

Use the eclipselink.multitenant.shared-emf property to specify if multitenant entities will be used within a shared entity manager factory.


Values

Table 5-71 describes this persistence property's values.

Table 5-71 Valid Values for multitenant.tenants-share-emf

Value Description

true

(Default) Multitenant entities will be used.

false

Specify a unique session name.


Usage

When setting it to false, you are required to provide a unique session name.


Examples

Example 5-83 shows how to use this property in the persistence.xml file.

Example 5-83 Using multitenant.tenants-share-emf in persistence.xml

<property name="eclipselink_multitenant_tenants_share_emf" value="true" />


See Also

For more information, see:

nosql.connection-factory

Use the eclipselink.nosql.connection-factory property to specify the JNDI name of a JCA ConnectionFactory or a JCA ConnectionFactory class name that connects to the NoSQL data-source.


Values

Table 5-72 describes this persistence property's values.

Table 5-72 Valid Values for nosql.connection-factory

Value Description

connection factory

JNDI name or class name of the JCA Connection Factory.


Usage

This property allows the JCA ConnectionFactory to be used with a NoSql or EIS adapter for a NoSQL datasource (that is, a non-relationship datasource such as a legacy database, NoSQL database, XML database, transactional and messaging systems, or ERP systems).


Examples

Example 5-84 shows how to use this property in the persistence.xml file.

Example 5-84 Using nosql.connection-factory in persistence.xml

<property name="eclipselink.nosql.connection-factory" 
value="MyConnectionFactory" />


See Also

For more information, see:

nosql.connection-spec

Use the eclipselink.nosql.connection-spec property to specify an EISConnectionSpec class name that defines how to connect to the NoSQL datasource.


Values

Table 5-73 describes this persistence property's values.

Table 5-73 Valid Values for nosql.connection-spec

Value Description

classname

IESConnectionSpec classname


Usage

This property allows the JCA ConnectionFactory to be used with a NoSql or EIS adapter for a NoSQL datasource (that is, a non-relationship datasource such as a legacy database, NoSQL database, XML database, transactional and messaging systems, or ERP systems).


Examples

See Example 5-85 for information on how to use this property.


See Also

For more information, see:

nosql.property

Use the eclipselink.nosql.property property to set NoSQL-specific connection properties.


Values

Table 5-74 describes this persistence property's values.

Table 5-74 Valid Values for nosql.property

Value Description

property name

A NoSQL property.


Usage

Append the NoSQL-specific property name to this property.


Examples

Example 5-85 shows how to use this property in the persistence.xml file.

Example 5-85 Using nosql.property in persistence.xml

<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.target-database"
            value="org.eclipse.persistence.nosql.adapters.mongo.MongoPlatform"/>
            <property name="eclipselink.nosql.connection-spec"
        value="org.eclipse.persistence.nosql.adapters.mongo.MongoConnectionSpec"/>
            <property name="eclipselink.nosql.property.mongo.port" value="27017,
            27017"/>
            <property name="eclipselink.nosql.property.mongo.host" value="host1,
            host2"/>
            <property name="eclipselink.nosql.property.mongo.db" value="acme"/>
        </properties>
    </persistence-unit>
</persistence>


See Also

For more information, see:

oracle.proxy-type

Use the eclipselink.oracle.proxy-type property to specify the proxy type to be passed to the OracleConnection.openProxySession method.


Values

Table 5-75 describes this persistence property's values.

Table 5-75 Valid Values for oracle.proxy-type

Value Description

USER_NAME

This type uses a user name for authentication when creating a proxy connection.

DISTINGUISED_NAME

This type uses a distinguished name for authentication when creating a proxy connection.

CERTIFICATE

This type uses a digital certificate for authentication when creating a proxy connection.


Usage

This property requires Oracle JDBC version 10.1.0.2 or later and eclipselink.target-database must be configured to use Oracle9 or later.

Typically, you should set this property into EntityManager, through a createEntityManager method or by using proprietary setProperties method on EntityManagerImpl. This causes EntityManager to use proxy connection for writing and reading inside transaction.

If proxy-type and the corresponding proxy property set into EntityManagerFactory, all connections created by the factory will be proxy connections.


Examples

Example 5-86 shows how to use the property with EntityManager.

Example 5-86 Using eclipselink.oracle.proxy-type with EntityManager

Map emProperties = new HashMap();
emProperties.put("eclipselink.oracle.proxy-type", 
OracleConnection.PROXYTYPE_USER_NAME);
emProperties.put(OracleConnection.PROXY_USER_NAME, "john");
EntityManager em = emf.createEntityManager(emProperties);

With injection:

entityManager.setProperty(”eclipselink.oracle.proxy-type”,
OracleConnection.PROXYTYPE_USER_NAME);
entityManager.setProperty(OracleConnection.PROXY_USER_NAME, ”john”);


See Also

For more information, see:

orm.throw.exceptions

Use the eclipselink.orm.throw.exceptions property to specify if EclipseLink throws an exception or logs a warning when encountering a problem with any of the files in the <mapping-file> element of the persistence.xml file.


Values

Table 5-76 describes this persistence property's values.

Table 5-76 Valid Values for orm.throw.exceptions

Value Description

true

(Default) Throw an exception.

false

Log a warning only.


Examples

Example 5-87 shows how to use this property in the persistence.xml file.

Example 5-87 Using orm.throw.exceptions in persistence.xml

<property name="oracle.orm.throw.exceptions" value="false"/>

Example 5-88 shows how to use this property in a property map.

Example 5-88 Using orm.throw.exceptions in a Property Map

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


See Also

For more information, see:

orm.validate.schema

Use the orm.validate.schema property to override orm.xml schema validation from its default value of false.


Values

Table 5-77 describes this persistence property's values.

Table 5-77 Valid Values for orm.validate.schema

Value Description

true

Enables schema velidation on on orm.xml file.

false

(Default) No schema validation is performed on the orm.xml file.


Usage

Use orm.validate.schema to enable orm.xml schema validation.


Examples

Example 5-89 shows how to use this property in the persistence.xml file.

Example 5-89 Using orm.validate.schema in persistence.xml

<property name="eclipselink.orm.validate.schema" value="true"/>

Example 5-90 shows how to use this property in a property map.

Example 5-90 Using orm.validate.schema in a Property Map

import org.eclipse.persistence.config.PersistenceUnitProperties;
propertyMap.put(PersistenceUnitProperties.ORM_VALIDATE_SCHEMA, "true");

partitioning

Use the eclipselink.partitioning property to set the default PartitioningPolicy for a persistence unit. The value must be the name of an existing, defined PartitioningPolicy.


Values

Table 5-78 describes this persistence property's values.

Table 5-78 Valid Values for partitioning

Value Description

name

An existing, defined PartitioningPolicy.


Usage

Use this property to partition data for a class across multiple difference databases or across a database cluster such as Oracle RAC. Partitioning may provide improved scalability by allowing multiple database machines to service requests.

If multiple partitions are used to process a single transaction, use JTA (Java Transcription API) for proper XA transaction support.


Examples

Example 5-91 shows how to use this property in the persistence.xml file.

Example 5-91 Using partitioning in persistence.xml

<property name="eclipselink.partitioning" value="Replicate" />


See Also

For more information, see:

partitioning.callback

Use the eclipselink.partitioning.callback property to integrate an external DataSource's affinity support, such as UCP.


Values

Table 5-79 describes this persistence property's values.

Table 5-79 Valid Values for eclipselink.partitioning.callback

Value Description

value

A class that implements the DataPartitioningCallBack interface.


Usage

The value must be set to the full class name.


Examples

Example 5-92 shows how to use this property in the persistence.xml file.

Example 5-92 Using partitioning.callback in persistence.xml

<property name="eclipselink.partitioning.callback"
value="mypacakge.MyDataPartitioningCallback"/>

Example 5-93 shows how to use this property in a property map.

Example 5-93 Using partitioning.callback in a Property Map

import org.eclipse.persistence.config.PersistenceUnitProperties;
propertiesMap.put(PersistenceUnitProperties.PARTITIONING_CALLBACK,
"mypackage.MyDataPartitioningCallback");

persistence-context.close-on-commit

Use the eclipselink.persistence-context.close-on-commit property to specify if the EntityManager will be closed or not used after commit (not extended).


Values

Table 5-80 describes this persistence property's values.

Table 5-80 Valid Values for persistence-context.close-on-commit

Value Description

true

Closes the EntityManager after a commit.

false

(Default) Does not close the EntityManager after a commit.


Usage

For a container-managed EntityManager and most managed applications, you normally set this property to false. This setting avoids additional performance overhead of resuming the persistence context after a commit() transaction.

The property set in persistence.xml or passed to createEntityManagerFactory affects all EntityManagers created by the factory. Alternatively, to apply the property to specific EntityManagers, pass it to createEntityManager method.


Examples

Example 5-94 shows how to use this property in the persistence.xml file.

Example 5-94 Using persistence-context.close-on-commit in persistence.xml

<property name="eclipselink.persistence-context.close-on-commit" value="true"/>

Example 5-95 shows how to use this property in a property map.

Example 5-95 Using persistence-context.close-on-commit in a Property Map

import org.eclipse.persistence.config.PersistenceUnitProperties;
propertiesMap.put(PersistenceUnitProperties.PERSISTENCE_CONTEXT_CLOSE_ON_COMMIT,
"true");

persistence-context.commit-without-persist-rules

Use the eclipselink.persistence-context.commit-without-persist-rules property to specify if the EntityManager will search all managed objects and persist any related non-managed new objects that are found, ignoring any absence of CascadeType.PERSIST settings.


Values

Table 5-81 describes this persistence property's values.

Table 5-81 Valid Values for persistence-context.commit-without-persist-rules

Value Description

true

Cascades Entity life-cycle Persist operations to related entities and uses the CascadeType.PERSIST settings.

false

(Default) Does not cascase Entitiy life-cycle Persist operations to related entities and does not use the CascadeType.PERSIST settings.


Usage

Setting this property to true replicates the traditional EclipseLink native functionality.


Examples

Example 5-96 shows how to use this property in the persistence.xml file.

Example 5-96 Using persistence-context.commit-without-persist-rules in persistence.xml

<property name="eclipse.persistence-context.commit-without-persist-rules"
value="true"/>

Example 5-97 shows how to use this property in a property map.

Example 5-97 Using persistence-context.commit-without-persist-rules in a Property Map

import org.eclipse.persistence.config.PersistenceUnitProperties;
propertiesMap.put
(PersistenceUnitProperties.PERSISTENCE_CONTEXT_COMMIT_WITHOUT_PERSIST_RULES,
"true");

persistence-context.flush-mode

Use the eclipselink.persistence-context.flush-mode property to configure the EntityManager FlushMode to be set as a persistence property and specify when flushing occurs.


Values

Table 5-82 describes this persistence property's values.

Table 5-82 Valid Values for persistence-context.flush-mode

Value Description

auto

(Default) Flushing occurs at query execution.

commit

Flushing occurs at transaction commit.


Usage

The property set in persistence.xml or passed to createEntityManagerFactory affects all EntityManagers created by the factory. To apply the property to specific EntityManagers pass it to the createEntityManager method.


Examples

Example 5-98 shows how to use this property in the persistence.xml file.

Example 5-98 Using persistence-context.flush-mode in persistence.xml

<property name="eclipselink.persistence-context.flush-mode" value="commit" />

Example 5-99 shows how to use this property in a property map.

Example 5-99 Using persistence-context.flush-mode in a Property Map

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


See Also

For more information, see:

  • "flush"

  • "Enhancing Performance" in Solutions Guide for EclispeLink

persistence-context.persist-on-commit

Use the eclipselink.persistence-context.persist-on-commit property to specify if the EntityManager searches all managed objects and persists any related non-managed new objects that are cascade persist. This can be used to avoid the cost of performing this search if persist is always used for new objects.


Values

Table 5-83 describes this persistence property's values.

Table 5-83 Valid Values for persistence-context.persist-on-commit

Value Description

true

(Default) Searches and persists related non-managed new objects that are cascade persist.

false

Does not search and persist related non-managed new objects that are cascade persist.


Usage

The property set in persistence.xml or passed to createEntityManagerFactory affects all EntityManagers created by the factory. To apply the property to specific EntityManagers pass it to createEntityManager method.


Examples

Example 5-100 shows how to use this property in the persistence.xml file.

Example 5-100 Using persistence-context.persist-on-commit in persistence.xml

<property name="eclipselink.persistence-context.persist-on-commit" value="false"/>

Example 5-101 show how to use this property in a property map.

Example 5-101 Using persistence-context.persis-on-commit in a Property Map

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

persistence-context.reference-mode

Use the eclipselink.persistence-context.reference-mode property to specify if hard or soft (that is, weak) references are used within the Persistence Context.


Values

Table 5-84 describes this persistence property's values.

Table 5-84 Valid Values for persistence-context.reference-mode

Value Description

hard

(Default) EclipseLink references all objects through hard references. These objects will not be available for garbage collection until the referencing artifact (such as the persistence context or unit of work) is released/cleared or closed.

weak

References to objects supporting active attribute change tracking (see "@ChangeTracking") 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.

Note: Any changes that have not been flushed in these entities will be lost.

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

All objects, including non-change-tracked objects, are to be held by weak references. When a change is made to a change-tracked object (see "@ChangeTracking"), 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.


Usage

The property set in persistence.xml or passed to createEntityManagerFactory affects all EntityManagers created by the factory. To apply the property to specific EntityManagers pass it to createEntityManager method.


Examples

Example 5-102 shows how to use this property in a persistence.xml file.

Example 5-102 Using persistence-context.reference-mode in persistence.xml

<property name="eclipselink.persistence-context.reference-mode" 
value="FORCE_WEAK"/>

Example 5-103 shows how to use this property in a property map.

Example 5-103 Using persistence-context.reference-mode in a Property Map

import org.eclipse.persistence.config.PersistenceUnitProperties;
propertiesMap.put(PersistenceUnitProperties.PERSISTENCE_CONTEXT_REFERENCE_MODE,
ReferenceMode.FORCE_WEAK);


See Also

For more information, see:

persistenceunits

Use the eclipselink.persistenceunits property to specify the set of persistence unit names that will be processed when generating the canonical model. By default, EclipseLink uses all persistence units available in all persistence XML files.


Values

Table 5-85 describes this persistence property's values.

Table 5-85 Valid Values for persistenceunits

Value Description

names

A comma separated list of persistence units

Note: When specifying multiple persistence units, you cannot include a comma ( , ) in the name of a persistence unit.


Examples

Example 5-104 shows how to use this property in the persistence.xml file.

Example 5-104 Using persistenceunits in persistence.xml

<property name="eclipselink.persistenceunits" value="mypu1, mypu2"/>

persistencexml

Use the eclipselink.persistencexml property to specify the full resource name in which to look for the persistence XML files. If omitted, EclipseLink uses the default location: META-INF/persistence.xml.


NoteNote:

Currently, this property is used only for the canonical model generator.


Values

Table 5-86 describes this persistence property's values.

Table 5-86 Valid Values for persistencexml

Value Description

resource name

Location of the persistence.xml file.


Usage

This property is only used by EclipseLink when it is locating the configuration file. When used within an EJB/Spring container in container-managed mode, the locating and reading of this file is done by the container and will not use this configuration.

If you want to change the default location, use persisencexml.default.


Examples

Example 5-105 shows how to use this property in the persistence.xml file.

Example 5-105 Using persistencexml in persistence.xml

<property name="eclipselink.persistencexml" value="resources/persistence.xml"/>


See Also

For more information, see:

persisencexml.default

Use the eclipselink.persistencexml.default property to specify the default resource location where the persistence.xml configuration file is located. The default location is META-INF/persistence.xml.


Values

Table 5-87 describes this persistence property's values.

Table 5-87 Valid Values for persistencexml.default

Value Description

resource location

Default resource location of the persistence.xml file.


Examples

Example 5-106 shows how to use this property in a property map.

Example 5-106 Using persistencexml.default in a Property Map

import org.eclipse.persistence.config.PersistenceUnitProperties;
propertiesMap.put(PersistenceUnitProperties.ECLIPSELINK_PERSISTENCE_XML_DEFAULT,
"resources/persistence.xml");

profiler

Use the eclipselink.profiler property to specify which performance profiler to use in order to capture runtime statistics.


Values

Table 5-88 describes this persistence property's values.

Table 5-88 Valid Values for profiler

Value Description

NoProfiler

(Default) Do not use a performance profiler.

PerformationMonitor

Use EclipseLink performance monitor org.eclipse.persistence.tools.profiler.PerformanceMonitor.

PerformanceProfiler

Use EclipseLink performance profiler (org.eclipse.persistence.tools.profiler.PerformanceProfiler).

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.

DMSProfiler

Use org.eclipse.persistence.tools.profiler.oracle.DMSPerformanceProfiler. This property is specific to the Oracle Dynamic Monitoring Service (DMS).

Custom profiler

Specify a custom profiler class name which implements SessionProfiler and provides a no-argument constructor.


Examples

Example 5-107 shows how to use this property in the persistence.xml file.

Example 5-107 Using profiler in persistence.xml

<property name="eclipselink.profiler" value="PerformanceProfiler"/>

Example 5-108 shows how to use this property in a property map.

Example 5-108 Using profiler in a Property Map

import org.eclipse.persistence.config.ProfilerType;
import org.eclipse.persistence.config.PersistenceUnitProperties;
propertiesMap.put(PersistenceUnitProperties.PROFILER,
ProfilerType.PerformanceProfiler);


See Also

For more information, see:

session.customizer

Use the eclipselink.session.customizer property to specify a session customizer class that implements the org.eclipse.persistence.config.SessionCustomizer interface. The class must provide a default, no argument constructor.


Values

Table 5-89 describes this persistence property's values.

Table 5-89 Valid Values for session.customizer

Value Description

class name

Fully qualified class name of a SessionCustomizer class.


Usage

You can use the customize method of the class (which takes an org.eclipse.persistence.sessions.Session) to programmatically access advanced EclipseLink session API. You can use the session customizer class to define multiple session event listeners.


Examples

Example 5-109 shows how to use this property in the persistence.xml file.

Example 5-109 Using session.customizer in persistence.xml

<property name="eclipselink.session.customizer"
value="acme.sessions.MySessionCustomizer"/>

Example 5-110 shows how to use this property in a property map.

Example 5-110 Using session.customizer in a Property Map

import org.eclipse.persistence.config.PersistenceUnitProperties;
propertiesMap.put(PersistenceUnitProperties.SESSION_CUSTOMIZER,
"acme.sessions.MySessionCustomizer");


See Also

For more information, see:

session.include.descriptor.queries

Use the eclipselink.session.include.descriptor.queries property to specify whether all descriptor named queries are copied to the session for use by the entity manager.


Values

Table 5-90 describes this persistence property's values.

Table 5-90 Valid Values for session.include.descriptor.queries

Value Description

true

Copying is enabled.

false

(Default) Copying is disabled.


Examples

Example 5-111 shows how to use this property in the persistence.xml file.

Example 5-111 Using session.include.descriptor.queries in persistence.xml

<property name="eclipselink.session.include.descriptor.queries" value="true"/>

Example 5-112 shows how to use this property in a property map.

Example 5-112 Using session.include.descriptor.queries in a Property Map

import org.eclipse.persistence.config.PersistenceUnitProperties;
propertiesMap.put(PersistenceUnitProperties.INCLUDE_DESCRIPTOR_QUERIES, "true");

session-event-listener

Use the eclipselink.session-event-listener property to specify a descriptor event listener to be added during bootstrapping.


Values

Table 5-91 describes this persistence property's values.

Table 5-91 Valid Values for session-event-listener

Value Description

Class name

A qualified class name for a class that implements the org.eclipse.persistence.sessions.SessionEventListener interface.


Usage

To define multiple event listener, you can use a session.customizer class.


Examples

Example 5-113 shows how to use this property in a persistence.xml file.

Example 5-113 Using session-event-listener in persistence.xml

<property name="eclipselink.session-event-listener"
value="mypackage.MyClass.class"/>

Example 5-113 shows how to use this property in a property map.

Example 5-114 Using session-event-listener in a Property Map

import org.eclipse.persistence.config.PersistenceUnitProperties;
propertiesMap.put(PersistenceUnitProperties.SESSION_EVENT_LISTENER_CLASS,
"mypackage.MyClass.class");


See Also

For more information, see:

session-name

Use the eclipselink.session-name property to configure a unique name to use when storing the singleton server session within the SessionManager.


Values

Table 5-92 describes this persistence property's values.

Table 5-92 Valid Values for session.name

Value Description

Name

Unique session name to use instead of the default, EclipseLink-generated session name.


Usage

By default, EclipseLink generates a unique session name. You can provide a custom, unique, session name with this property.

When using a sessions-xml file, you must include this session name as the name of the session in the sessions-xml file.


Examples

Example 5-115 shows how to use this property in the persistence.xml file.

Example 5-115 Using session-name in persistence.xml

<property name="eclipselink.session-name" value="MySession"/>

Example 5-116 shows how to use this property in a property map.

Example 5-116 Using session-name in a Property Map

import org.eclipse.persistence.config.PersistenceUnitProperties;
propertiesMap.put(PersistenceUnitProperties.SESSION_NAME, "MySession");


See Also

For more information, see:

sessions-xml

Use the eclipselink.sessions-xml property to use a specified native sessions.xml configuration file (which references a project.xml file) to load configuration and mapping information instead of JPA annotations or EclipseLink XML (as shown in Figure 5-1).


Values

Table 5-93 describes this persistence property's values.

Table 5-93 Valid Values for sessions-xml

Value Description

configuration file

The resource name of the sessions XML file. If you do not specify the value for this property, it will not be used.


Usage

You can use the eclipselink.sessions-xml property as an alternative to using annotations and deployment XML. With this property, EclipseLink builds an in-memory EclipseLink session and project based on this metadata (as shown in Figure 5-1). You can acquire a persistence manager and use it, having defined all entities and so on using only EclipseLink sessions.xml.

Figure 5-1 Using the eclipselink.sessions-xml Persistence Property

Description of Figure 5-1 follows
Description of "Figure 5-1 Using the eclipselink.sessions-xml Persistence Property"


Examples

Example 5-117 shows how to use this property in a persistence.xml file.

Example 5-117 Using sessions-xml in the persistence.xml file

<property name="eclipselink.sessions-xml" value="mysession.xml"/>

Example 5-118 shows how to use this property in a property map.

Example 5-118 Using sessions-xml in a Property Map

import org.eclipse.persistence.config.PersistenceUnitProperties;
propertiesMap.put(PersistenceUnitProperties.SESSIONS_XML, "mysession.xml");


See Also

For more information, see:

target-database

Use the eclipselink.target-database property to specify the database to use, controlling custom operations and SQL generation for the specified database.


Values

Table 5-94 describes this persistence property's values.

Table 5-94 Valid Values for target-database

Value Description

Defined in the TargetDatabase class or a fully qualified class name that extends DatabasePlatform

Specify your database:

  • Attunity

  • Auto (Default): EclipseLink attempts to access the database and the JDBC metadata to determine the target database.

  • Cloudscape

  • Database: Use a generic database, if your target database is not listed and your JDBC driver does not support the metadata required for Auto.

  • DB2

  • DB2Mainframe

  • DBase

  • Derby

  • HSQL

  • Informix

  • JavaDB

  • MaxDB

  • MySQL

  • MySQL4

  • Oracle

  • Oracle10

  • Oracle11

  • Oracle8

  • Oracle9

  • PointBase

  • PostgreSQL

  • SQLAnywhere

  • SQLServer

  • Sybase

  • Symfoware

  • TimesTen


Usage

If eclipselink.validation-only = true, you cannot use an Auto class name or short name.


Examples

Example 5-119 shows how to use this property in the persistence.xml file.

Example 5-119 Using target-database in persistence.xml

<property name="eclipselink.target-database" value="Oracle"/>

or

<property name="eclipselink.target-database"
value="org.eclipse.persistence.platform.database.HSQLPlatform"/>

Example 5-120 shows how to use this property in a property map.

Example 5-120 Using target-database in a Property Map

import org.eclipse.persistence.config.TargetDatabase;
import org.eclipse.persistence.config.PersistenceUnitProperties;
propertiesMap.put(PersistenceUnitProperties.TARGET_DATABASE, TargetDatabase.Oracle);


See Also

For more information, see:

target-server

Use the eclipselink.target-server property to configure the ServerPlatform that will be used to enable integration with a host container. If this property is not specified, the runtime will attempt to detect which ServerPlatform should be used. If detection fails, Default will be used.


Values

Table 5-95 describes this persistence property's values.

Table 5-95 Valid Values for target-server

Value Description

Defined in the TargetServer class

Specify your application server:

  • JBoss: JBoss Application Server

  • OC4J: OC4J persistence provider

  • SAPNetWeaver_7_1: SAP NetWeaver Application Server 7.1 (and higher)

  • SunAS9: Sun Application Server 9

  • WebLogic: Oracle WebLogic Server

  • WebLogic_10: Oracle WebLogic Server 10

  • WebLogic_9: Oracle WebLogic Server 9

  • WebSphere: IBM WebSphere

  • WebSphere_6_1: IBM WebSphere 6.1

  • WebSphere_7: IBM WebSphere 7

  • WebSphere_Liberty: IBM WebSphere Liberty

  • Default (TargetServer.None)


Usage

In addition to the supplied values, you can specify a custom server platform by supply the full class name for the platform.

Specifying a name of the class implementing ExternalTransactionController sets CustomServerPlatform with this controller.


Examples

Example 5-121 shows how to use this property in a persistence.xml file.

Example 5-121 Using target-server in persistence.xml

<property name="eclipselink.target-server" value="OC4J_10_1_3"/>

Example 5-122 shows how to use this property in a property map.

Example 5-122 Using target-server in a Property Map

import org.eclipse.persistence.config.TargetServer;
import org.eclipse.persistence.config.PersistenceUnitProperties;
propertiesMap.put(PersistenceUnitProperties.TARGET_SERVER, 
TargetServer.OC4J_10_1_3);


See Also

For more information, see:

temporal.mutable

Use the eclipselink.temporal.mutable property to configure the default for detecting changes to the temporal field (Date, Calendar).


Values

Table 5-96 shows this persistence property's values.

Table 5-96 Valid Values for temporal.mutable

Value Description

true

Changes to the object are detected. Disables weaving of attribute change tracking.

false

(Default) Changes to the object itself are not detected.


Usage

By default, it is assumed that temporal fields are replaced, and the temporal object is not changed directly.


Examples

Example 5-123 shows how to use this property in the persistence.xml file.

Example 5-123 Using temporal.mutable in persistence.xml

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

Example 5-124 shows how to use this property in a property map.

Example 5-124 Using temporal.mutable in a Property Map

import org.eclipse.persistence.config.PersistenceUnitProperties;
propertyMap.put(PersistenceUnitProperties.TEMPORAL_MUTABLE,
"true");

tenant-id

Use the eclipselink.tenant-id property to specify the default context property used to populate multitenant entities.


Values

Table 5-97 describes this persistence property's values.

Table 5-97 Valid Values for tenant-id

Value Description

value

Name of the default context property.


Usage

This is a default multitenant property that can be used on its own or with other properties defined by you. You are not obligated to use this property. You are free to specify your own.


Examples

Example 5-125 shows how to use this property in the persistence.xmlfile.

Example 5-125 Using tenant-id in persistence.xml

<property name="eclipselink.tenant-id" value="Oracle"/>

Example 5-126 shows how to use this property in a property map.

Example 5-126 Using tenant-id in a Property Map

import org.eclipse.persistence.config.PersistenceUnitProperties;
propertyMap.put(PersistenceUnitProperties.MULTI_TENANT_PROPERTY_DEFAULT,
"Oracle");

transaction.join-existing

Use the eclipselink.transaction.join-existing property to force the persistence context to read through the JTA-managed ("write") connect

ion in case there is an active transaction.


Values

Table 5-98 describes this persistence property's values.

Table 5-98 Valid Values for transaction.join-existing

Value Description

true

Forces the persistence context to read through the JTA-managed connection.

false

(Default) Does not force the persistence context to read through the JTA-managed connection.


Usage

The property set in persistence.xml or passed to createEntityManagerFactory affects all EntityManagers created by the factory. If the property set to true, objects read during transaction will not be placed into the shared cache unless they have been updated. Alternatively, to apply the property only to some EntityManagers, pass it to createEntityManager method.


Examples

Example 5-127 shows how to use this property in the persistence.xml file.

Example 5-127 Using transaction.join-existing in persistence.xml

<property name="eclipselink.transaction.join-existing" value="true"/>

Example 5-128 shows how to use this property in a property map.

Example 5-128 Using transaction.join-existing in a Property Map

import org.eclipse.persistence.config.PersistenceUnitProperties;
propertyMap.put(PersistenceUnitProperties.TRANSACTION_JOIN_EXISTING,
"true");


See Also

For more information, see:

  • "Automated Tuning" in Solutions Guide for EclispeLink

tuning

The eclipselink.tuning property selects the type of tuner to use to configure the persistence unit.


Values

Table 5-99 describes this persistence property's values.

Table 5-99 Valid Values for tuning

Value Description

standard

(Default) Uses the standard tuner and does not change any of the default configuration settings.

safe

Configures the persistence unit for debugging. This disables caching and several performance optimizations. The purpose is to provide a simplified development and debugging configuration.

custom tuner

Specifies the full class name of an implementation of the org.eclipse.persistence.tools.tuning.SessionTuner interface.


Usage

Use automated tuning to set multiple configuration properties as part of a single flag to perform dynamic tuning during different steps of application deployment.


Examples

Example 5-129 shows how to use this property in the persistence.xml file.

Example 5-129 Using tuning in persistence.xml

<property name="eclipselink.tuning" value="safe"/>

validate-existence

Use the eclipselink.validate-existence property to specify if EclipseLink should verify an object's existence on persist().


Values

Table 5-100 describes this persistence property's values.

Table 5-100 Valid Values for validate-existence

Value Description

true

EclipseLink verifies the object's existence.

false

(Default) EclipseLink assumes the object is new, if it is not in the persistence context.


Usage

EclipseLink will throw an error if a validated object is not in the persistence context.


Examples

Example 5-130 shows how to use this property in the persistence.xml file.

Example 5-130 Using validate-existence in persistence.xml

<property name="eclipselink.validate-existence" value="true"/>

Example 5-131 shows how to use this property in a proptery map.

Example 5-131 Using validate-existence in a Property Map

import org.eclipse.persistence.config.PersistenceUnitProperties;
propertyMap.put(PersistenceUnitProperties.VALIDATE-EXISTENCE,
"true");

validation-only

Use the eclipselink.validation-only property to validate deployments by initializing descriptors but not connecting to the data source.


Values

Table 5-101 describes this persistence property's values.

Table 5-101 Valid Values for validation-only

Value Description

true

EclipseLink will initialize the descriptors but not log in.

false

(Default) EclipseLink will initialize the descriptors and log in.


Usage

When setting eclipselink.validation-only to true, you must also configure eclipselink.target-database with a non-Auto class name or a short name.


Examples

Example 5-132 show how to use this property in the persistence.xml file.

Example 5-132 Using validation-only in persistence.xml

<property name="eclipselink.validation-only" value="true"/>

Example 5-133 shows how to use this property in a property map.

Example 5-133 Using validation-only in a Property Map

import org.eclipse.persistence.config.PersistenceUnitProperties;
propertyMap.put(PersistenceUnitProperties.VALIDATION_ONLY,
"true");


See Also

For more information, see:

weaving

Use the eclipselink.weaving property to specify if EclipseLink weaves the entity classes. EclipseLink JPA uses weaving to enhance JPA entities for such things as lazy loading, change tracking, fetch groups, and internal optimizations.


Values

Table 5-102 describes this persistence property's values.

Table 5-102 Valid values for weaving

Value Description

true

Weave the entity classes dynamically.

false

Do not weave the entity classes.

static

Weave the entity classes statically.


Examples

Example 5-134 shows how to use this property in the persistence.xml file.

Example 5-134 Using weaving in persistence.xml

<property name="eclipse.weaving" value="false"/>

Example 5-135 shows how to use this property in a property map.

Example 5-135 Using weaving in a Property Map

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


See Also

For more information, see:

weaving.changetracking

Use the eclipselink.weaving.changetracking persistence property to:

  • Enable AttributeLevelChangeTracking through weaving.

  • Permit only classes with all mappings to change.

  • Permit tracking to enable change tracking. Mutable basic attributes prevent change tracking.

This property is enabled only when weaving is enabled.


Values

Table 5-103 describes this persistence property's values.

Table 5-103 Valid Values for weaving.changetracking

Value Description

true

(Default) Enables this property.

false

Disables this property.


Examples

Example 5-136 shows how to use this property in the persistence.xml file.

Example 5-136 Using weaving.changetracking in persistence.xml

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

Example 5-137 shows how to use this property in a property map.

Example 5-137 Using weaving.changetracking in a Property Map

import org.eclipselink.persistence.config.PersistenceUnitProperties;
propertiesMap.put
(Persistence.Unit.Properties.WEAVING_CHANGETRACKING,
value="false");


See Also

For more information, see:

weaving.eager

Use the eclipselink.weaving.eager property to specify if EclipseLink uses indirection on eager relationships.


Values

Table 5-104 describes this persistence property's values.

Table 5-104 Valid Values for weaving.eager

Value Description

true

Enables indirection on eager relationships through weaving.

false

(Default) Disables indirection on eager relationships through weaving.


Usage

One-to-one and many-to-one mappings, even when configured with FetchType.EAGER, will effectively become "lazy."

You can use this extension only if weaving is configured to true or static. See "weaving" for more information.


Examples

Example 5-138 shows how to use this property in the persistence.xml file.

Example 5-138 Using weaving in persistence.xml

<property name="eclipselink.weaving.eager" value="true"/>

Example 5-139 shows how to use this extension in a property map

Example 5-139 Using weaving in a Property Map

import org.eclipse.persistence.config.PersistenceUnitProperties;
propertiesMap.put
(PersistenceUnitProperties.WEAVING_EAGER, "true");


See Also

For more information, see:

weaving.fetchgroups

Use the eclipselink.weaving.fetchgroups property to enable FetchGroups through weaving. When this is enabled, lazy direct mapping is supported, as well as descriptor and query-level FetchGroups.

FetchGroups allow partial objects to be read and written. Access to un-fetched attributes refreshes (fully-fetches) the object.

This property is only considered when weaving is enabled.


Values

Table 5-105 describes this persistence property's values.

Table 5-105 Valid Values for weaving.fetchgroups

Value Description

true

(Default) Enables FetchGroups through weaving.

false

Disables FetchGroups through weaving.


Examples

Example 5-140 shows how to use this property in the persistence.xml file.

Example 5-140 Using weaving.fetchgroups in persistence.xml

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

Example 5-141 shows how to use this property in a property map.

Example 5-141 Using weaving.fetchgroups in a Property Map

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


See Also

For more information, see:

weaving.internal

Use the eclipselink.weaving.internal property to specify if EclipseLink uses internal optimizations through weaving.


Values

Table 5-106 describes this persistence property's values.

Table 5-106 Valid Values for weaving.internal

Value Description

true

(Default) Enables internal optimizations through weaving.

false

Disables internal optimizations through weaving.


Usage

You can use this extension only if weaving is configured to true or static. See "weaving" for more information.


Examples

Example 5-142 shows how to use this property in the persistence.xml file.

Example 5-142 Using weaving in persistence.xml

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

Example 5-143 shows how to use this property in a property map.

Example 5-143 Using weaving in a Property Map

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


See Also

For more information, see:

weaving.lazy

Use the eclipselink.weaving.lazy property to specify if EclipseLink uses lazy one-to-one and many-to-one mappings.


Values

Table 5-107 describes this persistence property's values.

Table 5-107 Valid Values for weaving.lazy

Value Description

true

(Default) Enables lazy one-to-one and many-to-one mappings through weaving.

false

Disables lazy one-to-one and many-to-one mappings through weaving.


Usage

You can use this extension only if weaving is configured to true or static. See "weaving" for more information.


Examples

Example 5-144 shows how to use this property in the persistence.xml file.

Example 5-144 Using weaving.lazy in persistence.xml

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

Example 5-145 shows how to use this property in a property map.

Example 5-145 Using weaving.lazy in a Property Map

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


See Also

For more information, see:

  Previous Next
EclipseLink
  Go To Table Of Contents
 Search
 PDFComments
Comments