Understanding EclipseLink, 2.4
  Go To Table Of Contents

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, eclipselink-orm.xml, and 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 Chapter 4, "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 Chapter 6, "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 the project XML file at run time.

See Chapter 7, "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 Chapter 8, "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 Chapter 9, "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 Chapter 10, "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 Chapter 11, "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 Chapter 12, "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 Chapter 13, "Understanding Performance Monitoring and Profiling."