EclipseLink Solutions Guide for EclipseLink

By default, the WebLogic Server logging implementation is injected into the persistence context, which results in all EclipseLink logging messages being produced according to the WebLogic Server logging configuration.

As a result of this integration, EclipseLink logging levels are converted to WebLogic Server logging levels as shown in Table 3-1.

Table 3-1 Mapping of EclipseLink Logging Levels to WebLogic Server Logging Levels

WebLogic Server logging levels are mapped to EclipseLink levels as shown in Table 3-2.

Table 3-2 Mapping of WebLogic Server Logging Levels to EclipseLink Logging Levels

You can see the EclipseLink logging level defined for the persistence unit in the Administration Console, as described in Task 10: Configure and Monitor Persistence Settings in WebLogic Server. However, be aware that this logging level, set in the persistence.xml file, is overridden when the default WebLogic Server and EclipseLink logging integration is used. For information about overriding the integration, see Overriding the Default Logging Integration.

When the default integration is used, the Enterprise JavaBeans (EJB) logging options for persistence are mapped through and control EclipseLink’s logging output in the Administration Console.

You set EclipseLink logging levels in the persistence.xml file. However, when you accept the default logging integration with WebLogic Server, those settings are ignored, and the logging configuration set in WebLogic Server is used. The EclipseLink logging levels are used only when you use the native EclipseLink logging implementation.

You can override the default logging integration by setting the eclipselink.logging.logger property name to a different setting. For example, to enable the default EclipseLink logging, set the eclipselink.logging.logger property as follows:

You can also use a different logging implementation for EclipseLink messages, for example the java.util.logging package:

If you use the native EclipseLink logging implementation, you can still display EclipseLink logging messages in the WebLogic Server domain’s log files by configuring WebLogic Server to redirect Java Virtual Machine (JVM) output to the registered log destinations.

For more information and instructions for redirecting, see "Redirecting JVM Output" in Oracle Fusion Middleware Configuring Log Files and Filtering Log Messages for Oracle WebLogic Server. To set this option in the Administration Console, see "Redirect JVM output" in Oracle Fusion Middleware Oracle WebLogic Server Administration Console Online Help.

Other things to consider include the following:

You can configure data sources for JPA applications deployed to WebLogic Server in a variety of ways, including the following:

The most common data source configuration is a globally-scoped JNDI data source, using Java Transaction API (JTA) for transaction management, specified in the persistence.xml file. Configuration is straightforward, as shown in the following steps, and multiple applications can access the data source:

To configure an application-scoped data source that uses JTA for transaction management, perform the following steps:

To configure a non-JTA data source managed by the application, follow the procedures described in Configure an Application-Scoped JTA Data Source, but configure the JPA persistence unit to use a non-JTA data source by specifying a not-JTA data source, as shown in Example 3-5.

Example 3-5 non-JTA Data Source Definition in the persistence.xml File

Write the code in your application to handle the transactions as described, for example, in "Transactions in EJB Applications" in Oracle Fusion Middleware Programming JTA for Oracle WebLogic Server.

Certain settings in the data source configuration must match certain settings in the application’s ejbModule/META-INF/persistence.xml file. For the data source configuration in WebLogic Server, you can check the settings in the configuration files or in the Administration Console.

In the Administration Console, review the settings as follows:

Example 3-6 shows the values that must be shared in the domain’s config.xml file and the application’s persistence.xml file.

Example 3-6 Server Domain config.xml File

To integrate the JDBC driver, copy its JAR file into the domain and then restart the domain and instances to make the driver available.

You can create a JDBC connection pool from the GlassFish Server Administration Console or from the command line.

To use the GlassFish Server Administration Console:

In the GlassFish Server Administration Console, expand the Common Tasks node, then click the Create New JDBC Connection Pool button in the Common Tasks page. Specify the name of the pool, the resource type, the name of the database provider, the data source and driver class names, and other details. For more information, see "To Create a JDBC Connection Pool" in GlassFish Server Administration Console Online Help.

To use the command line:

You can use the GlassFish Server Administration Console to create the JDBC resource or you can use the command line.

To use the GlassFish Server Administration Console:

In the GlassFish Server Administration Console, expand the Resources node, then the JDBC node, then the JDBC Resources node to open the JDBC Resources page. Provide a unique JNDI resource name and associate the resource with a connection pool. For more information, see "To Create a JDBC Resource" in the GlassFish Server Administration Console Online Help.

To use the command line:

Use the create-jdbc-resource subcommand to create the JDBC resource, and name it so that the application can discover it using JNDI lookup, for example:

The persistence provider defines the implementation of JPA. It is defined in the provider element of the persistence.xml file. Persistence providers are vendor-specific. The persistence provider for EclipseLink is org.eclipse.persistence.jpa.PersistenceProvider.

You specify the database connection details in the persistence.xml file. GlassFish Server uses the bundled Java DB (Derby) database by default, named jdbc/__default. To use a nondefault database, such as the Oracle Database, either specify a value for the jta-data-source element, or set the transaction-type element to RESOURCE_LOCAL and specify a value for the non-jta-data-source element.

If you are using the default persistence provider, org.eclipse.persistence.jpa.PersistenceProvider, then the provider attempts to automatically detect the database type based on the connection metadata. This database type is used to issue SQL statements specific to the detected database type. You can specify the optional eclipselink.target-database property to guarantee that the database type is correct.

For more information about specifying database properties in a persistence.xml file for GlassFish Server, see "Specifying the Database for an Application" in the Oracle GlassFish Server Application Development Guide, at:

http://docs.oracle.com/cd/E26576_01/doc.312/e24930/jpa.htm#gbwmj

EclipseLink provides a logging utility even though logging is not part of the JPA specification. Hence, the information provided by the log is EclipseLink JPA-specific. With EclipseLink, you can enable logging to view the following information:

You can specify logging in the persistence.xml file. EclipseLink logging properties let you specify the level of logging and whether the log output goes to a file or standard output. Because the logging utility is based on java.util.logging, you can specify a logging level to use.

The logging utility provides nine levels of logging control over the amount and detail of the log output. Use eclipselink.logging.level to set the logging level, for example:

By default, the log output goes to System.out or to the console. To configure the output to be logged to a file, set the property eclipselink.logging.file, for example:

EclipseLink’s logging utility is pluggable, and several different logging integrations are supported, including java.util.logging. To enable java.util.logging, set the property eclipselink.logging.logger, for example:

While running inside GlassFish Server, EclipseLink is configured by GlassFish Server to use JavaLogger by default. The log is always redirected to the GlassFish Server server.log file. For more information, see "Setting Log Levels" in Oracle GlassFish Server Administration Guide, at:

http://docs.oracle.com/cd/E26576_01/doc.312/e24928/logging.htm#gklml

For more information about EclipseLink logging and the levels of logging available in the logging utility, see "Persistence Property Extensions Reference" in Jakarta Persistence API (JPA) Extensions Reference for EclipseLink.

You can make EclipseLink available globally for both container-managed and application-managed persistence units in either of the following ways:

Option 1: Create a Global Shared Library (Recommended)

Option 2: Add EclipseLink as a Server Library Extension

To add EclipseLink as a server library extension, copy eclipselink.jar and the other JAR file(s) listed in Option 1, above, to the `WAS_HOME``\lib\ext` directory.

You can also implement container-managed persistence by adding eclipselink.jar in the application EAR, without making any modifications to the server configuration. In this case, the persistence unit is managed by @PersistenceContext entity manager proxy injection on a stateless session bean. The following instructions show a example of this approach.

The following tables list the APIs removed as of TopLink 11g Release 1 (11.1.1.1.). Use the replacement API listed in the tables.

Table 7-1 changetracking (oracle.toplink.descriptors.)*

Table 7-2 databaseaccess (oracle.toplink.internal)*

Table 7-3 jdo (oracle.toplink.)*

Table 7-4 mappings (oracle.toplink.)*

Table 7-5 objectrelational (oracle.toplink.)*

Table 7-6 oraclespecific (oracle.toplink.)*

^Footnote 1 oracle.toplink.oraclespecific.Oracle9Specific was moved to an internal package and renamed to oracle.toplink.internal.platform.database.oracle.Oracle9Specific. The replacement public API for oracle.toplink.oraclespecific.Oracle9Specific is oracle.toplink.platform.database.oracle.Oracle9Specific.
^Footnote 2 oracle.toplink.oraclespecific.TopLinkXMLType was a miscellaneous class, which does not have a replacement API.

