This chapter describes Oracle TopLink and its key features: the components that are included with TopLink, metadata, application architectures, mappings, and the API.
This chapter contains the following sections:
Oracle TopLink is a mapping and persistence framework for use in a Java environment, including Java Platform, Standard Edition (Java SE) and Java Platform, Enterprise Edition (Java EE). The core functionality of TopLink is provided by EclipseLink, the open source mapping and persistence framework. The EclipseLink project is led by Oracle and is under the stewardship of the Eclipse Foundation. TopLink includes additional features beyond EclipseLink, described later in this document.
EclipseLink completely implements the following specifications, plus extensions to those specifications:
Java Persistence API (JPA)
JPA is the Java API for object/relational mapping (ORM), where Java objects are mapped to database artifacts, for the purpose of managing relational data in Java applications. JPA includes Java Persistence Query Language (JPQL), the Java Persistence Criteria API, and the Java API and XML schema for defining object/relational mapping metadata.
The latest version of the specification is JSR 317: Java Persistence 2.0. See
Some of the EclipseLink extensions to standard JPA are:
Support for mapping to nonrelational (NoSQL) databases.
Features useful in Software as a Service (SaaS) environments, including tenant isolation, extensible entities, external metadata sources.
Java API for RESTful Web Services (JAX-RS, defined in JSR 311).
Many other additional annotations, annotation extensions, Java Persistence Query Language (JPQL) extensions, JPA query customizations extensions, and persistence property extensions.
Java Architecture for XML Binding (JAXB)
JAXB is the Java API for object/XML mapping (OXM), where an XML document is bound to Java objects, based on the XML document's XSD schema. JAXB provides methods for unmarshalling (reading) XML instance documents into Java content trees, and then marshalling (writing) Java content trees back into XML instance documents. JAXB also provides a way to generate XML schema from Java objects.
The latest version of the specification is JSR 222: Java Architecture for XML Binding (JAXB) 2.0. See
The EclipseLink project uses the term"EclipseLink MOXy" to describe EclipseLink's full JAXB support plus its JSON support and support for the older native TopLink object/XML API (which are not defined in the JAXB specification). TopLink includes all the MOXy features; however the term is not regularly used in Oracle documentation.
In addition to the implementations of the standard specifications described above, EclipseLink includes the following:
EclipseLink Database Web Services (DBWS)
DBWS is a development tool and a runtime for providing Java EE-compliant, client-neutral access to relational database artifacts via a Web service. The development tool, DBWS Builder, is a command-line utility that generates the necessary deployment artifacts. (DBWS Builder is integrated into the Eclipse Dali Java Persistence toolset and into Oracle JDeveloper.) The runtime provider takes a service descriptor (along with related deployment artifacts) and realizes it as a JAX-WS 2.0 Web service. The runtime uses EclipseLink to bridge between the database and the XML SOAP Messages used by Web service clients.
EclipseLink Enterprise Information Services (EIS)
EIS is a facility for enabling the use of data stores through Java Connector Architecture (JCA) resource adapters. Using XML metadata, the interactions and their exchanged data are configured and mapped onto a domain model. The interactions data can be mapped from either the Common Client interface (CCI) or using XML schemas. This use is intended for non-relational data stores where no JDBC or SQL access is provided.
EclipseLink can be used with a wide range of Java Enterprise Edition (Java EE) and Java application architectures. Use EclipseLink to design, implement, deploy, and optimize an advanced, object-persistence and object-transformation layer that supports a variety of data sources and formats, including relational databases, nonrelational (NoSQL) databases, XML, JSON, and Web Services.
EclipseLink supports Java persistence in Java EE, Java SE and web containers including integration with various application servers including:
Oracle WebLogic Server
Oracle Glassfish Server
JBoss Web Server
IBM WebSphere application server
Oracle Containers for Java EE (OC4J)
Various other web containers, such as Apache Tomcat, Eclipse Gemini, IBM WebSphere CE, and SpringSource Server
EclipseLink lets you quickly capture and define object-to-data source and object-to-data representation mappings in a flexible, efficient metadata format.
The runtime lets your application exploit this mapping metadata with a simple session facade that provides in-depth support for data access, queries, transactions (both with and without an external transaction controller), and caching.
For more information about TopLink, see "Key Features".
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 Java 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 Java EE and the data source elements:
Fundamentally different technologies
Different skill sets
Different staff and ownership for each of the technologies
Different modeling and design principles
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:
Persist Java objects to virtually any relational database
Perform in-memory conversions between Java objects and XML and JSON documents
Map any object model to any relational or nonrelational schema
Use EclipseLink successfully, even if you are unfamiliar with SQL or JDBC, because EclipseLink offers a clear, object-oriented view of data sources
An extensive set of features are provided. You can use these features to rapidly build high-performance enterprise applications that are scalable and maintainable.
Some of the primary features are the following:
Nonintrusive, flexible, metadata-based architecture
Advanced mapping support and flexibility: relational, object-relational data type, and XML
Optimized for highly scalable performance and concurrency with extensive performance tuning options
Comprehensive object caching support including cluster integration for some application servers (such as Oracle Fusion Middleware Server)
Extensive query capability including: Java Persistence Query Language (JPQL), native SQL, and EclipseLink Expressions framework
Object-level transaction support and integration with popular application servers and databases
Optimistic and pessimistic locking options and locking policies
For additional information and downloads, see the TopLink home page:
The following sections provide a brief overview of new features in EclipseLink.
EclipseLink allows you to expose JPA entities through a standards-based (JAX-RS/JAXB/JPA) RESTful service. REST is an acronym for Representational State Transfer, which is a design idiom that embraces a stateless client-server architecture. In this architecture, Web services are viewed as resources which can be identified by their URIs.
Basic HTTP operations, such as create (POST), read (GET), update (PUT), and delete (DELETE) can be called on the services.
Data in RESTful services are referenced using a URI. A URI can be constructed in different ways, depending on the target, for example:
URI for JPA entities with a single-part primary key
URI for JPA entities with composite keys
URI with mapped named read queries
URI for name update and delete queries
Clients can interact with the RESTful service in any of these ways:
By using a web browser as the client
By using Java SE as the client
By using implementation-specific APIs
For more information, see "Exposing JPA Entities Through RESTful Services" in Oracle Fusion Middleware Solutions Guide for Oracle TopLink.
EclipseLink simplifies the development of application components that offer support for multiple tenants. Developers and deployers have complete control of the application and data isolation they require. Each tenant has access to its own data, while other tenants' data is invisible to it.
EclipseLink provides these options for tenant isolation:
Single-table tenant isolation allows tenants to share tables. Each tenant has its own rows, identified by discriminator columns, and those rows are invisible to other tenants.
With table-per-tenant tenant isolation, each tenant has its own table or tables, identified by table tenant discriminators, and those tables are invisible to other users.
With Virtual Private Database (VPD) tenant isolation, tenants use a VPD database, which provides the functionality to support multiple tenants sharing the same table.
For more information, see "Using Tenant Isolation" in Oracle Fusion Middleware Solutions Guide for Oracle TopLink.
NoSQL is a classification of database systems that do not support the SQL standard. The NoSQL classification can be expanded to include Enterprise Information Systems (EIS) including application databases, legacy databases, messaging systems, and transaction processing monitors. EclipseLink supports persistence of Java objects to NoSQL databases through the Java Persistence API (JPA). EclipseLink's native API is also supported with NoSQL databases.
NoSQL maps objects to structured data such as XML or JSON. It also supports embedded data, embedded collections, and all of the existing JPA mapping annotations.
Whether querying is supported in NoSQL depends on the NoSQL platform you are using. The JPA transaction API is supported with NoSQL data-sources. Some NoSQL data-sources might not support transactions, so the level of transaction support is dependent on the NoSQL platform.
For more information, see Chapter 12, "Understanding Non-relational Data Sources." See also "Using TopLink with NoSQL Databases" in Oracle Fusion Middleware Solutions Guide for Oracle TopLink.
JAXB binding metadata is used to marshall Java objects to and from JSON. This feature is useful when creating RESTful services; JAX-RS services can accept both XML and JSON messages.
For more information on JSON support, see "Oracle Fusion Middleware Developing JAXB Applications Using Oracle TopLink."
A shared (L2) object cache reduces database access for objects and their relationships. This cache is enabled by default which is normally not a problem, unless the contents of the database are modified directly by other applications, or by the same application on other servers in a clustered environment. This may result in stale data in the cache.
If the contents of the database are modified, then EclipseLink Database Change Notification (DCN) ensures that the contents of the cache are synchronized with the database. DCN allows shared caching to be used in the JPA environment.
Extensible entities allow mappings to be added dynamically. 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. Extensible entities are useful in a multi-tenant (or SaaS) architecture where a shared, generic application can be used by multiple clients (tenants). Tenants have private access to their own data, and to data shared with other tenants.
Using extensible entities, you can:
Build an application where some mappings are common to all users and some mappings are user-specific.
Add mappings to an application after it is made available to a customer (even post-deployment).
Use the same
EntityManagerFactory interface to work with data after mappings have changed.
Provide an additional source of metadata to be used by an application.
For more information on making entities extensible, see "Providing Software as a Service" in Oracle Fusion Middleware Solutions Guide for Oracle TopLink.
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. For more information, see "Using Multiple Databases with a Composite Persistence Unit" in Oracle Fusion Middleware Solutions Guide for Oracle TopLink.
You can store your mapping information in a metadata source that is external to the running application. Because the mapping information is retrieved when the application creates the persistence unit, you can dynamically override or extend mappings in a deployed application. See "Using an External Metadata Source" in Oracle Fusion Middleware Solutions Guide for Oracle TopLink.
You can scale out JPA applications using Oracle Coherence. TopLink Grid provides applications with a number of options on how they can scale, ranging from using Coherence as a distributed shared (L2) cache up to directing JP QL queries to Coherence for parallel execution across the grid to reduce database load. With TopLink Grid, you do not have to rewrite your applications to scale out. You can use your investment in JPA, and still take advantage of the scalability of Coherence. For more information, see "Integrating TopLink Grid with Oracle Coherence" in Integrating Oracle Coherence.
This section provides a brief introduction to several of the key concepts described in this documentation. The key concepts highlighted in this section are as follows:
EclipseLink metadata is the bridge between the development of an application and its deployed runtime environment. You can capture the metadata using:
JPA annotations in Java files and the JPA-defined properties in the
Metadata is also captured by EclipseLink JPA annotations and property extensions in the
persistence.xml file. The
eclipselink-orm.xml file can also be used to specify property extensions beyond the JPA specification.
JAXB annotations in Java files and JAXB-defined properties in the
eclipselink-oxm.xml file can be used to define property extensions beyond the JAXB specification.
Java and the EclipseLink API.
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 Oracle Fusion Middleware Java Persistence API (JPA) Extensions Reference for Oracle TopLink.
Mappings can be stored external to the application. This can be as simple as making the
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.
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.
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.
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 JDeveloper, then read from the project XML file at run time.
A data source platform includes options specific to a particular data source including binding, use of native SQL, use of batch writing, and sequencing.
EclipseLink supports a number of Oracle and non-Oracle data source platforms.
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.
You can to create, read, update, and delete persistent objects or data using queries in both Java EE and non-Java 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.
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.
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 Java Persistence API (JPA). EclipseLink's native API is also supported with NoSQL databases.
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.
Figure 1-1 illustrates the components contained by TopLink. The following sections describe the components.
Figure 1-1 TopLink Components
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-317). 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 Oracle Fusion Middleware Java Persistence API (JPA) Extensions Reference for Oracle TopLink.
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.
TopLink Grid APIs are included in the
toplink-grid.jar file. The
oracle.eclipselink.coherence.* classes encapsulate the EclipseLink support for TopLink Grid.
The old TopLink Essentials persistence API (an implementation of JPA 1), which was represented by the
oracle.toplink.* classes, was removed from TopLink and replaced with EclipseLink. The old native TopLink API (a pre-JPA mapping and persistence API), which was also represented by the
oracle.toplink.* classes, has been reimplemented in EclipseLink, using EclipseLink package names.
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 Java EE application server and outside an EJB container in a Java Standard Edition (Java SE) application. The main features included in the 2.0 JPA update are:
Expanded object/relational mapping functionality
Support for collections of embedded objects
Multiple levels of embedded objects
Combinations of access types
A criteria query API
Standardization of query "hints"
Standardization of additional metadata to support DDL generation
Support for validation
Object-XML, also known as MOXy, is an EclipseLink component that enables you to bind Java classes to XML schemas. Object-XML 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 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) only when you must fine-tune the XML representation of the model.
Using EclipseLink Object-XML, you can manipulate XML in the following ways:
Generate a Java Model from an XML schema
Specify the EclipseLink MOXy JAXB runtime
Use JAXB to manipulate XML
Generate an XML schema from a Java model
For more information on Object-XML and these use cases, see Oracle Fusion Middleware Developing JAXB Applications Using Oracle TopLink.
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:
You can design the domain classes specifically for your application using the appropriate patterns and practices.
You can use XPath-based mapping. This prevents the need for having a 1-to-1 relationship between classes and XML schema types. For more information, see Oracle Fusion Middleware Developing JAXB Applications Using Oracle TopLink.
You can instantiate objects in a way that is appropriate to your application.
You can control your own class path dependencies. Most JAXB implementations put vendor specific code in the generated classes that add class path dependencies to your application.
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:
Use of the SDO APIs
Conversion an XML Schema
Customization of your XSD for SDO usage
Use of dynamic data objects to manipulate XML
Use of static data objects
Run the SDO compiler—generate type safe data objects
Use type safe data objects to manipulate XML
For more information, see "Getting Started with EclipseLink SDO" in the EclipseLink documentation:
Database Web Services (DBWS) enables simple and efficient access to relational database artifacts by using a web service. It provides Java 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 Oracle Fusion Middleware Developing Persistence Architectures Using Oracle TopLink Database Web Services Developer's Guide.
You can scale out JPA applications using Oracle Coherence (Coherence) and write to the grid, treating the grid as the data source. TopLink Grid provides applications with a number of options on how they can scale, ranging from using Coherence as a distributed shared (L2) cache up to directing JPQL queries to Coherence for parallel execution across the grid to reduce database load. With TopLink Grid, you do not have to rewrite your applications to scale out.
TopLink Grid integrates the EclipseLink JPA implementation with Oracle Coherence and provides these development approaches:
You can use the Coherence API with caches backed by TopLink Grid to access relational data with a special cache loader and cache store interfaces that were implemented for JPA.
You can build applications using JPA and transparently use the power of the data grid for improved scalability and performance. In this JPA on the Grid approach, TopLink Grid provides a set of cache and query configuration options that lets you control how EclipseLink's JPA implementation uses Coherence.
TopLink Grid functionality is provided by the
toplink-grid.jar file. This file is available only if you have a license for Oracle Coherence.
This section describes the support for TopLink provided by Oracle JDeveloper, Oracle Enterprise Pack for Eclipse, and the Eclipse and NetBeans development environments. Any tooling is compatible with TopLink, but these offer specific integration.
This section contains the following subsections:
Oracle JDeveloper is a Java 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:
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 TopLink support, see JDeveloper online help.
Oracle Enterprise Pack for Eclipse (OEPE) is a set of plug-ins designed to support Java EE development, where Eclipse is your preferred IDE.
For OEPE information and downloads, see:
OEPE helps you complete the following tasks to create a persistence layer that uses EclipseLink's JPA implementation:
Configure the Persistence Provider for JPA Projects.
OEPE provides an EclipseLink project facet that you can use in your Eclipse JPA project. Selecting the EclipseLink project facet makes the following changes to your project:
The project build path is automatically configured to include EclipseLink persistence provider JAR files shipped with Oracle WebLogic Server 11g Release 1. Note that, even though the library files are not shipped with earlier versions of Oracle WebLogic Server, you can download them using the facet configuration wizard.
The database connection properties specific to EclipseLink can be automatically configured in the
persistence.xml file of your Eclipse JPA project.
Generate JPA Entities.
OEPE enables you to generate JPA entities using the OEPE JPA Entity Generation Wizard.
Map Java classes to an XML schema.
OEPE lets you map Java classes to an XML schema with MOXy as the JAXB provider.
Annotate Java Classes.
Using OEPE, you can annotate existing Java classes (POJOs) with JPA annotations based on a database schema. When you do, Eclipse adds JPA annotations to the appropriate accessors.
Use a JPA Entity Diagram Editor.
OEPE provides graphical user interfaces for viewing entity relationship within a JPA project. Using the Entity Diagram Editor, you can view and modify relationships between entities, get easy access to the entity source code, and create additional object-relational mappings. Note that the editor lets you edit properties of both entities and their fields. You can also edit the
persistence.xml file that describes the persistence context.
Use SQL Schema Viewer.
OEPE enables you to examine your database schema using the SQL Schema Viewer that displays tables and relationships between them. The viewer displays tables as table nodes. Each node lists all the columns in a table and shows column data types. The node also provides primary and foreign key indicators in the form of icons. Foreign key relationships between tables are represented by links in the form of arrows.
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:
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:
Other tools and utilities from the Oracle, open source, and third party vendor communities are available from the Eclipse Marketplace.
NetBeans IDE bundles Oracle GlassFish Server, which includes TopLink. 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
For NetBeans information and downloads, see: