Understanding EclipseLink

Java-to-data source integration is a widely underestimated problem when creating enterprise Java applications. This complex problem involves more than simply reading from and writing to a data source. The data source elements include tables, rows, columns, and primary and foreign keys. The Java and Jakarta EE programming languages include entity classes (regular Java classes), business rules, complex relationships, and inheritance. In a nonrelational data source, you must match your Java entities with XML elements and schemas.

A successful solution requires bridging these different technologies and solving the object-persistence impedance mismatch—a challenging and resource-intensive problem. To solve this problem, you must resolve the following issues between Jakarta EE and the data source elements:

As an application developer, you need a product that lets you integrate Java applications with any data source, without compromising application design or data integrity. In addition, as a Java developer, you need the ability to store (that is, persist) and retrieve business domain objects using a relational database or a nonrelational data source as a repository.

EclipseLink addresses the disparity between Java objects and data sources. It contains a persistence framework that lets you build applications that combine the best aspects of object technology with a specific data source. You can do the following:

EclipseLink metadata is the bridge between the development of an application and its deployed runtime environment. You can capture the metadata using:

The metadata lets you pass configuration information into the runtime environment. The runtime environment uses the information in conjunction with the persistent classes, such as Java objects, JPA entities, and the code written with the EclipseLink API, to complete the application. See "Adding Metadata Using Annotations" for more information. See also Jakarta Persistence API (JPA) Extensions Reference for EclipseLink.

Mappings can be stored external to the application. This can be as simple as making the eclipselink-orm.xml or eclipselink-oxm.xml file with the additional mapping information available on a web server as a file. It can also be more complex involving a server process that stores the mapping information and allows the information to be updated dynamically. For more information, see "EclipseLink/Examples/JPA/MetadataSource" in the EclipseLink documentation.

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

An entity is a persistence domain object. Typically, an entity represents a table in a relational database, and each entity instance corresponds to a row in the table. The primary programming artifact of an entity is the entity class, although entities can use helper classes.

The persistent state of an entity is represented either through persistent fields or persistent properties. These fields or properties use object/relational mapping annotations to map the entities and entity relationships to the relational data in the underlying data store.

See Chapter 4, "Understanding Entities."

Descriptors describe how a Java class relates to a data source representation. They relate object classes to the data source at the data model level. For example, persistent class attributes may map to database columns.

EclipseLink uses descriptors to store the information that describes how an instance of a particular class can be represented in a data source. Descriptors are used internally by EclipseLink, and are defined through annotations, XML, or in IDEs such as JDeveloper or Eclipse, then read at run time.

See Chapter 5, "Understanding Descriptors."

Mappings describe how individual object attributes relate to a data source representation. Mappings can involve a complex transformation or a direct entry.

EclipseLink uses mappings to determine how to transform data between object and data source representations. Mappings are used internally by EclipseLink, and are defined through annotations, XML, or in IDEs such as Eclipse, then read from XML files at run time.

See Chapter 6, "Understanding Mappings."

A data source platform includes options specific to a particular data source including binding, use of native SQL, use of batch writing, and sequencing.

See Chapter 7, "Understanding Data Access."

The EclipseLink cache is an in-memory repository that stores recently read or written objects based on class and primary key values. The cache is used to improve performance by avoiding unnecessary trips to the database, manage locking and cache isolation level, and manage object identity.

See Chapter 8, "Understanding Caching."

You can to create, read, update, and delete persistent objects or data using queries in both Jakarta EE and non-Jakarta EE applications for both relational and nonrelational data sources. Queries can be made at the object level or data level.

A number of query languages are supported, such as Java Persistence Query Language (JPQL), SQL, and the Expression Framework. The Java Persistence Criteria API can also be used to define dynamic queries through the construction of object-based query definition objects, rather than use of the string-based approach of JPQL.

See Chapter 9, "Understanding Queries."

By using the EclipseLink Expressions framework, you can specify query search criteria based on your domain object model. Expressions offer a number of advantages over SQL. For example, expressions are easier to maintain, changes to descriptors or database tables do not affect the querying structures in the application, they enhance readability by standardizing the Query interface, and they simplify complex operations.

See Chapter 10, "Understanding EclipseLink Expressions."

NoSQL is a classification of database systems that do not support the SQL standard. These include document databases, key-value stores, and various other non-standard databases. Persistence of Java objects to NoSQL databases is supported through the Jakarta Persistence API (JPA). EclipseLink’s native API is also supported with NoSQL databases.

See Chapter 11, "Understanding Non-relational Data Sources."

A diverse set of features is provided to measure and optimize application performance. You can enable or disable most features in the descriptors or session, making any resulting performance gains global. Tools are provided for performance profiling and performance, fetch group, and query monitoring.

See "Enhancing Performance" in Solutions Guide for EclipseLink.

The EclipseLink Core provides the runtime component. Access to the runtime can be obtained directly through the EclipseLink API. The runtime environment is not a separate or external process—it is embedded within the application. Application calls invoke EclipseLink to provide persistence behavior. This function enables transactional and thread-safe access to shared database connections and cached objects.

The EclipseLink API provides the reference implementation for JPA 2.0 (JSR-338). The org.eclipse.persistence.* classes encapsulate the EclipseLink API and provide extensions beyond the specification. These extensions include EclipseLink-specific properties and annotations. For more information on the API, properties and extensions, see Jakarta Persistence API (JPA) Extensions Reference for EclipseLink.

The JAXB APIs are included in Java SE 6. In the eclipselink.jar file, the org.eclipse.persistence.jaxb.* classes encapsulate the EclipseLink support for JAXB.

JPA simplifies Java persistence. It provides an object-relational mapping approach that lets you declaratively define how to map Java objects to relational database tables in a standard, portable way. JPA works both inside a Jakarta EE application server and outside an EJB container in a Java Standard Edition (Java SE) application. The main features included in the 2.2 JPA update are:

JAXB is a Java API that allows a Java program to access an XML document by presenting that document to the program in a Java format. This process, called binding, represents information in an XML document as an object in computer memory. In this way, applications can access the data in the XML from the object rather than using the Domain Object Model (DOM) or the Streaming API for XML (SAX) to retrieve the data from a direct representation of the XML itself. Usually, an XML binding is used with JPA entities to create a data access service by leveraging a JAX-WS or JAX-RS implementation. Both of these Web Service standards use JAXB as the default binding layer. This service provides a means to access data exposed by JPA across computers, where the client computer might or might not be using Java.

JAXB uses an extended set of annotations to define the binding rules for Java-to-XML mapping. These annotations are subclasses of the jakarta.xml.bind.`*` packages in the EclipseLink API. For more information about these annotations, see Java API Reference for EclipseLink.

For more information about JAXB, see "Java Architecture for XML Binding (JAXB)" at:

http://www.eclipse.org/eclipselink/moxy.php

MOXy (also known as Object-XML) is the EclipseLink JAXB implementation. This component enables you to bind Java classes to XML schemas. MOXy implements JAXB which lets you provide mapping information through annotations. Support for storing the mappings in XML format is provided by MOXy. The many advanced mappings that are available enable you to handle complex XML structures without having to mirror the schema in your Java class model.

The objects produced by the EclipseLink JAXB compiler are Java POJO models. They are generated with the necessary annotations required by the JAXB specification. The JAXB runtime API can be used to marshal and unmarshal objects.

When using MOXy as the JAXB provider, no metadata is required to convert your existing object model to XML. You can supply metadata (using annotations or XML) only when you must fine-tune the XML representation of the model.

Using EclipseLink MOXy, you can manipulate XML in the following ways:

For more information on MOXy and these use cases, see Developing JAXB Applications EclipseLink MOXy.

EclipseLink provides maximum flexibility with the ability to control how your object model is mapped to an XML schema. There are many advantages to having control over your own object model:

One of the key advantages of EclipseLink is that the mapping information can be stored externally and does not require any changes to the Java classes or XML schema. This means that you can map your domain objects to more than one schema, or if your schema changes, you can update the mapping metadata instead of modifying your domain classes. This is also useful when mapping third-party classes, because you might not have access to the source to add annotations.

The Service Data Objects (SDO) component provides the reference implementation of Service Data Objects version 2.1.1. The reference implementation is described in JSR-235. The SDO implementation incorporates the reference implementation and provides additional features primarily used for converting Java objects to XML, and for building and using data object models that can be incorporated into service architectures.

SDO provides you with the following capabilities:

For more information, see "Getting Started with EclipseLink SDO" in the EclipseLink documentation:

http://www.eclipse.org/eclipselink/moxy.php

Database Web Services (DBWS) enables simple and efficient access to relational database artifacts by using a web service. It provides Jakarta EE-compliant client-neutral access to the database without having to write Java code. DBWS extends EclipseLink’s core capabilities while using existing ORM and OXM components.

DBWS has a runtime provider component that takes a service descriptor (along with related deployment artifacts) and realizes it as a JAX-WS 2.0 Web service. The runtime provider uses EclipseLink to bridge between the database and the XML SOAP Messages used by web service clients. For information on DBWS architecture, see Developing Persistence Architectures Using EclipseLink Database Web Services Developer’s Guide.

Oracle JDeveloper is a Jakarta EE development environment with end-to-end support to develop, debug, and deploy e-business applications and web services.

For JDeveloper information and downloads, see:

http://www.oracle.com/us/products/tools/019657.htm

JDeveloper includes a number of features to aid in the development of applications that use EclipseLink. These features include wizards to reverse engineer JPA entities from database tables and to generate EJB 3.0 Session Beans with EntityManager injection. It also includes methods for querying JPA entities and to test client generation.

JDeveloper tools enable you to quickly and easily configure and map your Java classes and JPA entities to different data sources, including relational databases and XML schemas without using code.

DBWSBuilder script (included in EclipseLink install) can be used to run the DBWSBuilder utility to generate the Web service. JDeveloper uses the API provided, but does not use the DBWSBuilder script directly.

For more information on Oracle JDeveloper’s EclipseLink support, see JDeveloper online help.

The Eclipse IDE provides a number of features and utilities to help you create, run, and maintain applications that use JPA. These capabilities are extended if you install OEPE.

For Eclipse IDE information and downloads, see:

http://www.oracle.com/technetwork/developer-tools/eclipse/overview/index.html

The Dali Java Persistence Tools Project provides extensible frameworks and tools for defining and editing object-relational mappings for JPA entities. JPA mapping support focuses on minimizing the complexity of mapping by providing entity generation wizards, design-time validation, and a robust UI for entity and persistence unit configuration.

For Dali information and downloads, see:

http://www.eclipse.org/webtools/dali

Other tools and utilities from the Oracle, open source, and third party vendor communities are available from the Eclipse Marketplace.

http://marketplace.eclipse.org/

NetBeans IDE bundles Oracle GlassFish Server, which includes EclipseLink. The IDE provides full support for JPA-based code development. This support includes entity class wizards for constructing entities and editor hints to ensure that entities conform to the JPA specification. NetBeans also provides a persistence unit editor for constructing a persistence.xml file.

For NetBeans information and downloads, see:

http://netbeans.org/index.html

The EclipseLink metadata architecture provides many important benefits, including the following:

Using EclipseLink JPA, you have the flexibility of expressing persistence metadata using standard JPA annotations, deployment XML, or both and you can optionally take advantage of EclipseLink JPA annotation and persistence.xml property extensions.

A project contains the mapping metadata that the EclipseLink runtime uses to map objects to a data source. The project is the primary object used by the EclipseLink runtime.

This section describes the principal contents of project metadata, including the following:

For Object-relational mapping, the EclipseLink runtime constructs an in-memory project based on any combination of JPA annotations, persistence.xml, and EclipseLink JPA annotations and persistence.xml property extensions.

For MOXy mapping, the EclipseLink runtime uses a combination of JAXB annotations and eclipselink-oxm bindings. See "Overriding and Merging" in Jakarta Persistence API (JPA) Extensions Reference for EclipseLink.

A EclipseLink session contains the information required to access the data source. The session is the primary object used by your application to access the features of the EclipseLink runtime.

Using EclipseLink JPA, the EclipseLink runtime constructs an in-memory session based on any combination of JPA and EclipseLink annotations, JPA persistence properties (in the persistence.xml file), and EclipseLink property extensions. See "Overriding and Merging" in Jakarta Persistence API (JPA) Extensions Reference for EclipseLink.

The entity architecture is composed of entities, persistence units, persistence contexts, entity manager factories, and entity managers. Figure 2-2 illustrates the relationships between these elements:

Figure 2-2 Relationships Between Entity Architecture Elements

Description of "Figure 2-2 Relationships Between Entity Architecture Elements"

An annotation is a simple, expressive means of decorating Java source code with metadata that is compiled into the corresponding Java class files for interpretation at run time by a JPA persistence provider to manage persistent behavior.

A metadata annotation represents a Java language feature that lets you attach structured and typed metadata to the source code. Annotations alone are sufficient for the metadata specification—you do not need to use XML. Standard JPA annotations are in the jakarta.persistence package.

For more information, see Chapter 10 "Metadata Annotations" in the JPA Specification http://jcp.org/en/jsr/detail?id=338

EclipseLink provides a set of proprietary annotations as an easy way to add metadata to the Java source code. The metadata is compiled into the corresponding Java class files for interpretation at run time by a JPA persistence provider to manage persistent behavior. You can apply annotations at the class, method, and field levels.

EclipseLink annotations expose some features that are currently not available through the use of JPA metadata:

The following sections describe some of the key configuration files in an Object Relational Mapping project.

An important part of the definition of the persistence unit is the location where the provider can find data to read and write. This is called the data source. The data source is typically a database. The database location is specified in the form of a JDBC data source in the JNDI namespace of the server.

Typically, applications that use EclipseLink are run in the context of a JTA transaction. Specify the name of the data source in the jta-data-source element in the persistence.xml file. If the application is not run in the context of a transaction, then it is considered to be resource-local. In this case, specify the name of the data source in the non-jta-data-source element.

You can also specify a non-relational database data source, such as an XML schema.

For more information, see Chapter 7, "Understanding Data Access."

Applications can be run in standalone, or Java SE, mode. In this mode, the application runs outside the server, with a non-JTA compliant data source, and in a non-Oracle stack. In this case, you must provide driver-specific information, such as the JDBC driver class, the URL that the client uses to connect to the database, and the user name and password to access the database. For more information and an example of running an application in standalone mode, see "Testing EclipseLink JPA Outside a Container" in Solutions Guide for EclipseLink.

By default, EclipseLink uses a shared object cache that caches a subset of all objects read and persisted for the persistence unit. The shared cache differs from the local EntityManager cache. The shared cache exists for the duration of the persistence unit (EntityManagerFactory or server) and is shared by all EntityManagers and users of the persistence unit. The local EntityManager cache is not shared and only exists for the duration of the EntityManager or transaction.

The benefit of the shared cache is that after an object is read, the database does not need to be accessed if the object is read again. Also, if the object is read by using a query, it does not need to be rebuilt, and its relationships do not need to be fetched again.

The limitation of the shared cache is that if the database is changed directly through JDBC, or by another application or server, the objects in the shared cache will be stale.

EclipseLink offers several mechanism to deal with stale data including:

The shared cache can also be disabled, or it can be selectively enabled and disabled by using the @Cache or @Cacheable annotations.EclipseLink also offers several different caching strategies, to configure how many objects are cached and how much memory is used.

If the application detects that the cache is out of date, it can clear, refresh, or invalidate it programmatically. Clearing the cache can cause object identity issues if any of the cached objects are in use, so invalidating is safer. If you know that none of the cached objects are in use, then you can clear the cache.

For more information, see Chapter 8, "Understanding Caching."

The object-relational component of EclipseLink supports a variety of queries.

For information on these queries, see Chapter 9, "Understanding Queries."

To use MOXy as your JAXB provider, you must identify the entry point to the JAXB runtime. This entry point is the EclipseLink JAXBContextFactory class.

To identify the entry point, create a text file called jaxb.properties and enter the path to the JAXBContextFactory class as the value of the jakarta.xml.bind.context.factory context parameter, for example:

The jaxb.properties file must appear in the same package as the domain classes.

In the sample MOXy architecture illustrated in Figure 2-3, the starting point is an XML schema. A binding compiler binds the source schema to a set of schema-derived program classes and interfaces. JAXB-annotated classes within the application are generated either by a schema compiler or the result of a developer adding JAXB annotations to existing Java classes. The application can either marshal data to an XML document or unmarshal the data to a tree of content objects. Each content object is an instance of either a schema derived or an existing program element mapped by the schema generator and corresponds to an instance in the XML.

Figure 2-3 A Sample MOXy Architecture

Description of "Figure 2-3 A Sample MOXy Architecture"

In addition to the input options described in JAXB Contexts and JAXB Context Factories, MOXy provides the concept of a MetadataSource object. This object lets you to store mapping information outside of your application and retrieve it when the application’s JAXBContext object is being created or refreshed. For information on implementing MetadataSource, see Developing JAXB Applications EclipseLink MOXy.

XML binding is how you represent information in an XML document as an object in computer memory. This allows applications to access the data in the XML from the object rather than using the Domain Object Model (DOM), the Simple API for XML (SAX) or the Streaming API for XML (StAX) to retrieve the data from a direct representation of the XML itself. When binding, JAXB applies a tree structure to the graph of JPA entities. Multiple tree representations of a graph are possible and will depend on the root object chosen and the direction the relationships are traversed.

EclipseLink enables you to use all of the standard JAXB annotations. In addition to the standard annotations, EclipseLink offers another way of expressing your metadata—the EclipseLink XML Bindings document. Not only can XML Bindings separate your mapping information from your actual Java class, it can also be used for more advanced metadata tasks such as:

For more information, see Developing JAXB Applications EclipseLink MOXy.

In addition to using conventional Java access methods to get and set your object’s values, EclipseLink MOXy also lets you access values using an XPath statement. There are special APIs on EclipseLink’s JAXBContext object that enable you to get and set values by XPath. For more information, see Developing JAXB Applications EclipseLink MOXy.

