Cache Usage

The eclipselink.cache-usage hint specifies how the query should interact with the EclipseLink cache.

EclipseLink JPA 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.

If a read-object query contains an expression where the primary key is the only comparison, you can obtain a cache hit if you process the expression against the object in memory

CheckCacheByPrimaryKey

If a read-object query contains an expression that compares at least the primary key, you can obtain a cache hit if you process the expression against the objects in memory.

CheckCacheThenDatabase

You can configure any read-object query to check the cache completely before you resort to accessing the database.

CheckCacheOnly

You can configure any read-all query to check only the parent session cache (shared cache) and return the result from it without accessing the database.

ConformResultsInUnitOfWork

You can configure any read-object or read-all query within the context of a unit of work to conform the results with the changes to the object made within that unit of work. This includes new objects, deleted objects and changed objects.For more information, see Using Conforming Queries and Descriptors.

UseEntityDefault

Use the cache configuration as specified by the EclipseLink descriptor API for this entity.

Default

Note: The entity default value is to not check the cache (DoNotCheckCache). The query will access the database and synchronize with the cache. Unless refresh has been set on the query, the cached objects will be returned without being refreshed from the database. EclipseLink does not support the cache usage for native queries or queries that have complex result sets such as returning data or multiple objects.

Query Type

The eclipselink.query-type hint specifies the EclipseLink query type to use for the query.

For most JP QL queries, the org.eclipse.persistence.queries.ReportQuery or org.eclipse.persistence.queries.ReadAllQuery are used. The eclipselink.query-type hint lets you use other query types, such as org.eclipse.persistence.queries.ReadObjectQuery for queries that are know to return a single object.

Fetch Size

The eclipselink.jdbc.fetch-size hint specifies the number of rows that should be fetched from the database when more rows are needed1

For large queries that return a large number of objects you can configure the row fetch size used in the query to improve performance by reducing the number database hits required to satisfy the selection criteria. 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.
1 This property is dependent on the JDBC driver support.

Value

Description

0 to Integer.MAX_VALUE

As a String, depending on your JDBC driver. A value of 0 means the JDBC driver default will be used.Default = 0.

Timeout

The eclipselink.jdbc.timeout hint specifies the number of seconds EclipseLink will wait on a query before throwing a DatabaseException1

A value of 0 means EclipseLink will never time-out a query.

Valid values: 0 to Integer.MAX_VALUE (depending on your JDBC driver) as a String.

Default: 0

1 This property is dependent on the JDBC driver support.

Pessimistic Lock

The eclipselink.pessimistic-lock hint controls whether or not pessimistic locking is used.

The following are the valid values for the org.eclipse.persistence.config.PessimisticLock:

Batch

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.

Maintain Cache

The eclipselink.maintain-cache hint controls whether or not query results are cached in the session cache and provides a way to query the current database contents without affecting the current persistence context. It configures the query to return unmanaged instances so any updates to entities queried using this hint would have to be merged into the persistence context.

Read Only

The eclipselink.read-only hint retrieves read-only results back from the 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.

Result Collection Type

The eclipselink.result-collection-type hint configures the concrete class that EclipseLink should use to return its query result.

This lets you specify the type of collection in which the result will be returned.

Valid values: Java Class that implements the Collection interface.

Note: Typically, you would execute these queries by calling the getResultsList method, which returns the java.util.List, on the Query. This means that the class specified in this hint must implement the List interface, if you are invoking it using the getResultsList method.

Note: Specify the class without the ".class" notation. For example, java.util.Vector would work, not java.util.Vector.classEclipseLink will throw an exception, if you use this hint with a class that does not implement the Collection interface.