1 Overview of TopLink

Describes TopLink and its key features: the components that are included with TopLink, metadata, application architectures, mappings, and the API.

Understanding TopLink

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 338: Java Persistence 2.1. See http://jcp.org/en/jsr/detail?id=338.

    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 http://jcp.org/en/jsr/detail?id=222.


    The EclipseLink JAXB implementation is part of the EclipseLink MOXy component, which extends EclipseLink JAXB to support JavaScript Object Notation (JSON) documents. EclipseLink supports all object/XML options when reading and writing JSON. MOXy also includes support for the older native EclipseLink object/XML API).

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

  • SAP NetWeaver

  • 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 EclipseLink, see Key Features.

What Is the Object-Persistence Impedance Mismatch?

In a non-relational data source, you must match your Java entities with XML elements and schemas.

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.

The EclipseLink Solution

EclipseLink addresses the disparity between Java objects and data sources.

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

Key Features

Primary features of EclipseLink.

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

  • Just-in-time reading

  • 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 EclipseLink home page:


Key Concepts

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

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 persistence.xml and eclipselink-orm.xml files.

    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.

    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 Java Persistence API (JPA) Extensions Reference for EclipseLink.

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



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

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

See Understanding Entities.


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

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

See Understanding Descriptors .


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

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

See Understanding Mappings.

Data Access

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

See Understanding Data Access.


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

See Understanding Caching.


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.

See Understanding Queries.

Expression Framework

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

See Understanding EclipseLink Expressions.

NoSQL Databases

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.

See Understanding Non-relational Data Sources.

Performance Monitoring and Profiling

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

See "Enhancing Performance" in Solutions Guide for EclipseLink.

Key Components

The components contained by EclipseLink include JPA, JAXB, and MOXy components.

This figure illustrates the key components contained by EclipseLink.

Figure 1-1 EclipseLink Components

Description of Figure 1-1 follows
Description of "Figure 1-1 EclipseLink Components"

EclipseLink Core and API

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.x (JSR-338). The org.eclipse.persistence.* classes encapsulate the EclipseLink API and provide extensions beyond the specification. These extensions include EclipseLink-specific properties and annotations. For more information on the API, properties and extensions, see Java Persistence API (JPA) Extensions Reference for EclipseLink.

The JAXB APIs are included in Java SE 6, Java SE 7, Java SE 8, Java SE 9 and Java SE 10; these APIs were removed from Java SE 11. In the eclipselink.jar file, the org.eclipse.persistence.jaxb.* classes encapsulate the EclipseLink support for JAXB.

Object-Relational (JPA 2.1) Component

JPA 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 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.1 JPA update are: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.1 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

JAXB Component

JAXB is a Java API that allows a Java program to access an XML document by presenting that document to the program in a Java format.

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

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

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


MOXy Component

MOXy is the EclipseLink JAXB implementation.

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

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

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

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

  • 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 MOXy and these use cases, see Developing JAXB Applications EclipseLink MOXy.

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

  • 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 Developing JAXB Applications EclipseLink MOXy.

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

SDO Component

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 of 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 EclipseLink SDO in the EclipseLink documentation at https://www.eclipse.org/eclipselink/#moxy.

Database Web Services Component

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 Developing Persistence Architectures Using Oracle TopLink Database Web Services .

Key Tools

Oracle JDeveloper, Eclipse, and NetBeans development environments provide specific support for EclipseLink.

This section describes the support for EclipseLink provided by Oracle JDeveloper, Eclipse, and NetBeans development environments. Any tooling is compatible with EclipseLink, but these offer specific integration.

This section contains the following subsections:

Oracle JDeveloper

JDeveloper includes a number of features to aid in the development of applications that use EclipseLink.

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 EclipseLink support, see JDeveloper online help.

Oracle Enterprise Pack for Eclipse

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 http://www.oracle.com/technetwork/developer-tools/eclipse/overview/index.html.

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 https://www.eclipse.org/downloads/packages/.

The Dali Java Persistence Tools Project provides extensible frameworks and tools for defining and editing object-relational mappings for JPA entities. JPA mapping support focuses on minimizing the complexity of mapping by providing entity generation wizards, design-time validation, and a robust UI for entity and persistence unit configuration. For Dali information and downloads, see http://www.eclipse.org/webtools/dali.

Other tools and utilities from the Oracle, open source, and third party vendor communities are available from the Eclipse Marketplace at http://marketplace.eclipse.org/.


NetBeans IDE bundles GlassFish Server Open Source Edition, which includes EclipseLink.

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

For NetBeans information and downloads, see: http://netbeans.org/index.html.