If you are developing your application in a Jakarta EE environment, ensure that the persistence unit name is unique within each module. For example, you can define only one persistence unit with the name EmployeeService in an emp_ejb.jar file.

For more information, see "name" in the JPA Specification.

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.

If you are developing your application in a Jakarta EE environment, use the default transaction type: JTA (for Java Transaction API) and specify the data source in a jta-data-source element.

If you are using a data source that does not conform to the JTA, then 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, see "transaction-type" and "provider" in the JPA Specification.

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:

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.

The last section in the persistence.xml file is the properties section. The properties element gives you the chance to supply EclipseLink persistence provider-specific settings for the persistence unit. See "properties" in the JPA Specification. see also "Persistence Property Extensions Reference" in Jakarta Persistence API (JPA) Extensions Reference for EclipseLink.

Apply the metadata to the persistence unit. This metadata is a union of all the mapping files and the annotations (if there is no xml-mapping-metadata-complete element). If you use one mapping orm.xml file for your metadata, and place this file in a META-INF directory on the classpath, then you do not need to explicitly list it. The EclipseLink persistence provider will automatically search for this file and use it. If you named your mapping files differently or placed them in a different location, then you must list them in the mapping-file elements in the persistence.xml file.

For more information, see "mapping-file, jar-file, class, exclude-unlisted-classes" in the JPA Specification.

Typically, you put all of the entities and other managed classes in a single JAR file, along with the persistence.xml file in the META-INF directory, and one or more mapping files (when you store metadata in XML).

At the time the EclipseLink persistence provider processes the persistence unit, it determines which set of entities, mapped superclasses, embedded objects, and converters each particular persistence unit will manage.

At deployment time, the EclipseLink persistence provider may obtain managed classes from any of the following sources. A managed class will be included if it is one of the following:

To be accessible to the EJB JAR, WAR, or EAR file, a class or a JAR file must be on the deployment classpath. You can achieve this in one of the following ways:

Jakarta EE allows for persistence support in a variety of packaging configurations. You can deploy your application to the following module types:

For more information, see "Persistence Unit Packaging" in the JPA Specification.

You can define any number of persistence units in single persistence.xml file. The following are the rules for using defined and packaged persistence units:

For more information, see "Persistence Unit Scope" in the JPA Specification.

You can expose multiple persistence units (each with unique sets of entity types) as a single persistence context by using a composite persistence unit. Individual persistence units that are part of this composite persistence unit are called composite member persistence units.

With a composite persistence unit, you can:

Figure 3-1 illustrates a simple composite persistence unit. EclipseLink processes the persistence.xml file and detects the composite persistence unit, which contains two composite member persistence units:

Figure 3-1 A Simple Composite Persistence Unit

Description of "Figure 3-1 A Simple Composite Persistence Unit"

For more information, see "Using Multiple Databases with a Composite Persistence Unit" in Solutions Guide for EclipseLink.

When implementing your persistence layer using EclipseLink, consider the following options:

When you create persistent Java objects, use direct access on private or protected attributes.

If you are using weaving, the ValueHolderInterface is not required. For more information, see About Weaving. See Indirection (Lazy Loading) for more information on indirection and transparent indirection.

The purpose of your application’s persistence layer is to use a session at run time to associate mapping metadata and a data source (see Chapter 7, "Understanding Data Access") to create, read, update, and delete persistent objects using the EclipseLink cache, queries and expressions, and transactions.

Typically, the EclipseLink persistence layer contains the following components:

Object modeling refers to the design of the Java classes that represent your application objects. You can use your favorite integrated development environment (IDE) or Unified Modeling Language (UML) modeling tool to define and create your application object model.

Any class that registers a descriptor with EclipseLink database sessions is called a persistent class. EclipseLink does not require that persistent classes provide public accessor methods for any private or protected attributes stored in the database. Refer to Persistent Class Requirements for more information.

Your data storage schema refers to the design that you implement to organize the persistent data in your application. This schema refers to the data itself—not the actual data source (such as a relational database or nonrelational legacy system).

During the design phase of the application development process, you should decide how to implement the classes in the data source. When integrating existing data source information, you must determine how the classes relate to the existing data. If no legacy information exists to integrate, decide how you will store each class, then create the necessary schema.

When making objects persistent, each object requires an identity to uniquely identify it for storage and retrieval. Object identity is typically implemented using a unique primary key. This key is used internally by EclipseLink to identify each object, and to create and manage references. Violating object identity can corrupt the object model.

In a Java application, object identity is preserved if each object in memory is represented by one, and only one, object instance. Multiple retrievals of the same object return references to the same object instance—not multiple copies of the same object.

EclipseLink supports multiple identity maps to maintain object identity (including composite primary keys). See About Cache Type and Size for additional information.

EclipseLink uses metadata to describe how objects and beans map to the data source. This approach isolates persistence information from the object model—you are free to design their ideal object model, and DBAs are free to design their ideal schema. For more information, see About Metadata.

At run time, EclipseLink uses the metadata to seamlessly and dynamically interact with the data source, as required by the application.

EclipseLink provides an extensive mapping hierarchy that supports the wide variety of data types and references that an object model might contain. For more information, see Chapter 6, "Understanding Mappings."

A foreign key can be one or more columns that reference a unique key, usually the primary key, in another table. Foreign keys can be any number of fields (similar to primary key), all of which are treated as a unit. A foreign key and the primary parent key it references must have the same number and type of fields.

Foreign keys represents relationships from a column or columns in one table to a column or columns in another table. For example, if every Employee has an attribute address that contains an instance of Address (which has its own descriptor and table), the one-to-one mapping for the address attribute would specify foreign key information to find an address for a particular Employee.

Object-oriented systems allow classes to be defined in terms of other classes. For example: motorcycles, sedans, and vans are all kinds of vehicles. Each of the vehicle types is a subclass of the Vehicle class. Similarly, the Vehicle class is the superclass of each specific vehicle type. Each subclass inherits attributes and methods from its superclass (in addition to having its own attributes and methods).

Inheritance provides several application benefits, including the following:

To have concurrent clients logged in at the same time, the server must spawn a dedicated thread of execution for each client. Jakarta EE application servers do this automatically. Dedicated threads enable each client to work without having to wait for the completion of other clients. EclipseLink ensures that these threads do not interfere with each other when they make changes to the identity map or perform database transactions. Your client can make transactional changes in an isolated and thread safe manner. EclipseLink manages clones for the objects you modify to isolate each client’s work from other concurrent clients and threads. This is essentially an object-level transaction mechanism that maintains all of the ACID (Atomicity, Consistency, Isolation, Durability) transaction principles as a database transaction.

EclipseLink supports configurable optimistic and pessimistic locking strategies to let you customize the type of locking that the EclipseLink concurrency manager uses. For more information, see Descriptors and Locking.

EclipseLink caching improves application performance by automatically storing data returned as objects from the database for future use. This caching provides several advantages:

EclipseLink supports several caching polices to provide extensive flexibility. You can fine-tune the cache for maximum performance, based on individual application performance. Refer to Chapter 8, "Understanding Caching" for more information.

The EclipseLink nonintrusive approach of achieving persistence through a metadata architecture means that there are almost no object model intrusions.

To persist Java objects, EclipseLink does not require any of the following:

See Building and Using the Persistence Layer for additional information on this nonintrusive approach. See also About Metadata.

An indirection object takes the place of an application object so the application object is not read from the database until it is needed. Using indirection, or lazy loading in JPA, allows EclipseLink to create stand-ins for related objects. This results in significant performance improvements, especially when the application requires the contents of only the retrieved object rather than all related objects.

Without indirection, each time the application retrieves a persistent object, it also retrieves all the objects referenced by that object. This may result in lower performance for some applications.

EclipseLink provides several indirection models, such as proxy indirection, transparent indirection, and value holder indirection.

See Using Indirection with Collections and Indirection (Lazy Loading) for more information.

Mutability is a property of a complex field that specifies whether the field value may be changed or not changed as opposed to replaced.

An immutable mapping is one in which the mapped object value cannot change unless the object ID of the object changes: that is, unless the object value is replaced by another object value altogether.

A mutable mapping is one in which the mapped object value can change without changing the object ID of the object.

By default, EclipseLink assumes the following:

Whether a value is immutable or mutable largely depends on how your application uses your persistent classes. For example, by default, EclipseLink assumes that a persistent field of type Date is immutable: this means that as long as the value of the field has the same object ID, EclipseLink assumes that the value has not changed. If your application uses the set methods of the Date class, you can change the state of the Date object value without changing its object ID. This prevents EclipseLink from detecting the change. To avoid this, you can configure a mapping as mutable: this tells EclipseLink to examine the state of the persistent value, not just its object ID.

You can configure the mutability of the following:

Mutability can affect change tracking performance. For example, if a transformation mapping maps a mutable value, EclipseLink must clone and compare the value. If the mapping maps a simple immutable value, you can improve performance by configuring the mapping as immutable.

