This chapter describes the items that can be used in Object-Relational and Object-XML mapping projects.
This chapter contains the following sections:
TopLink provides a complete, JPA 2.0-compliant JPA implementation. It provides complete compliance for all of the mandatory features, many of the optional features, and some additional features. The additional nonmandatory features include object-level cache, distributed cache coordination, extensive performance tuning options, enhanced Oracle Database support, advanced mappings, optimistic and pessimistic locking options, extended annotations, and query hints.
For more information, see "The EclipseLink JPA User's Guide" in the EclipseLink documentation:
http://wiki.eclipse.org/EclipseLink/UserGuide/JPA
The following sections describe many of these features.
The entity architecture is composed of entities, persistence units, persistence contexts, entity manager factories, and entity managers. Figure 2-1 illustrates the relationships between these elements:
Persistence creates one or more EntityManagerFactory
objects.
Each EntityManagerFactory
is configured by one persistence unit.
EntityManagerFactory
creates one or more EntityManager
objects.
One or more EntityManagers
manage one PersistenceContext
.
Figure 2-1 Relationships Between Entity Architecture Elements
An entity is any application-defined object with the following characteristics:
It can be made persistent.
It has a persistent identity (a key that uniquely identifies an entity instance and distinguishes it from other instances of the same entity type. An entity has a persistent identity when there is a representation of it in a data store).
It is transactional in a sense that a persistence view of an entity is transactional (an entity is created, updated, and deleted within a transaction, and a transaction is required for the changes to be committed in the database). However, in-memory entities can be changed without the changes being persisted.
It is not a primitive, a primitive wrapper, or built-in object. An entity is a fine-grained object that has a set of aggregated states that is typically stored in a single place (such as a row in a table) and have relationships to other entities.
The entity also contains entity metadata that describes the entity. Entity metadata is not persisted to the database. It is used by the persistence layer to manage the entity from when it is loaded until it is invoked at runtime. Metadata can be expressed as annotations on the Java programming elements or in XML files (descriptors).
Beginning with the current release, you can define and use extensible entities where mappings can be added spontaneously. In this case, the entity stores extended attributes within a map instead of static attributes. The entity then defines how values from this map are mapped to the database using an eclipselink-orm.xml
mapping file. In addition to being able to dynamically define mappings, TopLink also enables these extended mappings to be stored and managed externally. This external storage enables your extended mappings to be defined while the application is running. For more information, see "EclipseLink/Examples/JPA/Extensibility" in the EclipseLink documentation:
http://wiki.eclipse.org/EclipseLink/Examples/JPA/Extensibility
Persistence is a characteristic of an entity. This means that the entity can be represented in a data store, and it can be accessed at a later time.
A persistence unit identifies a persistable unit and defines the properties associated with it. It also defines the objects that must be persisted. The objects can be entity classes, embeddable classes, or mapped superclasses. The persistence unit provides the configuration for the entity manager factory. Entity managers created by the entity manager factory inherit the properties defined in the persistence unit.
An entity manager enables API calls to perform operations on an entity. Until an entity manager is used to create, read, or write an entity, the entity is a nonpersistent Java object. When an entity manager obtains a reference to an entity, that entity becomes managed by the entity manager. The set of managed entity instances within an entity manager at any given time is called its persistence context; only one Java instance with the same persistent identity can exist in a persistence context at any time.
You can configure an entity manager to read or write to a particular database, to persist or manage certain types of objects, and to be implemented by a specific persistence provider. The persistence provider supplies the implementation for JPA, including the EntityManager
interface implementation, the Query implementation, and the SQL generation.Entity managers are provided by an EntityManagerFactory
. The configuration for an entity manager is bound to the EntityManagerFactory
, but it is defined separately as a persistence unit. You name persistence units to enable differentiation between EntityManagerFactory
objects. This way, your application obtains control over which configuration to use for operations on a specific entity. The configuration that describes the persistence unit is defined in a persistence.xml
file. You name persistence units to be able to request a specific configuration to be bound to an EntityManagerFactory
.
TopLink 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.
TopLink annotations expose some features of TopLink that are currently not available through the use of JPA metadata:
Basic properties—By default, TopLink persistence provider automatically configures a basic mapping for simple types. Use these annotations to fine-tune the immediate state of an entity in its fields or properties.
Relationships—TopLink has defaults for some relationships, such as OneToOne and OneToMany. Other relationships must be mapped explicitly. Use the annotations to specify the type and characteristics of entity relationships and to fine-tune how your database implements these relationships.
Embedded objects—An embedded object does not have its own persistent identity; it is dependent upon an entity for its identity. By default, TopLink persistence provider assumes that every entity is mapped to its own table. Use the following annotations to override this behavior for entities that are owned by other entities.
The following sections describe some of the key configuration files in a TopLink Object Relational Mapping project.
Oracle TopLink is compliant with the JPA 2.0 specification. The configuration files enable you to change the default values of properties that are defined in the specification. The defaults are extensive and specified in Chapter 10, "Metadata Annotations" in the JPA specification.
http://jcp.org/en/jsr/detail?id=317
The configuration is done by exception: if a value is not specified in one of the configuration files, then a default value is used.
Use the JPA persistence file, persistence.xml
, to configure a persistence unit. A persistence unit defines the details that are required when you acquire an entity manager. You can specify any vendor-specific extensions in the file by using a <properties>
element.
This file appears in the META-INF
/ directory of your persistence unit JAR file or in the classpath.
For more information, see "Configuring Persistence Units Using persistence.xml" in the EclipseLink documentation:
The standard JPA orm.xml
file is used to apply metadata to the persistence unit. It provides support for all of the JPA 2.0 mappings. You can use this file instead of annotations or to override JPA annotations in the source code. The EclipseLink eclipselink-orm.xml
file supports the mappings defined by the orm.xml
file and the full set of EclipseLink extensions beyond JPA 2.0.
For more information on the eclipselink-orm.xml
file, see "Specifying EclipseLink Object-Relational Mappings Using eclipselink-orm.xml" in the EclipseLink documentation:
See also "EclipseLink/Examples/JPA/EclipseLink-ORM.XML" in the EclipseLink documentation:
http://wiki.eclipse.org/EclipseLink/Examples/JPA/EclipseLink-ORM.XML
Note:
Using this mapping file enables many TopLink advanced features, but it may prevent the persistence unit from being portable to other JPA implementations.
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. In TopLink, the data source is often 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 TopLink 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.
TopLink also lets you specify a non-relational database data source, such as an XML schema.
Applications that use TopLink 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 "EclipseLink/Examples/JPA/OutsideContainer" in the EclipseLink documentation:
http://wiki.eclipse.org/EclipseLink/Examples/JPA/OutsideContainer
See also "EclipseLink/Examples/JPA/Tomcat Web Tutorial" in the EclipseLink documentation:
http://wiki.eclipse.org/EclipseLink/Examples/JPA/Tomcat_Web_Tutorial
By default, TopLink uses a shared object cache that caches a subset of all objects read and persisted for the persistence unit. The TopLink 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.
TopLink offers several mechanism to deal with stale data including:
Refreshing
Invalidation
Optimistic locking
Cache coordination
The shared cache can also be disabled, or it can be selectively enabled and disabled by using the @Cache
or @Cacheable
annotations.TopLink 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 object is 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 "EclipseLink/Examples/JPA/Caching" in the EclipseLink documentation.
http://wiki.eclipse.org/EclipseLink/Examples/JPA/Caching
TopLink provides an @Cache
annotation which lets you define cache properties. The properties include cache type, size, and refresh rules, among others. See "Using the @Cache
Annotation" in the EclipseLink documentation.
http://wiki.eclipse.org/EclipseLink/Examples/JPA/Caching#Using_the_.40Cache_Annotation
Caching in a clustered environment can have problems because changes made on one server are not reflected on objects cached in other servers. This is not a problem for read-only objects, but it is for objects that are frequently updated.
TopLink offers several solutions to this problem.
The cache can be disabled for the classes that frequently change.
Cache coordination can be used to broadcast changes between the servers in the cluster to update or invalidate changed objects.
Cache invalidation based on time-to-live or time-of-day.
Optimistic locking prevents updates to stale objects and triggers the objects to be invalidated in the cache.
The object-relational component of TopLink supports a variety of queries.
JPQL is a query language that is similar to SQL, but differs because it presents queries from an object model perspective and includes path expressions that enable navigation over the relationships defined for entities and dependent objects. TopLink enables you to use JPQL with regular Java objects. In TopLink, JPQL enables you to declare queries, using the attributes of each abstract entity in the object model.
The disadvantage of JPQL is that dynamic queries require performing string concatenations to build queries dynamically from web forms or dynamic content. JPQL is also not checked until runtime, making typographical errors more common. These disadvantages are reduced by using the query criteria API, described in the next section.
See "JPQL" in the EclipseLink documentation.
http://wiki.eclipse.org/EclipseLink/UserGuide/JPA/Basic_JPA_Development/Querying/JPQL
See also "EclipseLink/Release/2.1.0/JPAQueryEnhancements" in the EclipseLink documentation.
http://wiki.eclipse.org/EclipseLink/Release/2.1.0/JPAQueryEnhancements
JPA 2.0 defines a query criteria API to simplify dynamic query creation. Criteria queries can use parameters, and can use query hints the same as named queries. The query criteria API enables you to write any JQPL query—all JPQL keywords are defined in this API. The criteria API uses a set of Java interfaces to enable queries to be dynamically constructed. It also provides compile time checking for correctness to reduce the number of runtime typographical errors.
See "Criteria Query" in the EclipseLink documentation.
http://wiki.eclipse.org/EclipseLink/UserGuide/JPA/Basic_JPA_Development/Querying/Criteria
A TopLink query hint lets you customize or optimize a JPA Query beyond what is available in the JPA specification. Use TopLink JPA query hints to:
Construct a JPA query
Specify a JPA query using the @QueryHint
annotation
See "Query Hints" in the EclipseLink documentation.
http://wiki.eclipse.org/EclipseLink/UserGuide/JPA/Basic_JPA_Development/Query_Hints
TopLink provides an expression framework (also known as TopLink Native Query Support) with which you can express queries in a database-neutral fashion as an alternative to SQL when writing queries not supported by JPQL. TopLink expressions offer the following advantages over SQL when you access a database:
Expressions are easier to maintain because the database is abstracted.
Changes to descriptors or database tables do not affect the querying structures in the application.
Expressions enhance readability by standardizing the Query
interface so that it looks similar to traditional Java calling conventions.
Expressions enable read queries to transparently query between two classes that share a relationship. If these classes are stored in multiple tables in the database, TopLink automatically generates the appropriate join statements to return information from both tables.
Expressions simplify complex operations.
TopLink automatically generates the appropriate SQL from the specified expression.
The expression framework lets you work with expressions, database queries, call objects, and native queries. For more information on the queries described in the following list, see "Native SQL Queries" in the EclipseLink documentation.
http://wiki.eclipse.org/EclipseLink/UserGuide/JPA/Basic_JPA_Development/Querying/Native
JPA Query Using an EclipseLink DatabaseQuery
A TopLink DatabaseQuery
is a query object that provides a robust API for handling a variety of database query requirements, including reading and writing at the object level and at the data level.
JPA Query Using a TopLink Call Object
Using the DatabaseQuery
method setCall
, you can define your own TopLink Call
to accommodate a variety of data source options, such as SQL stored procedures and stored functions, EJB QL queries, and EIS interactions.
Named Parameters in a Native Query
Using TopLink, you can specify a named parameter in a native query using the TopLink # convention.
JPQL Positional Parameters in a Native Query
Using TopLink, you can specify positional parameters in a native query using the Java Persistence Query Language (JPQL) positional parameter ?n
convention to specify a parameter by number.
JDBC-Style Positional Parameters in a Native Query
Using TopLink, you can specify positional parameters in a native query using the JDBC-style positional parameter ?
convention.
The TopLink Object-XML component enables you to efficiently bind Java classes to XML schemas. Object-XML implements JAXB, enabling you to provide your mapping information through annotations and providing support for storing the mappings in XML format.
JAXB (Java Architecture for XML Binding—JSR 222) is the standard for XML Binding in Java. JAXB covers 100 percent of XML Schema concepts. TopLink provides a JAXB implementation with many extensions.
When using TopLink Object-XML as the JAXB provider, no metadata is required to convert your existing object model to XML. You can supply metadata (using annotations or XML) if you want to fine-tune the XML representation.
TopLink Object-XML includes many advanced mappings that let you handle complex XML structures without having to mirror the schema in your Java class model.
For more information, see "The EclipseLink MOXy (JAXB) User's Guide" in the EclipseLink documentation:
http://wiki.eclipse.org/EclipseLink/UserGuide/MOXy
The following sections describe many of these features.
Section 2.2.1, "Using TopLink Object-XML as the JAXB Provider"
Section 2.2.5, "Specifying TopLink Object-XML Mappings Using eclipselink-oxm.xml"
To use TopLink Object-XML as your JAXB provider, you must identify the entry point to the TopLink JAXB runtime. This entry point is the JAXBContextFactory
class.
Create a text file called jaxb.properties
and enter the path to the JAXBContextFactory
class as the value of the javax.xml.bind.context.factory
context parameter, for example:
javax.xml.bind.context.factory=org.eclipse.persistence.jaxb.JAXBContextFactory
The jaxb.properties
file must appear in the same package as the domain classes.
In the sample Object-XML architecture illustrated in Figure 2-2, 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-2 A Sample Object-XML Architecture
The JAXBContextFactory
class is the entry point into the TopLink JAXB runtime. It provides the required factory methods and can create new instances of JAXBContext
objects.
The JAXBContextFactory
class has the ability to:
Create a JAXBContext
object from an array of classes and a properties object
Create a JAXBContext
object from a context path and a classloader
The JAXBContext
class provides the client's entry point to the JAXB API. The JAXBContext
class is responsible for interpreting the metadata, generating schema files, and for creating instances of these JAXB objects: Marshaller
, Unmarshaller
, Binder
, Introspector
, and Validator
.
TopLink Object-XML offers several options when creating the JAXBContext
object. You have the option of booting from:
A list of one or more JAXB-annotated classes
A list of one or more TopLink XML Bindings documents defining the mappings for your Java classes
A combination of classes and XML Bindings
A list of context paths
A list of session names, referring to TopLink sessions defined in sessions.xml
In addition to the input options described in Section 2.2.2.1, "JAXB Contexts and JAXB Context Factories," TopLink Object-XML 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 "MetadataSource" in the EclipseLink documentation:
http://wiki.eclipse.org/EclipseLink/UserGuide/MOXy/Runtime/MetadataSource
TopLink enables you to use all of the standard JAXB annotations. In addition to the standard annotations, TopLink offers another way of expressing your metadata—the TopLink 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:
Augmenting or overriding existing annotations with additional mapping information.
Specifying all mappings information externally, without using Java annotations.
Defining your mappings across multiple Bindings documents.
Specifying virtual mappings that do not correspond to concrete Java fields.
For more information, see "XML Bindings" in the EclipseLink documentation:
http://wiki.eclipse.org/EclipseLink/UserGuide/MOXy/Runtime/XML_Bindings
You can use Java annotations to specify JAXB features in your TopLink projects. In addition to Java annotations, TopLink 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.
Note:
Using this mapping file will enable many TopLink advanced features but it can prevent the model from being portable to other JAXB implementations.
In addition to using conventional Java access methods to get and set your object's values, TopLink Object-XML also lets you access values using an XPath statement. There are special APIs on TopLink's JAXBContext
that enable you to get and set values by XPath. For more information, see "Querying Objects by XPath" in the EclipseLink documentation.
http://wiki.eclipse.org/EclipseLink/UserGuide/MOXy/Runtime/Querying_Objects_by_XPath