EclipseLink Solutions Guide for EclipseLink
Release 2.5
  Go To Table Of Contents

Performance Features

EclipseLink includes a number of performance features that make it the industry's best performing and most scalable JPA implementation. These features include:

Object Caching

The EclipseLink cache is an in-memory repository that stores recently read or written objects based on class and primary key values. The cache helps improve performance by holding recently read or written objects and accessing them in-memory to minimize database access.

Caching allows you to:

  • Set how long the cache lives and the time of day, a process called cache invalidation.

  • Configure cache types (Weak, Soft, SoftCache, HardCache, Full) on a per entity basis.

  • Configure cache size on a per entity basis.

  • Coordinate clustered caches.

Caching Annotations

EclipseLink defines these entity caching annotations:

  • @Cache

  • @TimeOfDay

  • @ExistenceChecking

EclipseLink also provides a number of persistence unit properties that you can specify to configure the EclipseLink cache (see "Persistence Property Extensions Reference" in Java Persistence API (JPA) Extensions Reference for Oracle TopLink). These properties might compliment or provide an alternative to the usage of annotations.

Using the @Cache Annotation

EclipseLink uses identity maps to cache objects in order to enhance performance, as well as maintain object identity. You can control the cache and its behavior by using the @Cache annotation in your entity classes. Example 18-1 shows how to implement this annotation.