Mutability also affects weaving. EclipseLink can only weave an attribute change tracking policy for immutable mappings.

For more information, see About Weaving. See also the description of the @Mutable annotation in Jakarta Persistence API (JPA) Extensions Reference for EclipseLink.

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

If the number of classes to weave is large or the time required to weave the classes is long, consider using static weaving.

Use static weaving to weave all application class files at build time so that you can deliver prewoven class files. Consider this option to weave all applicable class files at build time so that you can deliver prewoven class files. By doing so, you can improve application performance by eliminating the runtime weaving step required by dynamic weaving.

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

EclipseLink uses weaving to enable the following for POJO classes:

EclipseLink weaves all the POJO classes in the JAR you create when you package a POJO application for weaving.

EclipseLink weaves all the classes defined in the persistence.xml file, that is:

The default EclipseLink weaving behavior applies in any Jakarta EE JPA-compliant application server using the EclipseLink JPA persistence provider. To change this behavior, modify your persistence.xml file (for your JPA entities or POJO classes) to use EclipseLink JPA properties, EclipseLink JPA annotations, or both.

To disable weaving using EclipseLink persistence unit properties, configure your persistence.xml file with one or more of the following properties set to false:

A descriptor stores all the information describing how an instance of a particular object class can be represented in a data source. The Descriptor API can be used to define, or amend EclipseLink descriptors through Java code. The Descriptor API classes are mainly in the org.eclipse.persistence.descriptors package.

EclipseLink descriptors may contain the following information:

There is a descriptor type for each data source type that EclipseLink supports. In some cases, multiple descriptor types are valid for the same data source type. The type of descriptor you use determines the type of mappings that you can define.

Inheritance describes how a derived (child) class inherits the characteristics of its superclass (parent). You can use descriptors to describe the inheritance relationships between classes in relational and XML projects.

In the descriptor for a child class, you can override mappings that have been specified in the descriptor for a parent class, or map attributes that have not been mapped at all in the parent class descriptor.

Figure 5-1 illustrates the Vehicle object model–a typical Java inheritance hierarchy. The root class Vehicle contains two branch classes: FueledVehicle and NonFueledVehicle. Each branch class contains a leaf class: Car and Bicycle, respectively.

Figure 5-1 Example Inheritance Hierarchy

Description of "Figure 5-1 Example Inheritance Hierarchy "

EclipseLink recognizes the following three types of classes in an inheritance hierarchy:

In the descriptor for a child class, you can override mappings that have been specified in the descriptor for a parent class, or map attributes that have not been mapped at all in the parent class descriptor.

This section includes information on the following topics:

For relational projects, EclipseLink assumes that all of the classes in an inheritance hierarchy have the same primary key, as set in the root descriptor.

In a relational project, you can map your inheritance hierarchy to a single table or to multiple tables.

You can designate relational descriptors as aggregates. XML descriptors are always composites (see Descriptors and Aggregation).

When configuring inheritance for a relational aggregate descriptor, all the descriptors in the inheritance tree must be aggregates. The descriptors for aggregate and non-aggregate classes cannot exist in the same inheritance tree.

When configuring inheritance for an XML descriptor, because all XML descriptors are composites, descriptor type does not restrict inheritance.

Two objects—a source (parent or owning) object and a target (child or owned) object—are related by aggregation if there is a strict one-to-one relationship between them, and all the attributes of the target object can be retrieved from the same data source representation as the source object. This means that if the source object exists, then the target object must also exist, and if the source object is destroyed, then the target object is also destroyed.

In this case, the descriptors for the source and target objects must be designated to reflect this relationship.

The EJB 3.0 specification does not support nested aggregates).

You can customize a descriptor at run time by specifying a descriptor customizer—a Java class that implements the org.eclipse.persistence.config.DescriptorCustomizer interface and provides a default (zero-argument) constructor.

You use a descriptor customizer to customize a descriptor at run time through code API similar to how you use an amendment method to customize a descriptor. See Amendment Methods.

You can associate a static Java method that is called when a descriptor is loaded at run time. This method can amend the run-time descriptor instance through the descriptor Java code API. The method must be public static and take a single parameter of type org.persistence.descriptors.structures.ClassDescriptor. In the implementation of this method, you can configure advanced features of the descriptor using any of the public descriptor and mapping API.

You can only modify descriptors before the session has been connected; you should not modify descriptors after the session has been connected.

Amendment methods can be used with rational descriptors, object-relational data type descriptors, and XML descriptors.

In relational projects, EclipseLink raises various instances of DescriptorEvent during the persistence life cycle. Each descriptor owns an instance of DescriptorEventManager that is responsible for receiving these events and dispatching them to the descriptor event handlers registered with it.

Using a descriptor event handler, you can execute your own application specific logic whenever descriptor events occur, allowing you to take customized action at various points in the persistence life-cycle. For example, using a descriptor event handler, you can do the following:

By default, when you execute an object-level read query for a particular object class, EclipseLink returns all the persistent attributes mapped in the object’s descriptor. With this single query, all the object’s persistent attributes are defined, and calling their get methods returns the value directly from the object.

When you are interested in only some of the attributes of an object, it may be more efficient to return only a subset of the object’s attributes using a fetch group.

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

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

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

Fetch groups can be used only with basic mappings configured with FetchType.LAZY (partial object queries).

EclipseLink uses the AttributeGroup that can be used to configure the use of partial entities in fetch, load, copy, and merge operations.

The following sections describe the possible AttributeGroup types and operations.

The FetchGroup defines which attributes should be fetched (selected from the database) when the entity is retrieved as the result of a query execution. The inclusion of relationship attributes in a FetchGroup only determines if the attribute’s required columns should be fetched and populated. In the case of a lazy fetch type the inclusion of the attribute simply means that its proxy will be created to enable lazy loading when accessed. To force a relationship mapping to be populated when using a FetchGroup on a query the attribute must be included in the group and must either be FetchType.EAGER or it must be included in an associated LoadGroup on the query.

FetchGroup also has the notion of named and default FetchGroup which are managed by the FetchGroupManager. A default FetchGroup is defined during metadata processing if one or more basic mappings are configured to be lazy and the entity class implements FetchGroupTracker (typically introduced through weaving). The default FetchGroup is used on all queries for this entity type where no explicit FetchGroup or named FetchGroup is configured.

A named FetchGroup can be defined for an entity using @FetchGroup annotation or within the eclipselink-orm.xml file.

A FetchGroup when first created is assumed to be empty. The user must add the attributes to the FetchGroup. If a FetchGroup is required with all of the attributes then the FetchGroupManager.createFullFetchGroup() must be used.

A FetchGroup can also be configured to perform a load operation of relationship mappings and nested relationship mappings.

A LoadGroup is used to force a specified set of relationship attributes to be populated in a query result.

The CopyGroup replaces the deprecated ObjectCopyPolicy being used to define how a entity is copied. In addition to specifying the attributes defining what should be copied from the source entity graph into the target copy the CopyGroup also allows definition of:

When a partial entity is merged into a persistence context that has an AttributeGroup associated with it defining which attributes are available only those attributes are merged. The relationship mappings within the entity are still merged according to their cascade merge settings.

Each relational descriptor provides an instance of DescriptorQueryManager that you can use to configure the following:

An essential part of maintaining object identity is managing the assignment of unique values (that is, a specific sequence) to distinguish one object instance from another.

Sequencing options you configure at the project (or session) level determine the type of sequencing that EclipseLink uses. In a POJO project, you can use session-level sequence configuration to override project-level sequence configuration, on a session-by-session basis, if required.

After configuring the sequence type, for each descriptor’s reference class, you must associate one attribute, typically the attribute used as the primary key, with its own sequence.

With object-relational mapping, you can configure a descriptor with any of the following locking policies to control concurrent access to a domain object:

Oracle recommends using optimistic locking for most types of applications to ensure that users do not overwrite each other’s changes.

This section describes the various types of locking policies that EclipseLink supports, including the following:

With optimistic locking, all users have read access to the data. When a user attempts to make a change, the application checks to ensure the data has not changed since the user read the data.

Optimistic version locking policies enforce optimistic locking by using a version field (also known as a write-lock field) that you provide in the reference class that EclipseLink updates each time an object change is committed.

EclipseLink caches the value of this version field as it reads an object from the data source. When the client attempts to write the object, EclipseLink compares the cached version value with the current version value in the data source in the following way:

EclipseLink provides the following version-based optimistic locking policies:

For descriptions of these locking policies, see "Setting Optimistic Locking" in Solutions Guide for EclipseLink.

Whenever any update fails because optimistic locking has been violated, EclipseLink throws an OptimisticLockException. This should be handled by the application when performing any database modification. The application must notify the client of the locking contention, refresh the object, and have the client reapply its changes.

You can choose to store the version value in the object as a mapped attribute, or in the cache. In three-tier applications, you typically store the version value in the object to ensure it is passed to the client when updated (see Applying Locking in an Application).

If you store the version value in the cache, you do not need to map it. If you do map the version field, you must configure the mapping as read-only.

To ensure that the parent object’s version field is updated whenever a privately owned child object is modified, consider Optimistic Version Locking Policies and Cascading.