Table 7-7 publicinterface (oracle.toplink.)*

^Footnote 1 oracle.toplink.publicinterface.DatabaseSession was moved to an internal package and renamed to oracle.toplink.internal.sessions.DatabaseSessionImpl. The replacement public API for oracle.toplink.publicinterface.DatabaseSession is oracle.toplink.sessions.DatabaseSession.
^Footnote 2 oracle.toplink.publicinterface.Session was moved to an internal package and renamed to oracle.toplink.internal.sessions.AbstractSessionImpl. The replacement public API for oracle.toplink.publicinterface.Session is oracle.toplink.sessions.Session.
^Footnote 3 oracle.toplink.publicinterface.UnitOfWork was moved to an internal package and renamed to oracle.toplink.internal.sessionl.UnitOfWorkImpl. The replacement public API for oracle.toplink.publicinterface.UnitOfWork is oracle.toplink.sessions.UnitOfWork.

Table 7-8 sdk (oracle.toplink.)*

Table 7-9 entitymanager (oracle.toplink.sessions.)*

Table 7-10 sessionconfiguration (oracle.toplink.tools.)*

Table 7-11 xml (oracle.toplink.)*

Table 7-12 XMLCommandConverter (oracle.toplink.)*

Table 7-13 Remote Protocols (oracle.toplink.)*

Table 7-14 EJB Mapping for BEA WebLogic 6.1

The following tables list the APIs deprecated in the releases prior to TopLink 11g Release 1 (11.1.1) and therefore removed in that release, due to the substitution of EclipseLink libraries. Use the replacement API indicated.

Table 7-15 mappings (oracle.toplink.)*

Table 7-16 descriptors (oracle.toplink.)*

The following classes were removed in the release prior to TopLink 11g Release 1 (11.1.1):

Other API changes include the following:

You can continue to use sessions.xml files as is. For a more forward-compatible solution, run the renamer on your sessions.xml files.

Deployment XML files from TopLink 10.1.3 and above can be read by TopLink 11.1.1 and later. You can continue to use those files or for a more forward compatible solution, run the renamer on these files and replace the version string in the "XML Header" with the following:

"Eclipse Persistence Services"

To use EclipseLink as a persistence provider, you must run the renamer on your persistence.xml files. The renamer updates the persistence provider to be EclipseLink and also update any native TopLink specific properties to the EclipseLink equivalent.

The Object-Relational (ORM) XML configuration file (orm.xml) is not EclipseLink-dependant and does not need to be updated.

In Hibernate, the selectBeforeUpdate attribute specifies that Hibernate should never perform a SQL update unless it is certain that an object is actually modified. The dynamicInsert attribute specifies that the INSERT SQL statement should be generated at runtime and contain only the columns whose values are not null. The dynamicUpdate attribute specifies that the UPDATE SQL statement should be generated at runtime and can contain only those columns whose values have changed.

By default, EclipseLink will always insert all mapped columns and will update only the columns that have changed. If alternative operations are required, then the queries used for these operations can be customized by using Java code, SQL, or stored procedures.

In Hibernate, the optimisticLock attribute determines the optimistic locking strategy.

EclipseLink’s optimistic locking functionality supports all of the Hibernate locking types and more. Table 8-1 translates locking types from Hibernate’s @Entity(optimisticLock) attributes into EclipseLink locking policies. These policies can be configured either with the EclipseLink @OptimisticLocking annotation or in the EclipseLink orm.xml file. For more information, see @OptimisticLocking.

Table 8-1 Translating Hibernate’s OptimisticLock to EclipseLink’s OptimisticLocking

Additionally, EclipseLink allows you to compare a specific set of selected columns using the OptimisticLockingType.SELECTED_COLUMNS annotation. This allows you to select the critical columns that should be compared if the CHANGED or ALL strategies do not meet your needs.

In Hibernate, the @ForeignKey annotation allows you to define the name of the foreign key to be used during schema generation.

