2 Building Blocks of a TopLink Project

This chapter describes the items that can be used in a TopLink project.

This chapter contains the following sections:

2.1 Building Blocks for Object-Relational Mapping

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 functionality includes 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 describes many of these features.

2.1.1 Object-Relational Entity Architecture

The entity architecture is comprised 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

Relationships between entity architectue elements
Description of "Figure 2-1 Relationships Between Entity Architecture Elements"

2.1.1.1 Entities

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 state 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 which 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 on the fly. 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 allows these extended mappings to be stored and managed externally. This external storage allows 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

2.1.1.2 Persistence and Persistence Units

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 need to 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 will inherit the properties defined in the persistence unit.

2.1.1.3 Entity Managers

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 just 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 may 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 allow 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.

2.1.2 Adding Metadata Using Annotations

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

2.1.3 Configuration Files

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

2.1.3.1 About the Default Configuration Values

Oracle TopLink is compliant with the JPA 2.0 specification. The configuration files allow 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.

For the TopLink extensions beyond the JPA specification, the defaults are described in the Oracle Fusion Middleware Java API Reference for EclipseLink.

2.1.3.2 Configuring Persistence Units Using persistence.xml

Use the JPA persistence file, persistence.xml, to configure the 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 should appear 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:

http://wiki.eclipse.org/EclipseLink/UserGuide/JPA/Basic_JPA_Development/Configuration/JPA/persistence.xml

2.1.3.3 Specifying TopLink Object-Relational Mappings Using eclipselink-orm.xml

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 in place 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, plus 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:

http://wiki.eclipse.org/EclipseLink/UserGuide/JPA/Basic_JPA_Development/Configuration/JPA/eclipselink-orm.xml

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 will enable many TopLink advanced features, but it may prevent the persistence unit from being portable to other JPA implementations.

2.1.4 Data Sources

An important part of the definition of the persistence unit is the location where the provider will be able to 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 allows you to 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 needed to access the database. For more information and an example of running an application in stand-alone 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

2.1.5 TopLink Caches

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 once an object has been 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 will not need to be rebuilt, and its relationships will not need to be re-fetched.

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 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 knows 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 just clear the cache.

For more information, see "EclipseLink/Examples/JPA/Caching" in the EclipseLink documentation.

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

2.1.5.1 Defining Cache Behavior

TopLink provides a @Cache annotation which allows you to 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

2.1.5.2 Caching in Clustered Environments

Caching in a clustered environment can have issues, as changes made on one server will not be 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 of invalidate changed objects.

  • Cache invalidation based on time-to-live or time-of-day.

  • Optimistic locking will prevent updates to stale objects, and trigger the objects to be invalidated in the cache.

2.1.6 Database Queries

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

2.1.6.1 JPQL

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 typos 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

2.1.6.2 Criteria Queries

JPA 2.0 defines a query criteria API to simplify dynamic query creation. Criteria queries can use parameters, and query hints the same as named queries. The query criteria API allows you to write any JQPL query—all JPQL keywords are defined in this API. The criteria API uses a set of Java interfaces to allow queries to be dynamically constructed. It also provides compile time checking for correctness to reduce the number of runtime typos.

See "Criteria Query" in the EclipseLink documentation.

http://wiki.eclipse.org/EclipseLink/UserGuide/JPA/Basic_JPA_Development/Querying/Criteria

2.1.6.3 Query Hints

A TopLink query hint allows a JPA Query to be customized or optimized 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

2.1.6.4 Advanced TopLink Native Query Support

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 raw 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 allow 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 allows you to 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 rich 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 convention ?n 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.

2.2 Building Blocks for Object-XML Mapping

The TopLink Object-XML component enables you to efficiently bind Java classes to XML schemas. Object-XML implements JAXB, allowing you to provide your mapping information through annotations as well as 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% 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 allow you to 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 describes many of these features.

2.2.1 Using TopLink Object-XML as the JAXB Provider

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.

2.2.2 Object-XML Architecture

In the sample Object-XML architecture illustrated in Figure 2-2, the starting point is a 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

Process in an Object-XML project.
Description of "Figure 2-2 A Sample Object-XML Architecture"

2.2.2.1 JAXB Contexts and JAXB Context Factories

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.

The JAXBContextFactory has the ability to:

  • Create a JAXBContext from an array of classes and a properties object

  • Create a JAXBContext 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 your JAXBContext. You have the option of bootstrapping 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.

2.2.3 Serving Metadata for Object-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, which is responsible for serving TopLink metadata. This allows you to store mapping information outside of your application and have it retrieved when the application's JAXBContext 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

2.2.4 XML Bindings

TopLink allows 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

2.2.5 Specifying TopLink Object-XML Mappings Using eclipselink-oxm.xml

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, plus 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 may prevent the model from being portable to other JAXB implementations.

2.2.6 Querying Objects by XPath

In addition to using conventional Java access methods to get and set your object's values, TopLink Object-XML also allows you to access values using an XPath statement. There are special APIs on TopLink's JAXBContext to allow 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