1 General Concepts

This chapter describes Oracle TopLink and its key features: the components that constitute TopLink, metadata, application architectures, mappings, and the API.

This chapter contains the following sections:

1.1 What Is TopLink?

Oracle TopLink links object-oriented programs with relational data structures. Using TopLink, you can build high-performance applications that store persistent object-oriented data in a relational database. TopLink successfully transforms object-oriented data into either relational data or XML documents. You can integrate persistence and object-transformation into your application, while staying focused on your primary domain problem by taking advantage of an efficient, flexible, and field-proven solution.

TopLink includes EclipseLink. EclipseLink includes the open source implementation of the Java Persistence API (JPA) specification, plus extensions beyond what is defined in JPA. EclipseLink also includes the Java API for XML Binding (JAXB) specification. These extensions include persistence unit properties, query hints, annotations, TopLink's XML metadata, and TopLink's custom API. For a more detailed description of the contents of TopLink, see Section 1.4, "TopLink Components."

TopLink can be used with a wide range of Java Enterprise Edition (Java EE) and Java application architectures (see Section 1.5, "TopLink Application Architectures"). Use TopLink to design, implement, deploy, and optimize an advanced, object-persistence and object-transformation layer that supports a variety of data sources and formats, including the following:

  • Relational—For transactional persistence of Java objects to a relational database accessed using Java Database Connectivity (JDBC) drivers.

  • Object-Relational Data Type—For transactional persistence of Java objects to special purpose structured data source representations optimized for storage in object-relational data type databases such as Oracle Database.

  • Object-XML—For nontransactional, nonpersistent (in-memory) conversion between Java objects and XML Schema Document (XSD)-based XML documents using JAXB.

TopLink supports Enterprise JavaBeans (EJB) 3.0 in Java EE and Java SE environments including integration with a variety of application servers, such as Oracle WebLogic Server, Oracle Glassfish Server, and IBM WebSphere Application Server.

The extensive suite of development tools that TopLink provides, including Oracle JDeveloper TopLink Editor, lets you quickly capture and define object-to-data source and object-to-data representation mappings in a flexible, efficient metadata format.

The TopLink 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 Section 1.2, "TopLink Key Features."

1.1.1 What Is the Object-Persistence Impedance Mismatch?

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 or Enterprise JavaBeans (EJB) entity beans), 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.

1.1.2 The TopLink Solution

TopLink addresses the disparity between Java objects and data sources. TopLink is a persistence framework that manages relational, object-relational data type, and XML mappings in a seamless manner. This lets you build applications that combine the best aspects of object technology with a specific data source. TopLink lets you do the following:

  • Persist Java objects to virtually any relational database supported by a JDBC-compliant relational database

  • Perform in-memory conversions between Java objects and XML documents using JAXB based on XML Schema Document (XSD)

  • Map any object model to any relational or nonrelational schema, using Oracle JDeveloper TopLink Editor

  • Generate TopLink DBWS service descriptors and accompanying files, using JDeveloper DBWSBuilder

  • Use TopLink successfully, even if you are unfamiliar with SQL or JDBC, because TopLink offers a clear, object-oriented view of data sources

1.2 TopLink Key Features

TopLink provides an extensive set of features. You can use these features to rapidly build high-performance enterprise applications that are scalable and maintainable.

Some of the primary features of TopLink are the following:

  • Nonintrusive, flexible, metadata-based architecture

  • Architectural flexibility: Plain Old Java Objects (POJOs), JPA, JAXB, Service Data Objects (SDO), and web services provided by EclipseLink

  • 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: TopLink Expressions framework, Java Persistence Query Language (JPQL), Enterprise JavaBeans Query Language (EJB QL), and native SQL

  • Just-in-time reading

  • Object-level transaction support and integration with popular application servers and databases

  • Optimistic and pessimistic locking options and locking policies

  • Comprehensive visual design tools: Oracle JDeveloper TopLink Editor and Eclipse Dali Java Persistence Tools

For additional information and downloads, see the TopLink home page:


1.3 TopLink Metadata

TopLink 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 persistence.xml, eclipselink-orm.xml, and orm.xml files. Metadata is also captured by TopLink JPA annotations and TopLink property extensions in the persistence.xml file. The eclipselink-orm.xml file can also be used to specify TopLink property extensions beyond the JPA specification.

  • JAXB annotations in Java files and JAXB-defined properties in the eclipselink-oxm.xml file. The eclipselink-oxm.xml file can be used to define TopLink 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 TopLink API, to complete the application. See Section 2.1.2, "Adding Metadata Using Annotations" for more information.

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.


1.4 TopLink Components

Figure 1-1 illustrates the components contained by Oracle TopLink. The following sections describe the components.

Figure 1-1 TopLink Components

This figure is described in the text.
Description of "Figure 1-1 TopLink Components"

1.4.1 EclipseLink Core

The EclipseLink Core provides the EclipseLink runtime component. Access to the runtime component 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. For more information, see Section 1.7, "TopLink/EclipseLink API."

1.4.2 Object-Relational (JPA 2.0)

JPA, part of the Java EE EJB 3.0 specification, 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

    • Ordered lists

    • Combinations of access types

  • A criteria query API

  • Standardization of query "hints"

  • Standardization of additional metadata to support DDL generation

  • Support for validation

1.4.3 Object-XML (JAXB)

Object-XML, also known as MOXy, is a TopLink component that enables you to bind Java classes to XML schemas. Object-XML implements JAXB which lets you provide mapping information through annotations and provide support for storing the mappings in XML format. 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 TopLink JAXB compiler are Java POJO models. They implement the necessary interfaces 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 TopLink 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 "Getting Started with MOXy" in the EclipseLink documentation:


TopLink 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 deesign 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 "Mapping Simple Values" in the EclipseLink documentation.


  • You can instantiate objects in a way that is appropriate to your application (that is, using the default constructor).

  • 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 TopLink 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. You can also use annotations to provide the metadata. TopLink SDO

The Service Data Objects (SDO) component provides the reference implementation of Service Data Objects version 2.1.1. The TopLink 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.

TopLink SDO provides you with the following capabilities:

  • Use of the SDO APIs

  • Conversion an XML Schema to SDO metadata

  • Customization of your XSD for SDO usage

  • Use of dynamic data objects:

    • Use of dynamic data objects

    • 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:


1.4.4 Database Web Services

TopLink 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. TopLink DBWS extends TopLink's core capabilities while using existing ORM and OXM components.

TopLink DBWS has two parts: a design-time component (DBWSBuilder) and 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 Section 1.5.4, "TopLink Database Web Services."

1.4.5 TopLink Grid

Oracle TopLink enables you to scale out JPA applications using Oracle Coherence (Coherence) and to 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 TopLink JPA implementation (EclipseLink) 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 TopLink JPA 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.

1.5 TopLink Application Architectures

You can use TopLink in a variety of application architectures, including three-tier and two-tier architectures, with or without Java EE, to access a variety of data types on both relational and nonrelational data sources.

1.5.1 Three-Tier Architectures

The three-tier (or Java EE Web) application is one of the most common TopLink architectures. This architecture is characterized by a server-hosted environment in which the business logic, persistent entities, and the Oracle TopLink Foundation Library all exist in a single Java Virtual Machine (JVM).

The most common example of this architecture is a simple three-tier application in which the client browser accesses the application through servlets, JavaServer Pages (JSP), and HTML. The presentation layer communicates with TopLink through other Java classes in the same JVM, to provide the necessary persistence logic. This architecture supports multiple servers in a clustered environment, but there is no separation across JVMs from the presentation layer and the code that invokes the persistence logic against the persistent entities using TopLink. EJB Session Bean Facade

A popular variation on the three-tier application involves wrapping the business logic, including the TopLink access, in EJB session beans. This architecture provides a scalable deployment and includes integration with transaction services from the host application server.

Communication from the presentation layer occurs through calls to the EJB session beans. This architecture separates the application into different tiers for the deployment. The session bean architecture can persist either Java objects or EJB entity beans

1.5.2 Java SE or Thick Client