EclipseLink does generate reasonable names for foreign keys, but does not provide an annotation or eclipselink-orm.xml support for specifying the name to use. When migrating, the recommended solution is to have EclipseLink generate the schema (DDL) commands to a script file instead of directly on the database. The script can then be customized to use different names prior to being executed.

In Hibernate, the @Cache annotation configures the caching of entities and relationships. Because EclipseLink uses an entity cache instead of a data cache, the relationships are automatically cached. In these cases, the @Cache annotation should be removed during migration.When the @Cache annotation is used on an entity, its behavior is similar to the EclipseLink @Cache annotation. For more information about the @Cache annotation and equivalent eclipselink-orm.xml configuration values, see Jakarta Persistence API (JPA) Extensions Reference for EclipseLink.

Example 8-4 illustrates a persistence.xml file modified for an application that uses EclipseLink. Key differences include the value for the persistence provider. For EclipseLink, this value is org.eclipse.persistence.jpa.PersistenceProvider. The names of EclipseLink-specific properties are typically be prefixed by eclipselink, for example, eclipselink.target-database. EclipseLink-specific values appear in bold font.

Example 8-4 Persistence File Modified for EclipseLink

For production environments, you would usually have the schema set up on the database. The following properties defined in the persistence unit are more suitable for examples and demonstrations. These properties will instruct EclipseLink to automatically drop and create database tables. Any previously existing tables will be removed.

To use the Drop and Create Database Tables feature, add the following properties to the persistence.xml file.

For more information on this feature, see the drop-and-create-tables entry in "ddl-generation" in Jakarta Persistence API (JPA) Extensions Reference for EclipseLink.

The Create or Extend Database Tables feature allows you match the database schema to the object model by creating new database tables or by modifying existing tables. You can modify existing tables by specifying field name changes and by add and removing fields.

The Create or Extend Database Tables feature reduces the need to repopulate test data. You avoid the need to use the Drop and Create Database Tables feature when the schema changes, due to changes in the object model. The Create or Extend Database Tables feature can also be used with extensibility to add table columns.

To use the Create or Extend Database Tables feature, add the following properties to the persistence.xml file. When the context is loaded, EclipseLink will query the database for each table required in the persistence unit and use the results to determine if the table needs to be created or extended.

For more information on this feature, see the create-or-extend-tables entry in "ddl-generation" in Jakarta Persistence API (JPA) Extensions Reference for EclipseLink.

Disable the shared cache for highly volatile entities or for all entities as required. To disable the shared cache for all objects, use the <shared-cache-mode> element in the persistence.xml file. For example:

The default configuration is DISABLE_SELECTIVE and allows caching to be disabled per entity. To selectively enable or disable the shared cache, use the shared attribute of the @Cache annotation when defining an entity. For example:

Refreshing a cache reloads the cache from the database to ensure that an application is using current data. There are different ways to refresh a cache.

The @Cache annotation provides the alwaysRefresh and refreshOnlyIfNewer attributes which force all queries that go to the database to refresh the cache. The cache is only actually refreshed if the optimistic lock value in the database is newer than in the cache.

The jakarta.persistence.Cache interface includes methods that remove stale objects if the cache is out of date:

The preceding methods are passive and refresh objects only the next time the cache is accessed. To actively refresh an object, use the EntityManager.``refresh method. The method refreshes a single object at a time.

Another possibility is to use the setHint method to set a query hint that triggers the query to refresh the cache. For example:

Lastly, native API methods are also available. For details, see the ClassDescriptor documentation in Java API Reference for EclipseLink.

Cache expiration makes a cached object instance invalid after a specified amount of time. Any attempt to use the object causes the most up-to-date version of the object to be reloaded from the data source. Expiration can help ensure that an application is always using the most recent data. There are different ways to set expiration.

The @Cache annotation provides the expiry and expiryTimeOfDay attributes, which remove cache instances after a specific amount of time. The expiry attribute is entered in milliseconds. The default value if no value is specified is -1, which indicates that expiry is disabled. The expiryTimeOfDay attribute is an instance of the org.eclipse.persistence.annotations.TimeOfDay interface. The following example sets the object to expire after 5 minutes:

Optimistic locking prevents one user from writing over another user’s work. Locking is important when multiple servers or multiple applications access the same data and is relevant in both single-server and multiple-server environments. In a multiple-server environment, locking is still required if an application uses cache refreshing or cache coordination. There are different ways to set optimistic locking.

The standard JPA @Version annotation is used for single valued value and timestamp based locking. However, for advanced locking features use the @OptimisticLocking annotation. The @OptimisticLocking annotation specifies the type of optimistic locking to use when updating or deleting entities. Optimistic locking is supported on an @Entity or @MappedSuperclass annotation. The following policies are available and are set within the type attribute:

Cache coordination synchronizes changes among distributed sessions. Cache coordination is most useful in application server clusters where maintaining consistent data for all applications is challenging. Moreover, cache consistency becomes increasingly more difficult as the number of servers within an environment increases.

Cache coordination works by broadcasting notifications of transactional object changes among sessions (EntityManagerFactory or persistence unit) in the cluster. Cache coordination is most useful for applications that are primarily read-based and when changes are performed by the same application operating with multiple, distributed sessions.

Cache coordination significantly minimizes stale data, but does not completely eliminate the possibility that stale data might occur because of latency. In addition, cache coordination reduces the number of optimistic lock exceptions encountered in distributed architectures, and reduces the number of failed or repeated transactions in an application. However, cache coordination in no way eliminates the need for an effective locking policy. To ensure the most current data, use cache coordination with optimistic or pessimistic locking; optimistic locking is preferred.

Cache coordination is supported over the Remote Method Invocation (RMI) and Java Message Service (JMS) protocols and is configured either declaratively by using persistence properties in a persistence.xml file or by using the cache coordination API. System properties that match the persistence properties are available as well.

For additional details on cache coordination see:

Jakarta Persistence API (JPA) Extensions Reference for EclipseLink

Configure the entity by annotating the entity class with @VirtualAccessMethods (or using the XML <access-methods>), adding get and set methods for the property values, and adding a data structure to store the extended attributes and values, as described in the following sections:

Provide database tables with extra columns to store virtual attribute values. For example, the following Customer table includes two predefined columns, ID and NAME, and three columns for storing the attribute values, EXT_1, EXT_2, EXT_3:

CUSTOMER table

You can then specify which of the FLEX columns should be used to persist an extended attribute, as described in "Task 3: Provide Additional Mappings".

To provide additional mappings, add the mappings with the column and access-methods attributes to the eclipselink-orm.xml file, for example:

Configure persistence unit properties to indicate that the application should retrieve the flexible mappings from the eclipselink-orm.xml file. You can set persistence unit properties using the persistence.xml file or by setting properties on the EntityManagerFactory interface, as described in the following sections.

For more information about external mappings, see Chapter 13, "Using an External MetaData Source."

Configure the bean by annotating the bean class with the @XmlVirtualAccessMethods, adding get and set methods for the property values, and adding a data structure to store the extended attributes and values. Alternatively, you can use the <xml-virtual-access-methods> element in eclipselink-orm.xml.

To provide additional mappings, add the mappings to the eclipselink-oxm.xml file, for example:

Example 12-5 illustrates a base class, ExtensibleBase, which other extensible classes can extend. In the example, the use of the @XmlTransient annotation prevents ExtensibleBase from being mapped as an inheritance relationship. The real properties represent the parts of the model that will be common to all tenants. The per-tenant extensions will be represented as virtual properties.

Example 12-5 A Base Class for Extensible Classes

Example 12-6 illustrates the definition of a Customer class. The Customer class is extensible because it inherits from a domain class that has been annotated with @XmlVirtualAccessMethods.

Example 12-6 An Extensible Customer Class

Example 12-7 illustrates an Address class. It is not necessary for every class in your model to be extensible. In this example, the Address class does not have any virtual properties.

Example 12-7 A Nonextensible Address Class

Example 12-8 illustrates a PhoneNumber class. Like Customer, PhoneNumber will be an extensible class.

Example 12-8 An Extensible PhoneNumber Class

The examples in this section define two separate tenants. Even though both tenants share several real properties, the corresponding XML representation can be quite different due to virtual properties.

Tenant 1

The first tenant is an online sporting goods store that requires the following extensions to its model:

The metadata for the virtual properties is captured in the eclipselink-oxm.xml mapping file or in files using the eclipselink-orm.xml schema.. Virtual properties are mapped in the same way as real properties. Some additional information is required, including type (since this cannot be determined through reflection), and for collection properties, a container type. The virtual properties defined below for Customer are middleName, shippingAddress, and phoneNumbers. For PhoneNumber, the virtual property is the type property.

Example 12-9 illustrates the binding-tenant1.xml mapping file.

Example 12-9 Defining Virtual Properties for Tenant 1

The get and set methods are used on the domain model to interact with the real properties and the accessors defined on the @XmlVirtualAccessMethods annotation are used to interact with the virtual properties. The normal JAXB mechanisms are used for marshal and unmarshal operations. Example 12-10 illustrates the Customer class code for tenant 1 to obtain the data associated with virtual properties.

Example 12-10 Tenant 1 Code to Provide the Data Associated with Virtual Properties

Example 12-11 illustrates the XML output from the Customer class for tenant 1.

Example 12-11 XML Output from the Customer Class for Tenant 1

Tenant 2

The second tenant is a streaming media provider that offers on-demand movies and music to its subscribers. It requires a different set of extensions to the core model:

For this tenant, the mapping file is also used to customize the mapping of the real properties.

Example 12-12 illustrates the binding-tenant2.xml mapping file.

Example 12-12 Defining Virtual Properties for Tenant 2

Example 12-13 illustrates the tenant 2 Customer class code to obtain the data associated with virtual properties.

Example 12-13 Tenant 2 Code to Provide the Data Associated with Virtual Properties

Example 12-14 illustrates the XML output from the Customer class for tenant 2.

Example 12-14 XML Output from the Customer Class for Tenant 2

To implement and use single-table multi-tenancy, you need:

Single-table multi-tenancy can be enabled declaratively using the @Multitenant annotation, in an Object Relational Mapping (ORM) XML file using the <multitenant> element, or by using annotations and XML together.

To use the @TenantDiscriminatorColumn annotation, include it with @Multitenant annotation on an entity or mapped superclass, and optionally include the name and contextProperty attributes. If you do not specify these attributes, the defaults name = "TENANT-ID" and contextProperty = "eclipselink.tenant-id" are used.

For example:

To specify multiple tenant discriminator columns, include multiple @TenantDiscriminatorColumn annotations within the @TenantDiscriminatorColumns annotation, and include the table where the column is located if it is not located on the primary table. For example:

To use the <tenant-discriminator-column> element, include the element within a <multitenant> element and optionally include the name and context-property attributes. If you do not specify these attributes, the defaults name = "TENANT-ID" and contextProperty = "eclipselink.tenant-id" are used.

For example:

To specify multiple columns, include additional <tenant-discriminator-column> elements, and include the table where the column is located if it is not located on the primary table. For example:

Tenant discriminator columns can be mapped to a primary key or to another column. The following example maps the tenant discriminator column to the primary key on the table during DDL generation:

The following example uses the ORM XML file to map the tenant discriminator column to a primary key:

The following example maps the tenant discriminator column to another column named AGE:

The following example uses the ORM XML file to map the tenant discriminator column to another column named AGE:

In addition to configuring discriminator columns at the entity and mapped superclass levels, you can also configure them at the persistence-unit-defaults and entity-mappings levels to provide defaults. Defining the metadata at the these levels follows similar JPA metadata defaulting and overriding rules.

Specify default tenant discriminator column metadata at the persistence-unit-defaults level in the ORM XML file. When defined at this level, the defaults apply to all entities of the persistence unit that have specified a multi-tenant type of SINGLE_TABLE minus those that specify their own tenant discriminator metadata. For example:

You can also specify tenant discriminator column metadata at the entity-mappings level in the ORM XML file. A setting at this level overrides a persistence unit default and applies to all entities with a multi-tenant type of SINGLE_TABLE of the mapping file, minus those that specify their own tenant discriminator metadata. For example:

Runtime context properties are used in conjunction with the multi-tenancy configuration on an entity (or mapped superclass) to implement the multi-tenancy strategy. For example, the tenant ID assigned to a tenant discriminator column for an entity is used at runtime (via an entity manager) to restrict access to data, based on that tenant’s ownership of (or access to) the rows and tables of the database.

At runtime, multi-tenancy properties can be specified in a persistence unit definition or passed to a create entity manager factory call.

The order of precedence for tenant discriminator column properties is as follows:

For example, to set the configuration on a persistence unit in persistence.xml:

Alternatively, to set the properties programmatically:

Inheritance strategies are configured by specifying the inheritance type (@jakarta.persistence.Inheritance). Single-table multi-tenancy can be used in an inheritance hierarchy, as follows:

To implement and use table-per-tenant multi-tenancy, you need:

Table-per-tenant multi-tenancy can be enabled declaratively using the @Multitenant annotation; or in an Object Relational Mapping (ORM) XML file using the <multitenant> element, or using annotations and XML together.

The tenant table discriminator describes the type of table discriminator to use in a table-per-tenant multi-tenancy strategy. The tenant table discriminator is identified by a property. You can define your own identifier or use the default property: org.eclipse.persistence.config.PersistenceUnitProperties.MULTITENANT_PROPERTY_DEFAULT = "eclipselink.tenant-id"

The tenant table discriminator can be specified at the entity or mapped superclass level, and it must always be accompanied with a Multitenant(TABLE_PER_TENANT) specification. It is not sufficient to specify only a tenant table discriminator.

The tenant table discriminator is used together with an associated application context to indicate which table or tables an application tenant can access.

At runtime, specify the context property using a persistence unit definition passed to an entity manager factory or set on an individual entity manager. For example:

To specify a context property at runtime programmatically:

An entity manager property definition follows:

The tenant discriminator column is used at runtime through entity manager operations and querying. The tenant discriminator column and value are supported through the following entity manager operations:

The tenant discriminator column and value are supported through the following queries:

To implement and use VPD multi-tenancy, you need:

In this example, an Oracle Virtual Private Database is configured with a policy and a stored procedure. The policy is a call to the database that tells the database to use a stored function to limit the results of a query. In this example, the function is called ident_func, and it is run whenever a SELECT, UPDATE or DELETE is performed on the SCOTT.TASK table. The policy is created as follows:

The function defined below is used by VPD to limit the data based on the identifier that is passed in to the connection. The function uses the USER_ID column in the table to limit the rows. The rows are limited, based on what is set in the client_identifier variable in the userenv context.

As described above, VPD is configured to use the USER_ID column to limit access to rows. Therefore, you must tell EclipseLink to auto-populate the USER_ID column on inserts. The following code uses EclipseLink multi-tenancy and specifies that the client identifier is passed in to the entity managers using a property called tenant.id. Because the filtering is done by VPD on the database, you must turn off caching on this entity to avoid leakage across users.

When single-table and table-per-tenant multi-tenancy are enabled, a client identifier is auto appended to any generated SQL. However, when VPD is used to limit the access to data, the auto-appending of the identifier should be turned off.

Beginning with EclipseLink 2.4, disable criteria generation as follows:

In EclipseLink 2.3.1, you must run the following codefrom a SessionCustomizer:

Add the following properties to persistence.xml.

Include the following to set and clear the VPD identifier:

Include the following to provide one connection per entity manager:

Include the following to allow native queries to be runnable from EclipseLink. This is required for creating VPD artifacts:

For example:

Since all of the following examples use the same accessor type, FIELD, define it at the package level by using the JAXB annotation @XmlAccessorType. At this point, you would also import the necessary classes:

A "privately-owned" relationship occurs when the target object is only referenced by a single source object. This type of relationship can be either one-to-one and embedded or one-to-many.

This Task shows how to create bi-directional mappings for both of these types of relationships between the Employee entity and the Address and PhoneNumber entities.

A shared reference relationship occurs when target objects are referenced by multiple source objects. For example, a business might be segregated into multiple departments, such as IT, human resources, finance, and so on. Each of these departments has multiple employees of differing job descriptions, pay grades, locations, and so on. Managing departments and employees requires shared reference relationships.

Since a shared reference relationship cannot be safely represented as nesting in XML, we use key relationships. In order to leverage the ID fields on JPA entities, you need to use the EclipseLink JAXB @XmlID annotation on non-String fields and properties and @XmlIDREF on string fields and properties.

This section contains examples that show how to map a many-to-one shared reference relationship and a many-to-many shared reference relationship.