If you are using a stored procedure to update or delete an object, your database may not return the row-count required to detect an optimistic lock failure, so your stored procedure is responsible for checking the optimistic lock version and throwing an error if they do not match. Only version locking is directly supported with a StoredProcedureCall. Because timestamp and field locking require two versions of the same field to be passed to the call, an SQL call that uses an ## parameter to access the translation row could be used for other locking policies.

With pessimistic locking, the first user who accesses the data with the purpose of updating it locks the data until completing the update.

When using a pessimistic locking policy, you can configure the policy to either fail immediately or to wait until the read lock is acquired.

You can use a pessimistic locking policy only in a project with a container-managed persistence type and with descriptors that have EJB information.

You can also use pessimistic locking (but not a pessimistic locking policy) at the query level.

EclipseLink provides an optimization for pessimistic locking when this locking is used with entities with container-managed persistence: if you set your query to pessimistic locking and run the query in its own new transaction (which will end after the execution of the finder), then EclipseLink overrides the locking setting and does not append FOR UPDATE to the SQL. However, the use of this optimization may produce an undesirable result if the pessimistic lock query has been customized by the user with a SQL string that includes FOR UPDATE. In this case, if the conditions for the optimization are present, the query will be reset to nonpessimistic locking, but the SQL will remain the same resulting in the locking setting of the query conflicting with the query’s SQL string. To avoid this problem, you can take one of the following two approaches:

To correctly lock an object in an application, you must obtain the lock before the object is sent to the client for editing.

Use the orm.xml file to apply the metadata to the persistence unit. This metadata is a union of all the mapping files and the annotations (if there is no xml-mapping-metadata-complete element). If you use one mapping orm.xml file for your metadata and place this file in a META-INF directory on the classpath, then you do not need to explicitly list it. The persistence provider will automatically search for this file (orm.xml) and use it.