A two-tier (client and server) application is one in which the application accesses TopLink directly. Although less common than the other architectures discussed here, TopLink supports this architecture for smaller or embedded data processing applications.

1.5.3 Web Services

A web services architecture is similar to the Web or session-bean architecture. However, in a web services architecture you encapsulate business logic (the service) in a web service instead of (or in addition to) using session beans. In a web services architecture, clients communicate with your application using XML.

As in any architecture, you can use TopLink to persist objects to relational data sources. However, in a web services architecture, you can also use TopLink to map your object model to an XML schema for use with the web service or as the web service XML serializer.

1.5.4 TopLink Database Web Services

TopLink database web services architecture is similar to the Web services architecture. However, in a TopLink database web services architecture, you use TopLink to automatically generate web services that expose database operations such as queries, DML statements, stored procedures, and stored functions. Using TopLink database web services, you can provide Java EE-compliant, client-neutral access to a relational database without having to write Java code.

As in any web services architecture, clients communicate with your application using SOAP (XML) messages. However, in a TopLink database web services architecture, you need only specify an XSD for persistent classes. Clients need only invoke the operations the TopLink database web service exposes to create, read, update, and delete these persistent objects. TopLink database web services return objects or row set data, depending on the type of operation.

1.6 Mappings

Mapping refers to relating an object or XML schema to a corresponding relational database table. TopLink can transform data between an object representation (such as a Java class) and a representation specific to a data source (such as a database table). This transformation is called mapping, and it is the core of a TopLink project.

A mapping corresponds to a single data member of a domain object. It associates the object data member with its data source representation and defines the means of performing the two-way conversion between object and data source.

TopLink is a metadata-driven mapping engine with the mappings for different data sources provided through annotations, XML, or for advanced use cases, they can be written and augmented by using code.

For more information, see Section 1.6.2, "Object-Relational Data Type Mappings" and Section 1.6.3, "Object-XML Data Type Mappings."

1.6.1 Relational Mappings

Relational mappings transform any object data member type to a corresponding relational database (SQL) data source representation in any supported relational database. Relational mappings let you map an object model to a relational data model.

Relational mappings can also transform object data members that reference other domain objects that are stored in other tables in the database and are related through foreign keys.

1.6.2 Object-Relational Data Type Mappings

Object-relational data type mappings transform certain object data member types to structured data source representations optimized for storage in specialized object-relational databases such as Oracle Database. Object-relational data type mappings let you map an object model into an object-relational model. You can use only object-relational data type mappings with specialized object-relational databases optimized to support object-relational data type data source representations.

For more information, see "Object-Relational Data Type Mappings" in the EclipseLink documentation:


1.6.3 Object-XML Data Type Mappings

XML mappings transform object data members to the XML elements of an XML document whose structure is defined by an XML Schema Document (XSD). You can map the attributes of a Java object to a combination of XML simple and complex types using a wide variety of XML mapping types.

Classes are mapped to complex types, object relationships map to XML elements, and simple attributes map to text nodes and XML attributes. The real power in using Object-XML is that when mapping an object attribute to an XML document, XPath statements are used to specify the location of the XML data.

TopLink stores XML mappings for each class in the class descriptor. TopLink uses the descriptor to instantiate objects mapped from an XML document and to store new or modified objects as XML documents.

TopLink provides XML mappings that are not defined in the JPA specification. Some of the Object-XML extensions are available through TopLink annotations; others require programmatic changes to the underlying metadata.

For more information on these mappings, see "Mapping Simple Values" in the EclipseLink documentation:


1.7 TopLink/EclipseLink API

The EclipseLink API component of TopLink provides the reference implementation for JPA 2.0 (JSR-317). The org.eclipse.* 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 "Using EclipseLink JPA Extensions" in the EclipseLink documentation:


The EclipseLink API component also includes the JPA interfaces in the javax.persistence package.

The older Native TopLink, "Classic" TopLink, and TopLink Essentials persistence products, which were represented by the oracle.toplink.* classes, were removed from TopLink and replaced with the EclipseLink implementation.