Example 18-1 Using the @Cache Annotation

 @Cache (
 public class Employee implements Serializable {

For more information about object caching and using the @Cache annotation, see "@Cache" in the Java Persistence API (JPA) Extensions Reference for Oracle TopLink.


The scope of a query, the amount of data returned, and how that data is returned can all affect the performance of a EclipseLink-enabled application. EclipseLink query mechanisms enhance query performance by providing these features:

This section describes how these features improve performance.

Read-only Queries

EclipseLink uses the hint, QueryHint (@QueryHint) to retrieve read-only results back from a query. On nontransactional read operations, where the requested entity types are stored in the shared cache, you can request that the shared instance be returned instead of a detached copy.

For more information about read-only queries, see the documentation for the read-only hint in Java Persistence API (JPA) Extensions Reference for Oracle TopLink.

Join Fetching

Join Fetching enhances performance by enabling the joining and reading of the related objects in the same query as the source object. Enable Join Fetching by using the @JoinFetch annotation, as shown in Example 18-2. This example shows how the @JoinFetch annotation specifies the Employee field managedEmployees.

Example 18-2 Enabling JoinFetching

 public class Employee implements Serializable {
     @OneToMany(cascade=ALL, mappedBy="owner")
     public Collection<Employee> getManagedEmployees() {
         return managedEmployees;

For more details on Join Fetching, see "@JoinFetch" in Java Persistence API (JPA) Extensions Reference for Oracle TopLink.

Batch Reading

The eclipselink.batch hint supplies EclipseLink with batching information so subsequent queries of related objects can be optimized in batches instead of being retrieved one-by-one or in one large joined read. Batch reading is more efficient than joining because it avoids reading duplicate data. Batching is only allowed on queries that have a single object in their select clause.

Fetch Size

If you have large queries that return a large number of objects you can improve performance by reducing the number database hits required to satisfy the selection criteria. To do this, use the The eclipselink.jdbc.fetch-size hint. This hint specifies the number of rows that should be fetched from the database when more rows are required (depending on the JDBC driver support level). Most JDBC drivers default to a fetch size of 10, so if you are reading 1000 objects, increasing the fetch size to 256 can significantly reduce the time required to fetch the query's results. The optimal fetch size is not always obvious. Usually, a fetch size of one half or one quarter of the total expected result size is optimal. Note that if you are unsure of the result set size, incorrectly setting a fetch size too large or too small can decrease performance.


Slow paging can result in significant application overhead; however, EclipseLink includes a variety of solutions for improving paging results; for example, you can:

  • Configure the first and maximum number of rows to retrieve when executing a query.

  • Perform a query on the database for all of the ID values that match the criteria and then use these values to retrieve specific sets.

  • Configure EclipseLink to return a ScrollableCursor object from a query by using query hints. This returns a database cursor on the query's result set and allows the client to scroll through the results page by page.

For details on improving paging performance, see "How to use EclipseLink Pagination" in the EclipseLink online documentation, at:

Cache Usage

EclipseLink uses a shared cache mechanism that is scoped to the entire persistence unit. When operations are completed in a particular persistence context, the results are merged back into the shared cache so that other persistence contexts can use them. This happens regardless of whether the entity manager and persistence context are created in Java SE or Java EE. Any entity persisted or removed using the entity manager will always be kept consistent with the cache.

You can specify how the query should interact with the EclipseLink cache by using the eclipselink.cache-usage hint. For more information, see "cache usage" in tJava Persistence API (JPA) Extensions Reference for Oracle TopLink.


Mapping performance is enhanced by these features:

This section describes these features.

Read-Only Objects

When you declare a class read-only, clones of that class are neither created nor merged greatly improving performance. You can declare a class as read-only within the context of a unit of work by using the addReadOnlyClass() method.

  • To configure a read-only class for a single unit of work, specify that class as the argument to addReadOnlyClass():

  • To configure multiple classes as read-only, add them to a vector and specify that vector as the argument to addReadOnlyClass():


For more information about using read-only objects to enhance performance, see "@ReadOnly" in Java Persistence API (JPA) Extensions Reference for Oracle TopLink.


Weaving is a technique of manipulating the byte-code of compiled Java classes. The EclipseLink JPA persistence provider uses weaving to enhance both JPA entities and Plain Old Java Object (POJO) classes for such things as lazy loading, change tracking, fetch groups, and internal optimizations.Weaving can be performed either dynamically at runtime, when entities are loaded, or statically at compile time by post-processing the entity .class files. By default, EclipseLink uses dynamic weaving whenever possible. This includes inside an Java EE 5/6 application server and in Java SE when the EclipseLink agent is configured. Dynamic weaving is recommended as it is easy to configure and does not require any changes to a project's build process

For details on how to use weaving to enhance application performance, see "weaving" in Java Persistence API (JPA) Extensions Reference for Oracle TopLink.


To optimize performance during data transactions, use change tracking,. Change tracking allows you to tune the way EclipseLink detects changes that occur during a transaction. You should choose the strategy based on the usage and data modification patterns of the entity type as different types may have different access patterns and hence different settings, and so on.

Enable change tracking by using the @ChangeTracking annotation, as shown in Example 18-3.

Example 18-3 Enabling Change Tracking

@ChangeTracking(OBJECT) (
public class Employee implements Serializable {

For more details on change tracking, see "@ChangeTracking" in Java Persistence API (JPA) Extensions Reference for Oracle TopLink.


Database performance features in EclipseLink include:

This section describes these features.

Connection Pooling

Establishing a connection to a data source can be time-consuming, so reusing such connections in a connection pool can improve performance. EclipseLink uses connection pools to manage and share the connections used by server and client sessions. This feature reduces the number of connections required and allows your application to support many clients.

By default, EclipseLink sessions use internal connection pools. These pools allow you to optimize the creation of read connections for applications that read data only to display it and only infrequently modify data. The also allow you to use Workbench to configure the default (write) and read connection pools and to create additional connection pools for object identity or any other purpose.

In addition to internal connection pools, you can also configure EclipseLink to use any of these types of connection pools:

  • External connection pools; you must use this type of connection pool to integrate with external transaction controller (JTA).

  • Default (write) and read connection pools;

  • Sequence connection pools; Use these types of pools when your application requires table sequencing (that is, non-native sequencing) and you are using an external transaction controller. Application-specific connection pools; These are connection pools that you can create and use for any application purpose, provided you are using internal EclipseLink connection pools in a session.

For more information about using connection pools with EclipseLink, see the following topics in EclipseLink Concepts:

  • "Understanding Connections"

  • "Understanding Connection Pools"

Parameterized SQL and Statement Caching

Parameterized SQL can prevent the overall length of an SQL query from exceeding the statement length limit that your JDBC driver or database server imposes. Using parameterized SQL along with prepared statement caching can improve performance by reducing the number of times the database SQL engine parses and prepares SQL for a frequently called query

By default, EclipseLink enables parameterized SQL but not prepared statement caching. You should enable statement caching either in EclipseLink when using an internal connection pool or in the data source when using an external connection pool and want to specify a statement cache size appropriate for your application.

To enable parameterized SQL, add this line to the persistence.xml file that is in the same path as your domain classes:

<property name="eclipselink.jdbc.bind-parameters" value="true"/>

To disable parameterized SQL, change value= to false.

For more information about using parameterized SQL and statement caching, see "jdbc.bind-parameters" in Java Persistence API (JPA) Extensions Reference for Oracle TopLink.

Batch Writing

Batch writing helps optimize transactions with multiple write operations. Batch writing is enabled by using the EclipseLink JDBC extension batch-writing. You set one of the following parameter this property into the session at deployment time:

  • JDBC; Use JDBC batch writing.

  • Buffered; Do not use either JDBC batch writing nor native platform batch writing.

  • Oracle-JDBC; Use both JDBC batch writing and Oracle native platform batch writing and use OracleJDBC in your property map.

  • None; Disable batch writing.

For more information about batch writing, see "jdbc.batch-writing" in Java Persistence API (JPA) Extensions Reference for Oracle TopLink.


EclipseLink provides monitoring and optimization tools, as described in Monitoring and Optimizing EclipseLink-Enabled Applications.