The schema for the JPA 2.0 orm.xml is orm_2_0.xsd. (http://java.sun.com/xml/ns/persistence/orm_2_0.xsd)

If you use a different name for your mapping files or place them in a different location, you must list them in the mapping-file element of the persistence.xml file.

EclipseLink supports an extended JPA orm.xml mapping configuration file called eclipselink-orm.xml. This mapping file can be used in place of JPA’s standard mapping file or can be used to override a JPA mapping file. In additional to allowing all of the standard JPA mapping capabilities it also includes advanced mapping types and options.

For more information on the eclipselink-orm.xml file, see "eclipselink-orm.xml Schema Reference" in Jakarta Persistence API (JPA) Extensions Reference for EclipseLink.

For more information, on overriding values, see:

You can use Java annotations to specify JAXB features in your projects. In addition to Java annotations, EclipseLink provides an XML mapping configuration file called eclipselink-oxm.xml. This mapping file contains the standard JAXB mappings and configuration options for advanced mapping types. You can use the eclipselink-oxm.xml file in place of or to override JAXB annotations in source code.

To define a mapping, you draw upon the following components:

For an example of a typical EclipseLink mapping, see Mapping Examples.

The type of data source you define in your project determines the type of mappings you can use and how you configure them. In a persistent project, you use mappings to persist to a data source. In a nonpersistent project, you use mappings simply to transform between the object format and some other data representation (such as XML).

A descriptor represents a particular domain object: it describes the object’s class. A descriptor also owns the mappings: one mapping for each of the class data members that you intend to persist or transform in memory. For more information about descriptors, see Chapter 5, "Understanding Descriptors".

Although EclipseLink supports more complex mappings, most EclipseLink classes map to a single database table or XML element that defines the type of information available in the class. Each object instance of a given class maps to a single row comprising the object’s attributes, plus an identifier (the primary key) that uniquely identifies the object.

Figure 6-1 illustrates the simplest database mapping case in which:

Figure 6-1 How Classes and Objects Map to a Database Table

Description of "Figure 6-1 How Classes and Objects Map to a Database Table"

EclipseLink provides you with the tools to build these mappings, from the simple mappings illustrated in Figure 6-1, to complex mappings.

For an additional example of a relational mapping, see Figure 6-2, "Serialized Object Converter (relational)".

If existing EclipseLink mappings do not meet your needs, you can create custom mappings using mapping extensions. These extensions include the following:

In some special circumstances, existing mapping types and their default Java to data source type handling may be insufficient. In these special cases, you can consider using a transformation mapping to perform specialized translations between how a value is represented in Java and in the data source.

Figure 6-7 illustrates a transformation mapping. The values from the B_DATE and B_TIME fields are used to create a java.util.Date to be stored in the birthDate attribute.

Figure 6-7 Transformation Mappings

Description of "Figure 6-7 Transformation Mappings"

A transformation mapping is made up of the following two components:

You can implement a transformer as either a separate class or as a method on your domain object.

Often, a transformation mapping is appropriate when values from multiple fields are used to create an object. This type of mapping requires that you provide an attribute transformation that is invoked when reading the object from the database. This must have at least one parameter that is an instance of Record. In your attribute transformation, you can use Record method get to retrieve the value in a specific column. Your attribute transformation can optionally specify a second parameter, an instance of Session. The Session performs queries on the database to get additional values needed in the transformation. The transformation should return the value to be stored in the attribute.

Transformation mappings also require a field transformation for each field, to be written to the database when the object is saved. The transformation returns the value to be stored in that field.

Within your implementation of the attribute and field transformation, you can take whatever actions are necessary to transform your application data to suit your data source, and vise versa.

You can perform transformation mappings between database columns and attribute values by using the @Transformation annotation. Use this annotation with the @WriteTransformer and @ReadTransformer annotations. The @WriteTransformer annotation is used to transform a single attribute value to a single database column value. For this annotation you have the option of providing an implementation of the FieldTransformer interface. For the @ReadTransformer annotation, you must provide an implementation of the org.eclipse.persistence.mappings.transformers.AttributeTransformer interface. For more information on these annotations, see the descriptions of the @Transformation, @ReadTransformer, and @WriteTransformer in Jakarta Persistence API (JPA) Extensions Reference for EclipseLink.

By default, when EclipseLink retrieves a persistent object, it retrieves all of the dependent objects to which it refers. When you configure indirection (also known as lazy reading, lazy loading, and just-in-time reading) for an attribute mapped with a relationship mapping, EclipseLink uses an indirection object as a place holder for the referenced object: EclipseLink defers reading the dependent object until you access that specific attribute. This can result in a significant performance improvement, especially if the application is interested only in the contents of the retrieved object, rather than the objects to which it is related.

Oracle strongly recommends using indirection for all relationship mappings. Not only does this lets you optimize data source access, but it also allows EclipseLink to optimize the persistence unit processing, cache access, and concurrency.

Figure 6-8 shows an indirection example. Without indirection, reading the Order object also reads the dependent collection of LineItem objects. With indirection, reading the Order object does not read the dependent collection of LineItem objects: the lineItems attribute refers to an indirection object. You can access other attributes (such as customerId), but EclipseLink reads the dependent LineItem objects only if and when you access the lineItems attribute.

Figure 6-8 EclipseLink Indirection

Description of "Figure 6-8 EclipseLink Indirection"

EclipseLink supports the following types of indirection:

When using indirection with an object that your application serializes, you must consider the effect of any untriggered indirection objects at deserialization time. See Indirection, Serialization, and Detachment.

When using indirection (lazy loading), it is likely that a graph of persistent objects will contain untriggered indirection objects. Because indirection objects are transient and do not survive serialization between one JVM and another, untriggered indirection objects will trigger an error if the relationship is accessed after deserialization.

The application must ensure that any indirect relationships that will be required after deserialization have been instantiated before serialization. This can be done through accessing the get method for any relationship using ValueHolder or weaved indirection, and by calling the size method to any relationship using transparent indirection. If the application desired the relationships to be always instantiated on serialization, you could overwrite the serialization writeObject method in the persistent class to first instantiate the desired relationships. Use caution for objects with many or deep relationships to avoid serializing large object graphs: ideally, only the relationships required by the client should be instantiated.

When serializing JPA entities, any lazy relationships that have not been instantiated prior to serialization will trigger errors if they are accessed. If weaving is used on the server, and the entities are serialized to a client, the same weaved classes must exist on the client, either through static weaving of the jar, or through launching the client JVM using the EclipseLink agent.

For more information, see Using Java Byte-code Weaving.

Persistent classes that use indirection must replace relationship attributes with value holder attributes. A value holder is an instance of a class that implements the ValueHolderInterface interface, such as ValueHolder. This object stores the information necessary to retrieve the object it is replacing from the database. If the application does not access the value holder, the replaced object is never read from the database.

To obtain the object that the value holder replaces, use the getValue and setValue methods of the ValueHolderInterface. A convenient way of using these methods is to hide the getValue and setValue methods of the ValueHolderInterface inside get and set methods, as shown in the following illustrations.

Figure 6-9 shows the Employee object being read from the database. The Address object is not read and will not be created unless it is accessed.

Figure 6-9 Address Object Not Read

Description of "Figure 6-9 Address Object Not Read"

The first time the address is accessed, as in Figure 6-10, the ValueHolder reads and returns the Address object.

Figure 6-10 Initial Request

Description of "Figure 6-10 Initial Request"

Subsequent requests for the address do not access the database, as shown in Figure 6-11.

Figure 6-11 Subsequent Requests

Description of "Figure 6-11 Subsequent Requests"

If you are using method access, the get and set methods specified in the mapping must access the instance of ValueHolderInterface, rather than the object referenced by the value holder. The application should not use these getter and setter, but use the getter and setter that hide the usage of value holders.

Transparent indirection lets you declare any relationship attribute of a persistent class that holds a collection of related objects as any of the following Java objects:

EclipseLink will use an indirection object that implements the appropriate interface and also performs just-in-time reading of the related objects. When using transparent indirection, you do not have to declare the attributes as ValueHolderInterface.

Newly created collection mappings use transparent indirection by default if their attribute is not a ValueHolderInterface.

You can configure EclipseLink to automatically weave transparent indirect container indirection for JPA entities and Plain Old Java Object (POJO) classes. For more information, see Using Java Byte-code Weaving and About Weaving.

The Java class Proxy lets you use dynamic proxy objects as place-holders for a defined interface. Certain EclipseLink mappings can be configured to use proxy indirection, which gives you the benefits of indirection without the need to include EclipseLink classes in your domain model. Proxy indirection is to one-to-one relationship mappings as indirect containers are to collection mappings.

To use proxy indirection, your domain model must satisfy all of the following criteria:

Before using proxy indirection, be aware of the restrictions it places on how you use the persistence unit (see Proxy Indirection Restrictions).

To configure proxy indirection, you can use JDeveloper or Java in an amendment method.

For JPA entities or POJO classes that you configure for weaving, EclipseLink weaves value holder indirection for one-to-one mappings. If you want EclipseLink to weave change tracking and your application includes collection mappings (one-to-many or many-to-many), then you must configure all collection mappings to use transparent indirect container indirection only (you may not configure your collection mappings to use eager loading nor value holder indirection).

For more information, see Using Java Byte-code Weaving.

To map entity classes to relational tables you must configure a mapping per persistent field. The following sections describe EclipeLink’s JPA mapping types:

Annotations are not always the most effective way to map JPA to XML. For example, you would not use JAXB if:

Under these and similar circumstances, you can use an XML data representation by exposing the eclipselink_oxm.xml file.

XML metadata works in two modes:

There are several ways to map simple Java values and collections of simple values directly to XML text nodes. You can map to attributes, text nodes, or schema types. You can also use simple type translators to map types of nodes that are not defined in your XML schema. These techniques are described in "Mapping Simple Values" in Developing JAXB Applications EclipseLink MOXy.

When you configure an EclipseLink database login with a user name and password, EclipseLink provides these credentials to the JDBC driver that you configure your application to use.

By default, EclipseLink reads passwords from the persistence.xml file.

EclipseLink supports proxy authentication with Oracle Database in Java SE applications and Jakarta EE applications with the Oracle JDBC driver and external connection pools only.

Oracle Database proxy authentication delivers the following security benefits:

For more information about authentication in Oracle Database, see "Preserving User Identity in Multitiered Environments" in the Oracle Database Security Guide.

Configure your EclipseLink database login to use proxy authentication to do the following:

Regardless of what type of authentication you choose, EclipseLink logs the name of the user associated with all database operations. Example 7-1 shows the CONFIG level EclipseLink logs when a ServerSession connects through the main connection for the sample user "scott", and a ClientSession uses proxy connection "jeff"

Example 7-1 Logs with Oracle Database Proxy Authentication

Your database server likely provides additional user auditing options. Consult your database server documentation for details.

Alternatively, you may consider using the EclipseLink persistence unit in conjunction with your database schema for auditing purposes.

For non-Jakarta EE applications, you typically use internal connection pools. By default, EclipseLink sessions use internal connection pools.

Using internal connection pools, you can configure the default (write) and read connection pools. You can also create additional connection pools for object identity, or any other purpose.

Internal connection pools allow you to optimize the creation of read connections for applications that read data only to display it and only infrequently modify data. This also allow you to use Workbench to configure the default (write) and read connection pools and to create additional connection pools for object identity or any other purpose.

For Jakarta EE applications, you typically use external connection pools. An external connection pool is a collection of reusable connections to a single data source provided by a JDBC driver or Jakarta EE container.

If you are using an external transaction controller (JTA), you must use external connection pools to integrate with the JTA.

Using external connection pools, you can use Java to configure the default (write) and read connection pools and create additional connection pools for object identity, or any other purpose.

External connection pools enable your EclipseLink application to do the following:

A server session provides a read connection pool and a write connection pool. These could be different pools, or if you use external connection pooling, the same connection pool.

All read queries use connections from the read connection pool and all queries that write changes to the data source use connections from the write connection pool. You can configure attributes of the default (write) and read connection pools.

Whenever a new connection is established, EclipseLink uses the connection configuration you specify in your session’s DatasourceLogin. Alternatively, when you use an external transaction controller, you can define a separate connection configuration for a read connection pool to avoid the additional overhead, if appropriate.

Use the connection-pool.read property to configure a read connection pool for non-transaction read queries. By default, EclipseLink does not use a separate read connection pool; the default pool is used for read queries. For more information, see connection-pool.read in Jakarta Persistence API (JPA) Extensions Reference for EclipseLink.

An essential part of maintaining object identity is sequencing–managing the assignment of unique values to distinguish one instance from another. For more information, see About Cache Type and Size.

Sequencing involves reading and writing a special sequence resource maintained by your data source.

By default, EclipseLink includes sequence operations in a separate transaction. This avoids complications during the write transaction, which may lead to deadlocks over the sequence resource. However, when using an external transaction controller (such as a JTA data source or connection pool), EclipseLink cannot use a different transaction for sequencing. Use a sequence connection pool to configure a non-JTA transaction pool for sequencing. This is required only for table sequencing–not native sequencing.

In each server session, you can create one connection pool, called a sequence connection pool, that EclipseLink uses exclusively for sequencing. With a sequence connection pool, EclipseLink satisfies a request for a new object identifier outside of the transaction from which the request originates. This allows EclipseLink to immediately commit an update to the sequence resource, which avoids deadlocks.

You should use a sequence connection pool, if the following applies:

You should not use a sequence connection pool, if the following applies:

You can configure a sequence connection pool with the eclipselink.connection-pool.sequence persistence unit property. This property allows the connection pool to allocate generated IDs, and is required only for TABLE sequencing. By default, EclipseLink does not use a separate sequence connection pool; the default pool is used for sequencing. For more information, see connection-pool.sequence in Jakarta Persistence API (JPA) Extensions Reference for EclipseLink.

When you use internal EclipseLink connection pools in a session, you can create one or more connection pools that you can use for any application purpose. These are called named connection pools, as you can give them any name you want and use them for any purpose.

Typically, use these named connection pools to provide pools of different security levels. For example, the "default" connection pool may only allow access to specific tables but the "admin" connection pool may allow access to all tables.

With single-table multi-tenancy, any table (Table or SecondaryTable) to which an entity or mapped superclass maps can include rows for multiple tenants. Access to tenant-specific rows is restricted to the specified tenant.

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

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

Table-per-tenant multi-tenancy allows multiple tenants of an application to isolate their data in one or more tenant-specific tables. Multiple tenants' tables can be in a shared schema, identified using a prefix or suffix naming pattern; or they can be in separate, tenant-specific schemas. Table-per-tenant entities can be mixed with other multi-tenant type entities within the same persistence unit.

The table-per-tenant multi-tenant type is used in conjunction with:

A single application instance with a shared EntityManagerFactory for a persistence unit can be responsible for handling requests from multiple tenants.

Alternatively, separate EntityManagerFactory instances can be used for each tenant. (This is required when using extensions per tenant.) In this case, tenant-specific schema and table names are defined in an eclipselink-orm.xml configuration file. A MetadataSource must be registered with a persistence unit. The MetadataSource is used to support additional persistence unit metadata provided from outside the application. See also metadata-source in Jakarta Persistence API (JPA) Extensions Reference for EclipseLink.

The table-per-tenant multi-tenant type enables individual tenant table(s) to be used at the entity level. A tenant context property must be provided on each entity manager after a transaction has started.

For information on constructing table-per-tenant multi-tenancy, see "Using Table-Per-Tenant Multi-Tenancy" in Solutions Guide for EclipseLink.

A Virtual Private Database (VPD) uses security controls to restrict access to database objects based on various parameters.

For example, the Oracle Virtual Private Database supports security policies that control database access at the row and column level. Oracle VPD adds a dynamic WHERE clause to SQL statements issued against the table, view, or synonym to which the security policy was applied.

Oracle Virtual Private Database enforces security directly on the database tables, views, or synonyms. Because security policies are attached directly to these database objects, and the policies are automatically applied whenever a user accesses data, there is no way to bypass security.

When a user directly or indirectly accesses a table, view, or synonym that is protected with an Oracle Virtual Private Database policy, Oracle Database dynamically modifies the SQL statement of the user. This modification creates a WHERE condition (called a predicate) returned by a function implementing the security policy. Oracle Virtual Private Database modifies the statement dynamically, transparently to the user, using any condition that can be expressed in or returned by a function. Oracle Virtual Private Database policies can be applied to SELECT, INSERT, UPDATE, INDEX, and DELETE statements.

When using EclipseLink VPD Multitenancy, the database handles the tenant filtering on all SELECT, INSERT, UPDATE, INDEX and DELETE queries.

To use EclipseLink VPD multi-tenancy, you must first configure VPD in the database and then specify multi-tenancy on the entity or mapped superclass using @Multitenant and @TenantDiscriminatorColumn annotations.

For more information on constructing VPD Multi-Tenancy, see "Using VPD Multi-Tenancy" in Solutions Guide for EclipseLink.

The persistence unit cache is a shared cache (L2) that services clients attached to a given persistence unit. When you read objects from or write objects to the data source using an EntityManager object, EclipseLink saves a copy of the objects in the persistence unit’s cache and makes them accessible to all other processes accessing the same persistence unit.

EclipseLink adds objects to the persistence unit cache from the following:

EclipseLink defines three cache isolation levels: Isolated, Shared, and Protected. For more information on these levels, see Shared, Isolated, Protected, Weak, and Read-only Caches.

There is a separate persistence unit cache for each unique persistence unit name. Although the cache is conceptually stored with the EntityManagerFactory, two factories with the same persistence unit name will share the same cache (and effectively be the same persistence unit instance). If the same persistence unit is deployed in two separate applications in Jakarta EE, their full persistence unit name will normally still be unique, and they will use separate caches. Certain persistence unit properties, such as data-source, database URL, user, and tenant id can affect the unique name of the persistence unit, and result in separate persistence unit instances and separate caches. The eclipselink.session.name persistence unit property can be used to force two persistence units to resolve to the same instance and share a cache.

The persistence context cache is an isolated cache (L1) that services operations within an EntityManager. It maintains and isolates objects from the persistence unit cache, and writes changed or new objects to the persistence unit cache after the persistence context commits changes to the data source.

The life-cycle for the persistence context cache differs between application managed, and container managed persistence contexts. The persistence context (unit of work) cache services operations within the persistence unit. It maintains and isolates objects from the persistence context (session) cache, and writes changed or new objects to the persistence context cache after the persistence unit commits changes to the data source.

EclipseLink defines three cache isolation levels. The cache isolation level defines how caching for an entity is performed by the persistence unit and the persistence context. The cache isolation levels can be set with the isolation attribute on the @Cache annotation. the possible values of the isolation attribute are:

This option provides full caching and guaranteed identity: objects are never flushed from memory unless they are deleted.

It caches all objects and does not remove them. Cache size doubles whenever the maximum size is reached. This method may be memory-intensive when many objects are read. Do not use this option on batch operations.

Oracle recommends using this identity map when the data set size is small and memory is in large supply.

This option only caches objects that have not been garbage collected. Any object still referenced by the application will still be cached.

The weak cache type uses less memory than full identity map but also does not provide a durable caching strategy across client/server transactions. Objects are available for garbage collection when the application no longer references them on the server side (that is, from within the server JVM).

This option is similar to the weak cache type, except that the cache uses soft references instead of weak references. Any object still referenced by the application will still be cached, and objects will only be removed from the cache when memory is low.

The soft identity map allows for optimal caching of the objects, while still allowing the JVM to garbage collect the objects if memory is low.

These options are similar to the weak cache except that they maintain a most frequently used sub-cache. The sub-cache uses soft or hard references to ensure that these objects are not garbage collected, or only garbage collected only if the JVM is low on memory.

The soft cache and hard cache provide more efficient memory use. They release objects as they are garbage-collected, except for a fixed number of most recently used objects. Note that weakly cached objects might be flushed if the transaction spans multiple client/server invocations. The size of the sub-cache is proportional to the size of the cache as specified by the @Cache size attribute. You should set the cache size to the number of objects you wish to hold in your transaction.

Oracle recommends using this cache in most circumstances as a means to control memory used by the cache.

NONE and CACHE options do not preserve object identity and should only be used in very specific circumstances. NONE does not cache any objects. CACHE only caches a fixed number of objects in an LRU fashion. These cache types should only be used if there are no relationships to the objects.Oracle does not recommend using these options. To disable caching, set the cache isolation to ISOLATED instead.

Use the following guidelines when configuring your cache type:

See About the Internals of Weak, Soft, and Hard Cache Types.

JPA defines standard query hints for configuring how a query interacts with the shared persistence unit cache (L2). EclipseLink also provides some additional query hints for configuring the cache usage. For information on JPA and EclipseLink query hints, see About Query Hints.

Entities can be accessed through JPA using either find() method or queries. The find() method will first check the persistence context cache (L1) for the Id, if the object is not found it will check the shared persistence unit cache (L2), if the object is still not found it will access the database. By default all queries will access the database, unless querying by Id or by cache indexed fields. Once the query retrieves the rows from the database, it will resolve each row with the cache. If the object is already in the cache, then the row will be discarded, and the object will be used. If the object is not in the shared cache, then it will be built from the row and put into the shared cache. A copy will also be put in the persistence context cache and returned as the query result.

This is the general process, but it differs if the transaction is dirty. If the transaction is dirty then the shared persistence unit cache will be ignored and objects will be built directly into the persistence context cache.

A transaction is considered dirty in the following circumstances:

Entities can also be configured to be isolated, or noncacheable, in which case they will never be placed in the shared cache (see "Shared, Isolated, Protected, Weak, and Read-only Caches").

Make sure you configure a locking policy so that you can prevent or at least identify when values have already changed on an object you are modifying. Typically, this is done using optimistic locking. EclipseLink offers several locking policies such as numeric version field, time-stamp version field, and some or all fields. Optimistic and pessimistic locking are described in the following sections.

If other applications can modify the data used by a particular class, use a weaker style of cache for the class. For example, the @Cache type attribute values WEAK and SOFT_WEAK minimizes the length of time the cache maintains an object whose reference has been removed. For more information about cache types, see About Cache Type and Size.

Any query can include a flag that forces EclipseLink to go to the data source for the most recent version of selected objects and update the cache with this information. For more information, see About Explicit Query Refreshes. See also "Refreshing the Cache" in Solutions Guide for EclipseLink.

You can configure any entity with an expiry that lets you specify either the number of milliseconds after which an entity instance should expire from the cache, or a time of day that all instances of the entity class should expire from the cache. Expiry is set on the @Cache annotation or <cache> XML element, and can be configured either with the expiry or with the expiryTimOfDay attribute. For more information, see "Setting Entity Caching Expiration" in Solutions Guide for EclipseLink.

If your application is primarily read-based and the changes are all being performed by the same Java application operating with multiple, distributed sessions, you may consider using the EclipseLink cache coordination feature. Although this will not prevent stale data, it should greatly minimize it. For more information, see About Cache Coordination and Clustering and Cache Coordination.

The Oracle database released a Continuous Query Notification (CQN) feature in the 10.2 release. CQN allows for database events to be raised when the rows in a table are modified. The JDBC API for CQN was not complete until 11.2, so 11.2 is required for EclipseLink’s integration.

EclipseLink CQN support is enabled by the OracleChangeNotificationListener listener which integrates with Oracle JDBC to received database change events. Use the eclipselink.cache.database-event-listener property to configure the full class name of the listener.

By default all tables in the persistence unit are registered for change notification, but this can be configured using the databaseChangeNotificationType attribute of the @Cache annotation to selectively disable change notification for certain classes.

Oracle CQN uses the ROWID to inform of row level changes. This requires EclipseLink to include the ROWID in all queries for a CQN enabled class. EclipseLink must also select the object’s ROWID after an insert operation. EclipseLink must maintain a cache index on the ROWID, in addition to the object’s Id. EclipseLink also selects the database transaction Id once each transaction to avoid invalidating the cache on the server that is processing the transaction.

EclipseLink’s CQN integration has the following limitations:

Cache coordination can enhance performance and reduce the likelihood of stale data for applications that have the following characteristics:

To maximize performance, avoid cache coordination for applications that do not have these characteristics.

For other options to reduce the likelihood of stale data, see About Handling Stale Data.

For a JMS coordinated caches, when a particular session’s coordinated cache starts, it uses its JNDI naming service information to locate and create a connection to the JMS server. The coordinated cache is ready when all participating sessions are connected to the same topic on the same JMS server. At this point, sessions can start sending and receiving object change messages. You can then configure all sessions that are participating in the same coordinated cache with the same JMS and JNDI naming service information.

For an RMI coordinated cache, when a particular session’s coordinated cache starts, the session binds its connection in its naming service (either an RMI registry or JNDI), creates an announcement message (that includes its own naming service information), and broadcasts the announcement to its multicast group. When a session that belongs to the same multicast group receives this announcement, it uses the naming service information in the announcement message to establish bidirectional connections with the newly announced session’s coordinated cache. The coordinated cache is ready when all participating sessions are interconnected in this way, at which point sessions can start sending and receiving object change messages. You can then configure each session with naming information that identifies the host on which the session is deployed.

For more information on configuring JMS and RMI cache coordination, see "Configuring JMS Cache Coordination Using Persistence Properties" and "Configuring RMI Cache Coordination Using Persistence Properties" in Solutions Guide for EclipseLink.

You can define your own custom solutions for coordinated caches by using the classes in the EclipseLink org.eclipse.persistence.sessions.coordination package.

The Call object encapsulates an operation or action on a data source. The EclipseLink API provides a variety of Call types such as structured query language (SQL), Java Persistence Query Language (JPQL), and Extensible Markup Language (XML).

You can execute a Call directly or in the context of the EclipseLink DatabaseQuery object.

A DatabaseQuery object is an abstraction that associates additional customization and optimization options with the action encapsulated by a Call. By separating these options from the Call, EclipseLink can provide sophisticated query capabilities across all Call types.

Queries can be defined for objects or data, as follows:

While data-level queries return raw data and object-level queries return objects in your domain model, summary queries return data about objects. EclipseLink provides partial object queries to return a set of objects with only specific attributes populated, and report queries to return summarized (or rolled-up) data for specific attributes of a set of objects.

In addition to storing named queries applicable to a particular class, you can also use the DescriptorQueryManager to override the default action that EclipseLink defines for common data source operations.

A query key is a schema-independent alias for a database field name. Using a query key, you can refer to a field using a schema-independent alias. In relational projects only, EclipseLink automatically creates query keys for all mapped attributes. The name of the query key is the name of the class attribute specified in your object model.

You can configure query keys in a class descriptor or interface descriptor. You can use query keys in expressions and to query variable one-to-one mappings.

By default, EclipseLink creates query keys for all mapped attributes, but in some scenarios you may find it beneficial to add your own.

EclipseLink supports all of the statements and clauses described in "Query Language" in the JPA Specification, including SELECT queries, update and delete statements, WHERE clauses, literal values, and database functions. For more information, see the JPA Specification.

http://jcp.org/en/jsr/detail?id=338

EclipseLink provides many extensions to the standard JPA JPQL. These extensions provide access to additional database features many of which are part of the SQL standard, provide access to native database features and functions, and provide access to EclipseLink specific features.

EclipseLink’s JPQL extensions include:

For descriptions of these extensions, see "EclipseLink Query Language" in Jakarta Persistence API (JPA) Extensions Reference for EclipseLink.

EclipseLink defines several special JPQL operators that allow performing database operations that are not possible in basic JPQL. These include:

For descriptions of these operators, see "Special Operators" in Jakarta Persistence API (JPA) Extensions Reference for EclipseLink.

As described in the "Stored Procedures" section of the JPA specification (http://jcp.org/en/jsr/detail?id=338), native SQL allows you to use named stored procedures either dynamically or specified by the NamedStoredProcedureQuery annotation. If you use annotations, the stored procedure must exist in the database. The annotation allows you to specify the types of all parameters to the stored procedure, their corresponding parameter modes, and the mapping of the result sets.

Metadata must be provided for all parameters by using the StoredProcedureParameter annotation. Parameters must be specified in the order in which they occur in the parameter list of the stored procedure. If parameter names are used, the parameter name is used to bind the parameter value and to extract the output value (if the parameter is an INOUT or OUT parameter).

If the stored procedure is not defined using metadata, then parameter and result set information must be provided dynamically.

EclipseLink’s Criteria API support has fewer restrictions than specified by JPA. In general, sub-queries and object path expressions are allowed in most places, including:

EclipseLink’s Criteria API support is built on top of EclipseLink native Expression API. EclipseLink provides the JpaCriteriaBuilder interface to allow the conversion of native Expression objects to and from JPA Expression objects. This allows the EclipseLink native Expression API to be mixed with the JPA Criteria API.

The EclipseLink native Expression API provides the following additional functionality:

EclipseLink Expressions can be combined with EclipseLink DatabaseQuerys to provide additional functionality:

EclipseLink expressions let you specify query search criteria based on your domain object model. When you execute the query, EclipseLink translates these search criteria into the appropriate query language for your platform.

The EclipseLink API provides the following two public classes to support expressions:

You can specify a selection criterion as an Expression with DatabaseQuery method setSelectionCriteria, and in a finder that takes an Expression.

For more information about using EclipseLink expressions, see Chapter 10, "Understanding EclipseLink Expressions".

The JPA query hints allow for queries or the find() operation to bypass, or refresh the shared cache. JPA cache query hints can be set on named or dynamic queries, or set in the properties map passed to the find() operation.

JPA 2.0 defines the following query hint properties to configure a queries interaction with the shared cache:

The EclipseLink cache query hints allow for queries or the find() operation to interact with the cache is the following ways:

Queries that access the cache have the following restrictions:

All EclipseLink query hints are defined in the QueryHints class in the org.eclipse.persistence.config package. When you set a hint, you can set the value using the public static final field in the appropriate configuration class in org.eclipse.persistence.config package, including the following:

You can specify EclipseLink query hints (JPA query extensions) either by using the @QueryHint annotation, by including the hints in the orm.xml or eclipselink-orm.xml files. or by using the setHint() method when executing a named or dynamic query (JPQL or Criteria).

Query settings and query hints that affect the generated SQL are not supported with SQL queries. Unsupported query hints include:

For descriptions of these extensions, see "EclipseLink Query Language" in Jakarta Persistence API (JPA) Extensions Reference for EclipseLink.

EclipseLink extends the Criteria API to allow a cast using Expression.as(type). The as method checks the hierarchy; and if type is a subclass of the type for the expression that is being called on, a cast is implemented.

The Expression.as(Class) can also be used for downcasting. The behavior of using Expression.as(Class) is as follows:

Oracle lets you specify SQL query additions called hints that can influence how the database server SQL optimizer works. This lets you influence decisions usually reserved for the optimizer. You use hints to specify things such as join order for a join statement, or the optimization approach for a SQL call.

You specify hints using the EclipseLink DatabaseQuery method setHintString.

For more information, see the performance tuning guide for your database.

Oracle Database Hierarchical Queries mechanism lets you select database rows based on hierarchical order. For example, you can design a query that reads the row of a given employee, followed by the rows of people the employee manages, followed by their managed employees, and so on.

You specify a hierarchical query clause using the setHierarchicalQueryClause method which appears in the EclipseLink DatabaseQuery subclass ReadAllQuery.

When using EclipseLink with Oracle9i Database (or later), you can acquire a special historical session where all objects are read as of a past time, and then you can express read queries depending on how your objects are changing over time. For more information, see "Using Oracle Flashback Technology" in Oracle Database Advanced Application Developer’s Guide.

A stored function is an Oracle Database mechanism that provides all the capabilities of a stored procedure in addition to returning a value. provides a number of annotations for working with stored functions as well as stored procedures. For a list of the EclipseLink annotation extensions for stored functions and procedures and links to their descriptions, see "Stored Procedure and Function Annotations" in Jakarta Persistence API (JPA) Extensions Reference for EclipseLink.

Expressions use standard boolean operators, such as AND, OR, and NOT, and you can combine multiple expressions to form more complex expressions.

EclipseLink supports many database functions using standard operator names that are translated to different databases. EclipseLink operators are supported on any database that has an equivalent function (or set of functions). For more information and a list of all supported functions and operators see "OPERATOR" and "FUNCTION" in Jakarta Persistence API (JPA) Extensions Reference for EclipseLink

EclipseLink expressions support a variety of database functions, which are described in the Expression class. Database functions let you define more flexible queries. You can use these functions in either a report query using a SELECT clause, or with comparisons in a query’s selection criteria using a WHERE clause.

Operators are relational operations that compare two values. EclipseLink expression operators are described in the ExpressionOperator class.

Mathematical functions are available through the ExpressionMath class. Mathematical function support in expressions is similar to the support provided by the Java class java.lang.Math.

You can use the Expression method getFunction to access database functions that EclipseLink does not support directly. The Expression API includes additional forms of the getFunction method that allow you to specify arguments. You can also create your own custom functions. For more information, see Java API Reference for EclipseLink.

Expressions can include an attribute that has a one-to-one relationship with another persistent class. A one-to-one relationship translates naturally into an SQL join that returns a single row.

You can query against complex relationships, such as one-to-many, many-to-many, direct collection, and aggregate collection relationships. Expressions for these types of relationships are more complex to build, because the relationships do not map directly to joins that yield a single row per object.

This section describes the following:

To use a NoSQL platform you must set both the eclipselink.nosql.connection-spec to the connection spec class name and the eclipselink.target-database to the platform class name. Each NoSQL platform also supports platform-specific properties that can be set using eclipselink.nosql.property. For more information on values for MongoDB, Oracle NoSQL, XML, JMS, and Oracle AQ, see "@NoSql" in Jakarta Persistence API (JPA) Extensions Reference for EclipseLink. See also Non-SQL Standard Database Support: NoSQL.