4 JPA Query Customization Extensions

This chapter describes how to specify EcpliseLink query hints (JPA query extensions). You can specify EclipseLink query hints (JPA query extensions) by:

Using the @QueryHint annotation
Including the hints in the orm.xml or eclipselink-orm.xml file
Using the setHint() method when executing a named or dynamic query (JPQL or Criteria)

EclipseLink supplies the following query hints:

batch
batch.size
batch.type
cache-usage
cache-usage.indirection-policy
cursor
composite-unit.member
cursor.initial-size
cursor.page-size
exclusive-connection
flush
history.as-of
history.as-of.scn
inheritance.outer-join
jdbc.bind-parameters
jdbc.cache-statement
jdbc.fetch-size
jdbc.first-result
jdbc.max-rows
jdbc.native-connection
jdbc.parameter-delimiter
jdbc.timeout
join-fetch
left-join-fetch
load-group
load-group.attribute
maintain-cache
pessimistic-lock
prepare
query-results-cache
query-results-cache.expiry
query-results-cache.expiry-time-of-day
query-results-cache.ignore-null
query-results-cache.randomize-expiry
query-results-cache.size
query-results-cache.type
query-type
read-only
refresh
refresh.cascade
result-collection-type
sql.hint

All EclipseLink query hints are defined in the QueryHints class in the org.eclipse.persistence.config package. When you set a hint, you can set the value using the public static final field in the appropriate configuration class in org.eclipse.persistence.config package, including the following:

HintValues
CacheUsage
PessimisticLock
QueryType

For more information, see Section 10.3.1 "NamedQuery Annotation" in the JPA Specification (http://jcp.org/en/jsr/detail?id=317).

batch

Use eclipselink.batch to supply 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.

Values

This query hint accepts a single-valued, relationship path expression.

Usage

Using the eclipselink.batch hint is more efficient than joining, because EclipseLink avoids reading duplicate data.

You can only batch queries that have a single object in the select clause.

Valid values: a single-valued relationship path expression.

Note:

Use dot notation to access nested attributes. For example, to batch-read an employee's manager's address, use e.manager.address.

Examples

Example 4-1 shows how to use this hint in a JPA query.

Example 4-1 Using batch in a JPA Query

import org.eclipse.persistence.config.HintValues;
 import org.eclipse.persistence.config.QueryHints;
 query.setHint("eclipselink.batch", "e.address");

Example 4-2 shows how to use this hint with the @QueryHint annotation.

Example 4-2 Using batch in a @QueryHint Annotation

import org.eclipse.persistence.config.HintValues;
 import org.eclipse.persistence.config.QueryHints;
 @QueryHint(name=QueryHints.BATCH, value="e.address");

See Also

For more information, see:

"EclipseLink" JPA Query Hints http://wiki.eclipse.org/EclipseLink/UserGuide/JPA/Basic_JPA_Development/Querying/Query_Hints
"join-fetch"
"batch.size"
"batch.type"
"Querying" in Solutions Guide for EclispeLink

batch.size

Use eclipselink.batch.size to configure the batch size when using batch.type set to IN.

Values

Table 4-1 describes this persistence property's values.

Table 4-1 Valid Values for batch.size

Value	Description
Size	The number of keys in each `IN` clause Default: 256 or the query's `pageSize` (for cursor queries)

Examples

Example 4-3 shows how to use this hint in a JPA query.

Example 4-3 Using batch.size in a JPA Query

import org.eclipse.persistence.config.HintValues;
 import org.eclipse.persistence.config.QueryHints;
 query.setHint("eclipselink.BATCH_SIZE", "3");

Example 4-4 shows how to use this hint with the @QueryHint annotation.

Example 4-4 Using batch.size in a @QueryHint Annotation

import org.eclipse.persistence.config.HintValues;
 import org.eclipse.persistence.config.QueryHints;
 @QueryHint(name=QueryHints.BATCH_SIZE, value="3");

See Also

For more information, see:

"batch"

batch.type

Use eclipselink.batch.type to specify the type of batch fetching the query should use for any batch-fetched relationships.

Values

Table 4-2 describes this query hint's values.

Table 4-2 Valid Values for batch.type

Value	Description
`JOIN`	(Default) The original query's selection criteria is joined with the batch query.
`EXISTS`	Uses an SQL `EXISTS` and a sub-select in the batch query instead of a join.
`IN`	Uses an SQL `IN` clause in the batch query passing in the source object IDs.

Examples

Example 4-5 shows how to use this hint in a JPA query.

Example 4-5 Using batch.type in a JPA Query

import org.eclipse.persistence.config.HintValues;
 import org.eclipse.persistence.config.QueryHints;
 query.setHint("eclipselink.BATCH_TYPE", "EXISTS");

Example 4-6 shows how to use this hint with the @QueryHint annotation.

Example 4-6 Using batch.type in a @QueryHint Annotation

import org.eclipse.persistence.config.HintValues;
 import org.eclipse.persistence.config.QueryHints;
 @QueryHint(name=QueryHints.BATCH_TYPE, value="EXISTS");

See Also

For more information, see:

cache-usage

Use eclipselink.cache-usage to specify how the query should interact with the EclipseLink cache.

Values

Table 4-3 describes this query hint's valid values.

Table 4-3 Valid Values for org.eclipse.persistence.config.CacheUsage

Value	Description
`DoNotCheckCache`	Always go to the database.
`CheckCacheByExactPrimaryKey`	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.
`UseEntityDefault`	(Default) Use the cache configuration as specified by the EclipseLink descriptor API for this entity. 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.

Usage

EclipseLink JPA uses a shared cache assessed across the entire persistence unit. After completing an operation in a particular persistence context, EclipseLink merges the results into the shared cache, so that other persistence contexts can use the results 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 consistently maintained with the cache.

Examples

Example 4-7 shows how to use this hint in a JPA query.

Example 4-7 Using cache-usage in a JPA Query

import org.eclipse.persistence.config.CacheUsage;
 import org.eclipse.persistence.config.QueryHints;
 query.setHint(QueryHints.CACHE_USAGE, CacheUsage.CheckCacheOnly);

Example 4-8 shows how to use this hint with the @QueryHint annotation.

Example 4-8 Using cache-usage in a @QueryHint Annotation

import org.eclipse.persistence.config.CacheUsage;
 import org.eclipse.persistence.config.TargetDatabase;
 @QueryHint(name=QueryHints.CACHE_USAGE, value=CacheUsage.CheckCacheOnly);

See Also

For more information, see:

"EclipseLink Caches" in Understanding EclipseLink
"Querying" in Solutions Guide for EclispeLink
"Enhancing Performance" in Solutions Guide for EclispeLink
"cache-usage.indirection-policy"

cache-usage.indirection-policy

Use eclipselink.cache-usage.indirection-policy (with cache-usage) to configure in-memory querying and conforming's treatment of uninstantiated indirection/lazy relationships.

Values

Table 4-4 describes this query hint's values.

Table 4-4 Valid Values for cache-usage.indirection-policy

Value	Description
`Conform`	If conforming encounters an uninstantiated indirection/lazy object, it is assumed to conform.
`Exception`	(Default) If conforming encounters an uninstantiated indirection/lazy object an exception is thrown.
`NotConform`	If conforming encounters an uninstantiated indirection/lazy object it is assumed to not conform.
`Trigger`	If conforming encounters an uninstantiated indirection/lazy object it is triggered.

Usage

This hint applies only when the query traverses a join across a lazy relationship.

Examples

Example 4-9 shows how to use this hint in a JPA query.

Example 4-9 Using cache-usage.indirection-policy in a JPA Query

query.setHint(QueryHints.INDIRECTION_POLICY, CacheUsageIndirectionPolicy.Trigger);

Example 4-10 shows how to use this hint with the @QueryHint annotation.

Example 4-10 Using cache-usage.indirection-policy in a @QueryHint Annotation

@QueryHint(name=QueryHints.INDIRECTION_POLICY, value=CacheUsageIndirectionPolicy.Trigger)

See Also

For more information, see:

"EclipseLink" JPA Query Hints http://wiki.eclipse.org/EclipseLink/UserGuide/JPA/Basic_JPA_Development/Querying/Query_Hints
"EclipseLink Caches" in Understanding EclipseLink
"Querying" in Solutions Guide for EclispeLink
"cache-usage"

cursor

Use eclipselink.cursor to configure the query to return a CursoredStream.

Values

Table 4-5 describes this persistence property's values.

Table 4-5 Valid Values for cursor

Value	Description
`true`
`false`	(Default)

Usage

A Cursor is a stream of the JDBC ResultSet. Cursors are useful for large results sets, or when you only need the few results of a query.

A cursor implements Enumeration, when the each next() will fetch the next from the JDBC ResultSet, and builds the resulting Object or value. A Cursor requires, and will keep, a live JDBC connection. You must use close() to free the Cursor's resources.

You can access a Cursor from a JPA Query through getSingleResult(), or from JpaQuery using getResultCursor().

Tip:

You can use MAX_ROWS and FIRST_RESULT instead of a Cursor to obtain a page of results.

Examples

Example 4-11 shows how to use this hint in a JPA query.

Example 4-11 Using cursor in a JPA Query

import org.eclipse.persistence.config.HintValues;
 import org.eclipse.persistence.config.QueryHints;
 query.setHint("eclipselink.cursor", "TRUE");

Example 4-12 shows how to use this hint with the @QueryHint annotation.

Example 4-12 Using cursor in a @QueryHint Annotation

import org.eclipse.persistence.config.HintValues;
 import org.eclipse.persistence.config.QueryHints;
 @QueryHint(name=QueryHints.CURSOR, value="TRUE");

See Also

For more information, see:

"cursor.initial-size"
"cursor.page-size"

composite-unit.member

The ecliplselink.composite-unit.member query hint specifies the name of the composite member persistence unit on which you want to execute the query. You must use it on a native query executed on a composite persistence unit.

Values

Table 4-6 describes this persistence property's values.

Table 4-6 Valid Values for composite-unit.member

Value	Description
value	The name of the composite persistence unit.

Examples

Example 4-13 shows how to use this hint in a JPA query.

Example 4-13 Using composite-unit.member in a JPA query

import org.eclipse.persistence.config.QueryHints;
query.setHint("eclipselink.composite-unit.member", "mypersistentunit");

Example 4-14 shows how to use this hint with the @QueryHint annotation.

Example 4-14 Using composite-unit.member in an @QueryHint annotation

import org.eclipse.persistence.config.QueryHints;
@QueryHint(name=QueryHints.COMPOSITE_UNIT_MEMBER, 
value="mypersistentunit");

cursor.initial-size

Use eclipselink.cursor.initial-size to configure the query to return a CursoredStream with the specified initial size.

Values

Table 4-7 describes this query hint's values.

Table 4-7 Valid Values for cursor.initial-size

Value	Description
`Integer` or `Strings` that can be parsed to `int` values	The initial number of objects that are prebuilt for the stream before a `next()` is called

Examples

Example 4-15 shows how to use this hint in a JPA query.

Example 4-15 Using cursor.initial-size in a JPA Query

import org.eclipse.persistence.config.HintValues;
 import org.eclipse.persistence.config.QueryHints;
 query.setHint("eclipselink.cursor_initial_size", "10");

Example 4-16 shows how to use this hint with the @QueryHint annotation.

Example 4-16 Using cursor.initial-size in a @QueryHint Annotation

import org.eclipse.persistence.config.HintValues;
 import org.eclipse.persistence.config.QueryHints;
 @QueryHint(name=QueryHints.CURSOR_INITIAL_SIZE, value="10");

See Also

For more information, see:

"cursor"

cursor.page-size

Use eclipselink.cursor.page-size to configure the query to return a CursoredStream with the specified page size.

Values

Table 4-8 describes this query hint's values.

Table 4-8 Valid Values for cursor.page-size

Value	Description
`Integer` or `Strings` that can be parsed to `int` values	The number of objects that are fetched from the stream on a `next()` call, if the buffer of objects is empty

Examples

Example 4-17 shows how to use this hint in a JPA query.

Example 4-17 Using cursor.page-size in a JPA Query

import org.eclipse.persistence.config.HintValues;
 import org.eclipse.persistence.config.QueryHints;
 query.setHint("eclipselink.CURSOR_PAGE_SIZE", "10");

Example 4-18 shows how to use this hint with the @QueryHint annotation.

Example 4-18 Using cursor.page-size in a @QueryHint Annotation

import org.eclipse.persistence.config.HintValues;
 import org.eclipse.persistence.config.QueryHints;
 @QueryHint(name=QueryHints.CURSOR_PAGE_SIZE, value="10");

See Also

For more information, see:

"cursor"

exclusive-connection

Use eclipselink.exclusive-connection to specify if the query should use the exclusive (transactional/write) connection.

Values

Table 4-9 describes this query hint's values.

Table 4-9 Valid Values for exclusive-connection

Value	Description
true	The query is executed through the exclusive connection.
false

Usage

This is valid only when an EXCLUSIVE_CONNECTION_MODE property has been set for the persistence unit (such as VPD). If a jdbc.exclusive-connection.mode has been configured, use this query hint to ensure that the query is executed through the exclusive connection.

This may be required in certain cases, such as when database security prevents a query joining to a secure table from returning the correct results, when executed through the shared connection.

Examples

Example 4-19 shows how to use this hint in a JPA query.

Example 4-19 Using exclusive-connection in a JPA Query

import org.eclipse.persistence.config.HintValues;
 import org.eclipse.persistence.config.QueryHints;
 query.setHint("eclipselink.EXCLUSIVE_CONNECTION", "TRUE");

Example 4-20 shows how to use this hint with the @QueryHint annotation.

Example 4-20 Using exclusive-connection in a @QueryHint Annotation

import org.eclipse.persistence.config.HintValues;
 import org.eclipse.persistence.config.QueryHints;
 @QueryHint(name=QueryHints.EXCLUSIVE_CONNECTION, value="TRUE");

See Also

For more information, see:

"jdbc.exclusive-connection.mode"

flush

Use eclipselink.flush to specify if the query should flush the persistence context before executing.

Values

Table 4-10 describes this query hint's values.

Table 4-10 Valid Values for flush

Value	Description
`true`	The query triggers a flush of the persistence context before execution
`false`	(Default)

Usage

If the query may access objects that have been changed in the persistence context, you must trigger a flush in order for the query to see the changes. If the query does not require seeing the changes, you should avoid the flush in order to improve performance.

You can also configure the flush-mode as a persistence unit property. See "flush-clear.cache" for more information.

You can also use conforming to query changes without requiring a flush. See "cache-usage" for more information.

Examples

Example 4-21 shows how to use this hint in a JPA query.

Example 4-21 Using flush in a JPA Query

import org.eclipse.persistence.config.HintValues;
 import org.eclipse.persistence.config.QueryHints;
 query.setHint("eclipselink.FLUSH", "TRUE");

Example 4-22 shows how to use this hint with the @QueryHint annotation.

Example 4-22 Using flush in a @QueryHint Annotation

import org.eclipse.persistence.config.HintValues;
 import org.eclipse.persistence.config.QueryHints;
 @QueryHint(name=QueryHints.FLUSH, value="TRUE");

See Also

For more information, see:

"persistence-context.flush-mode"
"flush-clear.cache"
"EclipseLink" JPA Query Hints http://wiki.eclipse.org/EclipseLink/UserGuide/JPA/Basic_JPA_Development/Querying/Query_Hints
"EclipseLink Caches" in Understanding EclipseLink
"Querying" in Solutions Guide for EclispeLink
"cache-usage.indirection-policy"
"cache-usage"

history.as-of

Configures the query to query the state of the object as-of a point in time.

Values

Table 4-11 describes this query hint's values.

Table 4-11 Valid Values for history.as-of

Value	Description
Timestamp	Timestamp, in the form: `YYYY/MM/DD HH:MM:SS.n`

Usage

Both the query execution and result will conform to the database as it existed based on the database SCN.

Note:

This query hint requires a class with historical support or when using Oracle Flashback.

Examples

Example 4-23 shows how to use this hint in a JPA query.

Example 4-23 Using history.as-of in a JPA Query

import org.eclipse.persistence.config.HintValues;
 import org.eclipse.persistence.config.QueryHints;
 query.setHint("eclipselink.AS_OF", "2012/10/15 11:21:18.2");

Example 4-24 shows how to use this hint with the @QueryHint annotation.

Example 4-24 Using history.as-of in @QueryHint Annotation

import org.eclipse.persistence.config.HintValues;
 import org.eclipse.persistence.config.QueryHints;
 @QueryHint(name=QueryHints.AS_OF, value="2012/10/15 11:21:18.2");

See Also

For more information, see:

"history.as-of.scn"
"Using Oracle Flashback Technology" in Oracle Database Advanced Application Developer's Guide

history.as-of.scn

Use eclipselink.history.as-of.scn to configure the query to query the state of the object as-of a database SCN (System Change Number).

Values

Table 4-12 describes this query hint's values.

Table 4-12 Valid Values for history.as-of.scn

Value	Description
value	Integer SCN value

Usage

Note:

This query hint requires Oracle Flashback support.

Examples

Example 4-25 shows how to use this hint in a JPA query.

Example 4-25 Using history.as-of.scn in a JPA Query

import org.eclipse.persistence.config.HintValues;
 import org.eclipse.persistence.config.QueryHints;
 query.setHint("eclipselink.AS_OF_SCN", "3");

Example 4-26 shows how to use this hint with the @QueryHint annotation.

Example 4-26 Using history.as-of.scn in @QueryHint Annotation

import org.eclipse.persistence.config.HintValues;
 import org.eclipse.persistence.config.QueryHints;
 @QueryHint(name=QueryHints.AS_OF_SCN, value="3");

See Also

For more information, see:

"history.as-of"
"Using Oracle Flashback Technology" in Oracle Database Advanced Application Developer's Guide

inheritance.outer-join

Use eclipselink.inheritance.outer-join to configure the query to use an outer-join for all subclasses.

Values

Table 4-13 describes this query hint's values.

Table 4-13 Valid Values for inheritance.outer-join

Value	Description
`true`	Use outer-join.
`false`	(Default) Do not use outer-join; execute a separate query for each subclass.

Usage

This query hint can be used queries to root or branch inherited classes.

You can also configure this behavior by using a DescriptorCustomizer (see "descriptor.customizer").

Note:

This is required for correct ordering, firstResult, maxResult, and cursors.

Examples

Example 4-27 shows how to use this hint in a JPA query.

Example 4-27 Using inheritance.outer-join in a JPA Query

import org.eclipse.persistence.config.HintValues;
 import org.eclipse.persistence.config.QueryHints;
 query.setHint("eclipselink.INHERITANCE_OUTER_JOIN", "TRUE");

Example 4-28 shows how to use this hint with the @QueryHint annotation.

Example 4-28 Using inheritance.outer-join in a @QueryHint Annotation

import org.eclipse.persistence.config.HintValues;
 import org.eclipse.persistence.config.QueryHints;
 @QueryHint(name=QueryHints.INHERITANCE_OUTER_JOIN, value="TRUE");

See Also

For more information, see:

"Inheritance" in Understanding EclipseLink
"Enhancing Performance" in Solutions Guide for EclispeLink

jdbc.bind-parameters

Use eclipselink.jdbc.bind-parameters to specify if the query uses parameter binding (parameterized SQL).

Values

Table 4-14 describes this query hint's valid values.

Table 4-14 Valid Values for org.eclipse.persistence.config.HintValues

Value	Description
`TRUE`	Bind all parameters.
`FALSE`	Do not bind all parameters.
`PERSISTENCE_UNIT_DEFAULT`	(Default) Use the parameter binding setting made in your EclipseLink session's database login, which is true by default.

Usage

By default, EclipseLink enables parameter binding and statement caching. This causes EclipseLink to use a prepared statement, binding all SQL parameters and caching the prepared statement. When you re-execute this query, you avoid the SQL preparation, which improves performance.

You can also configure parameter binding for the persistence unit in the persistence.xml file (when used in a Java SE environment).

Examples

Example 4-29 shows how to use this hint in a JPA query.

Example 4-29 Using bind-parameters in a JPA Query

import org.eclipse.persistence.config.HintValues;
 import org.eclipse.persistence.config.QueryHints;
 query.setHint(QueryHints.BIND_PARAMETERS, HintValues.TRUE);

Example 4-30 shows how to use this hint with the @QueryHint annotation.

Example 4-30 Using bind-parameters in a @QueryHint Annotation

import org.eclipse.persistence.config.HintValues;
 import org.eclipse.persistence.config.TargetDatabase;
 @QueryHint(name=QueryHints.BIND_PARAMETERS, value=HintValues.TRUE);

Example 4-31 shows how to configure parameter binding in the persistence unit persistence.xml file.

Example 4-31 Specifying Parameter Binding Persistence Unit Property

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

Or by importing a property map:

import org.eclipse.persistence.config.PersistenceUnitProperties;
propertiesMap.put(PersistenceUnitProperties.NATIVE_SQL, "true");

See Also

For more information, see:

"jdbc.cache-statements"
"jdbc.batch-writing.size"
"Parameterized SQL and Statement Caching" in Solutions Guide for EclispeLink

jdbc.allow-partial-bind-parameters

Use eclipselink.jdbc.allow-partial-bind-parameters to specify if parameter binding decisions apply to individual expressions or the whole query.

Values

Table 4-83 describes this persistence property's values.

Table 4-83 Valid Values for jdbc.allow-partial-bind-parameters

Value	Description
`TRUE`	EclipseLink binds parameters per SQL function/expression.
`FALSE`	(Default) EclipseLink either binds all parameters or no parameters; depending on database support.

Usage

EclipseLink determines binding behavior based on the database's support for binding. If the database does not support binding, for a specific expression, EclipseLink will disable parameter binding for the whole query. Setting this property to 'true' will allow EclipseLink to bind per expression, instead of per query.

Examples

Example 4-83 shows how to configure parameter binding in the persistence unit persistence.xml file.

Example 4-83 Specifying Allow Partial Parameter Binding Persistence Unit Property

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

Or by importing a property map:

import org.eclipse.persistence.config.PersistenceUnitProperties;
propertiesMap.put(PersistenceUnitProperties.JDBC_ALLOW_PARTIAL_PARAMETERS, "true");

See Also

For more information, see:

"jdbc.bind-parameters"
"jdbc.batch-writing.size"
"Parameterized SQL and Statement Caching" in Solutions Guide for EclispeLink

jdbc.cache-statement

Specify if the query caches its JDBC statement.

Values

Table 4-15 describes this query hint's values.

Table 4-15 Valid Values for jdbc.cache-statement

Value	Description
`true`	The query will cache its JDBC statement.
`false`	(Default)

Usage

This allows queries to use parameterized SQL with statement caching. It also allows a specific query to not cache its statement, if statement caching is enable for the persistence unit.

Tip:

Normally, you should set statement caching for the entire persistence unit (see "jdbc.cache-statements") instead of each query.

When using a DataSource, you must set statement caching in the DataSource configuration.

Examples

Example 4-32 shows how to use this hint in a JPA query.

Example 4-32 Using jdbc.cache-statement in a JPA Query

import org.eclipse.persistence.config.HintValues;
 import org.eclipse.persistence.config.QueryHints;
 query.setHint("eclipselink.CACHE_STATEMENT", "TRUE");

Example 4-33 shows how to use this hint in the @QueryHint annotation.

Example 4-33 Using jdbc.cache-statement in a @QueryHint Annotation

import org.eclipse.persistence.config.HintValues;
 import org.eclipse.persistence.config.QueryHints;
 @QueryHint(name=QueryHints.CACHE_STATEMENT, value="TRUE");

See Also

For more information, see:

"jdbc.cache-statements"
"Enhancing Performance" in Solutions Guide for EclispeLink

jdbc.fetch-size

Use eclipselink.jdbc.fetch-size to specify the number of rows to be fetched from the database when additional rows are needed.

Note:

This property requires JDBC driver support.

Values

Table 4-16 describes this query hint's valid values.

Table 4-16 Valid Values for eclipselink.jdbc.fetch-size

Value Description

Value	Description
from `0` to `Integer.MAX_VALUE`	(Default = `0`) As a `String`, depending on your JDBC driver. If 0, the JDBC driver default will be used.

from 0 to Integer.MAX_VALUE

(Default = 0) As a String, depending on your JDBC driver.

If 0, the JDBC driver default will be used.

Usage

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

By default, most JDBC drivers use 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.

If you are unsure of the result set size, incorrectly setting a fetch size too large or too small can decrease performance.

Examples

Example 4-34 shows how to use this hint in a JPA query.

Example 4-34 Using jdbc.fetch-size in a JPA Query

import org.eclipse.persistence.config.HintValues;
 import org.eclipse.persistence.config.QueryHints;
 query.setHint("eclipselink.JDBC_FETCH_SIZE", "100");

Example 4-35 shows how to use this hint with the @QueryHint annotation.

Example 4-35 Using jdbc.fetch-size in a @QueryHint Annotation

import org.eclipse.persistence.config.HintValues;
 import org.eclipse.persistence.config.QueryHints;
 @QueryHint(name=QueryHints.JDBC_FETCH_SIZE, value="100");

See Also

For more information, see:

"EclipseLink" JPA Query Hints http://wiki.eclipse.org/EclipseLink/UserGuide/JPA/Basic_JPA_Development/Querying/Query_Hints
"Querying" and "Enhancing Performance" in Solutions Guide for EclispeLink
"EclipseLink Caches" in Understanding EclipseLink

jdbc.first-result

Use eclipselink.jdbc.first-result to specify if the query should skip the specified number of rows in the result.

Values

Table 4-17 describes this query hint's values.

Table 4-17 Valid Values for jdbc.first-result

Value Description

Value	Description
Integer	`Integer` or `String` value that can be parsed to an `int` value. The position of the first result to retrieve.

Integer

Integer or String value that can be parsed to an int value.

The position of the first result to retrieve.

Usage

This query hint is similar to JPA Query setFirstResults(), but can be set in metadata for NamedQuerys.

Examples

Example 4-36 shows how to use this hint in a JPA query.

Example 4-36 Using jdbc.first-result in a JPA Query

import org.eclipse.persistence.config.HintValues;
 import org.eclipse.persistence.config.QueryHints;
 query.setHint("eclipselink.JDBC_FIRST_RESULT", "10");

See Also

For more information, see:

"Query Concepts" in Understanding EclipseLink

jdbc.max-rows

Use eclipselink.jdbc.max-rows to specify the maximum number of rows to be returned. If the query returns more rows than specified, the trailing rows will not be returned.

Values

Table 4-18 describes this query hint's valid values.

Table 4-18 Valid Values for eclipselink.jdbc.max-rows

Value	Description
`Int` or `String` (that can be parsed to `Int` values)	Configures the JDBC maximum number of rows.

Usage

This hint is similar to JPQL setMaxResults(), but can be specified within the metadata for NamedQueries.

Examples

Example 4-37 shows how to use this hint in a JPA query.

Example 4-37 Using jdbc.max-rows in a JPA Query

import org.eclipse.persistence.config.HintValues;
 import org.eclipse.persistence.config.QueryHints;
 query.setHint("eclipselink.JDBC_MAX_ROWS", "100");

Example 4-38 shows how to use this hint with the @QueryHint annotation.

Example 4-38 Using jdbc.max-rows in a @QueryHint Annotation

import org.eclipse.persistence.config.HintValues;
 import org.eclipse.persistence.config.QueryHints;
 @QueryHint(name=QueryHints.JDBC_MAX_ROWS, value="100");

See Also

For more information, see:

EclipseLink Pagination Example http://wiki.eclipse.org/EclipseLink/Examples/JPA/Pagination
"Query Concepts" in Understanding EclipseLink

jdbc.native-connection

Use eclipselink.jdbc.native-connection to specify if the query requires a native JDBC connection.

Values

Table 4-19 describes this persistence property's values.

Table 4-19 Valid Values for jdbc.native-connection

Value	Description
`true`	Require native connection.
`false`	(Default) Do not require native connection.

Usage

This may be required for some queries on some server platforms that have DataSource implementations that wrap the JDBC connection in their own proxy. If the query requires custom JDBC access, it may require a native connection.

A ServerPlatform is required to be set as a persistence property to be able to use a native connection. For features that EclipseLink already knows require a native connection, eclipselink.jdbc.native-connection will default to true.

Examples

Example 4-39 shows how to use the hint in a JPA Query.

Example 4-39 Using jdbc.native-connection in a JPA Query

import org.eclipse.persistence.config.HintValues;
 import org.eclipse.persistence.config.QueryHints;
 query.setHint("eclipselink.NATIVE_CONNECTION", "TRUE");

See Also

For more information, see:

"target-server"

jdbc.parameter-delimiter

Use eclipselink.jdbc.parameter-delimiter to specify a custom parameter binding character (instead of the default hash # character).

Values

Table 4-20 describes this query hint's values.

Table 4-20 Valid Values for jdbc.parameter-delimiter

Value	Description
Character	Any valid, single character. Do not use "".

Examples

Example 4-40 shows how to use this hint in a JPA query.

Example 4-40 Using jdbc.parameter-delimiter in a JPA Query

import org.eclipse.persistence.config.HintValues;
 import org.eclipse.persistence.config.QueryHints;
 query.setHint("eclipselink.PARAMETER_DELIMITER", ",");

Example 4-41 shows how to use this hint with the @QueryHint annotation.

Example 4-41 Using jdbc.parameter-delimiter in a @QueryHint Annotation

import org.eclipse.persistence.config.HintValues;
 import org.eclipse.persistence.config.QueryHints;
 @QueryHint(name=QueryHints.PARAMETER_DELIMITER, value=",");

See Also

For more information, see:

"jdbc.bind-parameters"

jdbc.timeout

Use eclipselink.jdbc.timeout to specify number of seconds EclipseLink will wait (time out) for a query result, before throwing a DatabaseExcpetion.

Note:

This property requires JDBC driver support.

Values

Table 4-21 describes this query hint's valid values.

Table 4-21 Valid Values for eclipselink.jdbc.timeout

Value Description

Value	Description
from `0` to `Integer.MAX_VALUE`	(Default = `0`) As a `String`, depending on your JDBC driver. If 0, EclipseLink will never time out waiting for a query.

from 0 to Integer.MAX_VALUE

(Default = 0) As a String, depending on your JDBC driver.

If 0, EclipseLink will never time out waiting for a query.

Usage

Some database platforms may not support lock timeouts, so you may consider setting a JDBC_TIMEOUT hint for these platforms.

Examples

Example 4-42 shows how to use this hint in a JPA query.

Example 4-42 Using jdbc.timeout in a JPA Query

import org.eclipse.persistence.config.CacheUsage;
 import org.eclipse.persistence.config.QueryHints;
 query.setHint(QueryHints.JDBC_TIMEOUT, "100");

Example 4-43 shows how to use this hint with the @QueryHint annotation.

Example 4-43 Using jdbc.timeout in a @QueryHint Annotation

import org.eclipse.persistence.config.CacheUsage;
 import org.eclipse.persistence.config.TargetDatabase;
 @QueryHint(name=QueryHints.JDBC_TIMEOUT, value="100");

See Also

For more information, see:

"query-type"
"About JPA Query Hints" in Understanding EclipseLink
"Enhancing Performance" in Solutions Guide for EclispeLink

join-fetch

Use eclipselink.join-fetch hint to join attributes in a query.

Note:

Use dot notation to access nested attributes. For example, to batch-read an employee's manager's address, use e.manager.address.

Values

Table 4-22 describes this query hint's valid values.

Table 4-22 Valid Values for eclipselink.join-fetch hint

Value
A relationship path expression

Usage

This hint is similar to eclipselink.batch. Subsequent queries of related objects can be optimized in batches instead of being retrieved in one large joined read

The eclipselink.join-fetch hint differs from JPQL joining in that it allows multilevel fetch joins.

Examples

Example 4-44 shows how to use this hint in a JPA query.

Example 4-44 Using join-fetch in a JPA Query

import org.eclipse.persistence.config.HintValues;
 import org.eclipse.persistence.config.QueryHints;
 query.setHint("eclipselink.join-fetch", "e.address");

Example 4-45 shows how to use this hint with the @QueryHint annotation.

Example 4-45 Using join-fetch in a @QueryHint Annotation

import org.eclipse.persistence.config.HintValues;
 import org.eclipse.persistence.config.QueryHints;
 @QueryHint(name=QueryHints.FETCH, value="e.address");

See Also

For more information, see:

"EclipseLink" JPA Query Hints http://wiki.eclipse.org/EclipseLink/UserGuide/JPA/Basic_JPA_Development/Querying/Query_Hints
EclipseLink Examples http://wiki.eclipse.org/EclipseLink/Examples/JPA/QueryOptimization
"Optimizing Queries" in Understanding EclipseLink.
"Fetch Joins" in the JPA Specification (http://jcp.org/en/jsr/detail?id=317)
"batch"
"left-join-fetch"
"Enhancing Performance" in Solutions Guide for EclispeLink

left-join-fetch

Use eclipselink.left-join-fetch to optimize the query: related objects will be joined into the query instead of being queries separately.

Values

Table 4-23 describes this query hint's values.

Table 4-23 Valid Values for left-join-fetch

Value	Description
String	JPQL-style navigations to a relationship

Usage

You can use this query hint to create nested join fetches, which is not supported by JPQL. You can also use eclipselink.left-join-fetch to create join fetches with native queries.

Note:

This uses an OUTER join to allow null or empty values.

Examples

Example 4-46 shows how to use this hint in a JPA query.

Example 4-46 Using left-join-fetch in a JPA Query

import org.eclipse.persistence.config.HintValues;
 import org.eclipse.persistence.config.QueryHints;
 query.setHint("eclipselink.LEFT_FETCH", "STRING");

Example 4-47 shows how to use this hint with the @QueryHint annotation.

Example 4-47 Using left-join-fetch in a @QueryHint Annotation

import org.eclipse.persistence.config.HintValues;
 import org.eclipse.persistence.config.QueryHints;
 @QueryHint(name=QueryHints.LEFT_FETCH, value="STRING");

See Also

EclipseLink Examples http://wiki.eclipse.org/EclipseLink/Examples/JPA/QueryOptimization
"Fetch Joins" in the JPA Specification (http://jcp.org/en/jsr/detail?id=317)
"batch"
"join-fetch"
"Enhancing Performance" in Solutions Guide for EclispeLink

load-group

Use eclipselink.load-group to configures a query to use the load group object.

Values

Table 4-24 describes this persistence property's values.

Table 4-24 Valid Values for load-group

Value	Description
`load-group` classname	An instance of `LoadGroup`.

Usage

With load groups, EclipseLink ensures that all relational attributes for a group are loaded. LoadGroups are only supported for queries returning objects (only a single alias can be the select clause).

Examples

Example 4-48 shows how to use this hint in a JPA query.

Example 4-48 Using load-group in a JPA Query

import org.eclipse.persistence.config.HintValues;
 import org.eclipse.persistence.config.QueryHints;
 query.setHint("eclipselink.LOAD_GROUP", MyLoadGroup);

Example 4-49 shows how to use this hint with the @QueryHint annotation.

Example 4-49 Using load-group in a @QueryHint Annotation

import org.eclipse.persistence.config.HintValues;
 import org.eclipse.persistence.config.QueryHints;
 @QueryHint(name=QueryHints.LOAD_GROUP, value="lg");

See Also

For more information, see:

"load-group.attribute"
"AttributeGroup Types and Operations" in Understanding EclipseLink
EclipseLink Attribute Group example:http://wiki.eclipse.org/EclipseLink/Examples/JPA/AttributeGroup
"@FetchGroup"

load-group.attribute

Use eclipselink.load-group.attribute to specify if the query uses a load-group that includes a list of attributes.

Usage

You must define each attribute using a separate hint. The query loads all relational attributes defined in the load group.

LoadGroups are only supported for queries returning objects (only a single alias can be the select clause). Both local and nested attributes are supported.

See Also

For more information, see:

"load-group"

maintain-cache

Use eclipselink.maintain-cache to controls whether or not query results are cached in the session cache

Values

Table 4-25 describes this query hint's valid values.

Table 4-25 Valid Values for org.eclipselink.maintain-cache

Value	Description
`TRUE`	Maintain cache.
`FALSE`	(Default) Do not maintain cache.

Usage

The eclipselink.maintain-cache hint provides a way to query the current database contents without affecting the current persistence context. It configures the query to return un-managed instances so any updates to entities queried using this hint would have to be merged into the persistence context.

Examples

Example 4-50 shows how to use this hint in a JPA query.

Example 4-50 Using maintain-cache in a JPA Query

import org.eclipse.persistence.config.HintValues;
 import org.eclipse.persistence.config.QueryHints;
 query.setHint(QueryHints.MAINTAIN_CACHE, HintValues.FALSE);

Example 4-51 shows how to use this hint with the @QueryHint annotation.

Example 4-51 Using maintain-cache in a @QueryHint Annotation

import org.eclipse.persistence.config.HintValues;
 import org.eclipse.persistence.config.QueryHints;
 @QueryHint(name=QueryHints.MAINTAIN_CACHE, value=HintValues.FALSE);

See Also

For more information, see:

"Scaling EclipseLink Applications in Clusters" in Solutions Guide for EclispeLink
"Enhancing Performance" in Solutions Guide for EclispeLink
"EclipseLink Caches" in Understanding EclipseLink

pessimistic-lock

Use eclipselink.pessimistic-lock to specify if EclipseLink uses pessimistic locking.

Values

Table 4-26 describes this query hint's valid values.

Table 4-26 Valid Values for org.eclipse.persistence.config.PessimisticLock

Value	Description
`NoLock`	(Default) Do not use pessimistic locking.
`Lock`	EclipseLink issues `SELECT .... FOR UPDATE` statements.
`LockNoWait`	EclipseLink issues `SELECT .... FOR UPDATE NO WAIT` statements.

Usage

The primary advantage of using pessimistic locking is that you are assured, once the lock is obtained, of a successful edit. This is desirable in highly concurrent applications in which optimistic locking may cause too many optimistic locking errors.

One drawback of pessimistic locking is that it requires additional database resources, requiring the database transaction and connection to be maintained for the duration of the edit. Pessimistic locking may also cause deadlocks and lead to concurrency issues.

Examples

Example 4-52 shows how to use this hint in a JPA query.

Example 4-52 Using pessimistic-lock in a JPA Query

import org.eclipse.persistence.config.PessimisticLock;
 import org.eclipse.persistence.config.QueryHints;
 query.setHint(QueryHints.PESSIMISTIC_LOCK, PessimisticLock.LockNoWait);

Example 4-53 shows how to use this hint with the @QueryHint annotation.

Example 4-53 Using pessimistic-lock in a @QueryHint Annotation

import org.eclipse.persistence.config.PessimisticLock;
 import org.eclipse.persistence.config.QueryHints;
 @QueryHint(name=QueryHints.PESSIMISTIC_LOCK, value=PessimisticLock.LockNoWait);

See Also

For more information, see:

EclipseLink Examples http://wiki.eclipse.org/EclipseLink/Examples/JPA/PessimisticLocking
"Scaling EclipseLink Applications in Clusters" in Solutions Guide for EclispeLink
"Understanding Queries" in Understanding EclipseLink
"Building Blocks of a EclipseLink Project" in Understanding EclipseLink

prepare

Use eclipselink.prepare to specify if a query prepares (that is, generates) its SQL for each execution.

Values

Table 4-27 describes this query hint's values.

Table 4-27 Valid Values for prepare

Value	Description
true	Generate the SQL each time EclipseLink executes the query.
`false`	(Default) Generate the SQL only the first time EclipseLink executes the query.

Usage

By default, EclipseLink does not re-generate the SQL for each execution. This may improve performance.

For queries that require dynamic SQL (for example, to handle null parameters) set eclipselink.prepare to false.

Examples

Example 4-54 shows how to use this hint in a JPA query.

Example 4-54 Using prepare in a JPA Query

import org.eclipse.persistence.config.HintValues;
 import org.eclipse.persistence.config.QueryHints;
 query.setHint("eclipselink.PREPARE", "TRUE");

Example 4-55 shows how to use this hint with the @QueryHint annotation.

Example 4-55 Using prepare in a @QueryHint Annotation

import org.eclipse.persistence.config.HintValues;
 import org.eclipse.persistence.config.QueryHints;
 @QueryHint(name=QueryHints.PREPARE, value="TRUE");

See Also

For more information, see:

"Understanding Queries" in Understanding EclipseLink

query-results-cache

Use eclipselink.query-results-cache to specify that the query should use a results cache.

Values

Table 4-28 describes this persistence property's values.

Table 4-28 Valid Values for query-results-cache

Value	Description
`Persistence_Unit_Default`	(Default)
`True`	Query results are cache.
`False`	Query results are not cached.

Usage

By default, the query will cache 100 query results (see query-results-cache.size); if the same named query with the same arguments is re-executed EclipseLink will skip the database and return the cached results.

Note:

The query cache is different and independent from the object cache.

Examples

Example 4-56 shows how to use this hint in a JPA query.

Example 4-56 Using query-results-cache in a JPA Query

import org.eclipse.persistence.config.HintValues;
 import org.eclipse.persistence.config.QueryHints;
 query.setHint("eclipselink.QUERY_RESULTS_CACHE", "TRUE");

Example 4-57 shows how to use this hint with the @QueryHint annotation.

Example 4-57 Using query-results-cache in a @QueryHint Annotation

import org.eclipse.persistence.config.HintValues;
 import org.eclipse.persistence.config.QueryHints;
 @QueryHint(name=QueryHints.QUERY_RESULTS_CACHE, value="TRUE");

Example 4-58 shows how to use this hint in an orm.xml file.

Example 4-58 Using query-results-cache in orm.xml File

<?xml version="1.0"?>
<entity-mappings
    xmlns="http://www.eclipse.org/eclipselink/xsds/persistence/orm"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://www.eclipse.org/eclipselink/xsds/persistence/orm     http://www.eclipse.org/eclipselink/xsds/eclipselink_orm_2_4.xsd"
    version="2.4">
    <entity name="Employee" class="org.acme.Employee" access="FIELD">
        <named-query name="findAllEmployeesInCity" query="Select e from Employee e where e.address.city = :city">
            <hint name="eclipselink.query-results-cache" value="true"/>
            <hint name="eclipselink.query-results-cache.size" value="500"/>
        </named-query>
        ...
    </entity>
</entity-mappings>

See Also

For more information, see:

"About Query Results Cache" in Understanding EclipseLink

query-results-cache.expiry

Use eclipselink.query-results-cache.expiry to set the time-to-live (that is, expiration time) of the query's results cache.

Values

Table 4-29 describes this query hint's values.

Table 4-29 Valid Values for query-results-cache.expiry

Value	Description
Value	Number of milliseconds, as `Integer` or `Strings` that can be parsed to `int` values.

Usage

By default the query results cache will not expiry results.

Examples

Example 4-59 shows how to use this hint in a JPA query.

Example 4-59 Using query-results-cache.expiry in a JPA Query

import org.eclipse.persistence.config.HintValues;
 import org.eclipse.persistence.config.QueryHints;
 query.setHint("eclipselink.QUERY_RESULTS_CACHE_EXPIRY", "100");

Example 4-60 shows how to use this hint with the @QueryHint annotation.

Example 4-60 Using query-results-cache.expiry in a @QueryHint Annotation

import org.eclipse.persistence.config.HintValues;
 import org.eclipse.persistence.config.QueryHints;
 @QueryHint(name=QueryHints.QUERY_RESULTS_CACHE_EXPIRY, value="100");

See Also

For more information, see:

"query-results-cache"

query-results-cache.expiry-time-of-day

Use eclipselink.query-results-cache.expiry-time-of-day to set the time of day of the query's results cache expiration.

Values

Table 4-30 describes this persistence property's values.

Table 4-30 Valid Values for query-results-cache.expiry-time-of-day

Value	Description
Value	Time, in HH:MM:SS format, as a `String`

Usage

By default the query results cache will not expiry results.

Examples

Example 4-61 shows how to use this hint in a JPA query.

Example 4-61 Using query-results-cache.expiry-time-of-day in a JPA Query

import org.eclipse.persistence.config.HintValues;
 import org.eclipse.persistence.config.QueryHints;
 query.setHint("eclipselink.QUERY_RESULTS_CACHE_EXPIRY_TIME_OF_DAY", "11:15:34");

Example 4-62 shows how to use this hint with the @QueryHint annotation.

Example 4-62 Using query-results-cache.expiry-time-of-day in a @QueryHint Annotation

import org.eclipse.persistence.config.HintValues;
 import org.eclipse.persistence.config.QueryHints;
 @QueryHint(name=QueryHints.QUERY_RESULTS_CACHE_EXPIRY_TIME_OF_DAY, value="11:15:34");

See Also

For more information, see:

"query-results-cache"

query-results-cache.ignore-null

Use eclipselink.query-results-cache.ignore-null to specify if EclipseLink caches null query results

Values

Table 4-31 describes this query hint's values.

Table 4-31 Valid Values for query-results-cache.ignore-null

Value	Description
`true`	Ignore null results (that is, do not cache results)
`false`	(Default) Do not ignore `null` results (that is, do cache results)

Usage

You can use this query hint to use query cache as a secondary key index, and allow inserts of new objects.

Examples

Example 4-63 shows how to use this hint in a JPA query.

Example 4-63 Using query-results-cache.ignore-null in a JPA Query

import org.eclipse.persistence.config.HintValues;
 import org.eclipse.persistence.config.QueryHints;
 query.setHint("eclipselink.QUERY_RESULTS_CACHE_IGNORE_NULL", "TRUE");

Example 4-64 shows how to use this hint with the @QueryHint annotation.

Example 4-64 Using query-results-cache.ignore-null in a @QueryHint Annotation

import org.eclipse.persistence.config.HintValues;
 import org.eclipse.persistence.config.QueryHints;
 @QueryHint(name=QueryHints.QUERY_RESULTS_CACHE_IGNORE_NULL, value="TRUE");

See Also

For more information, see:

"query-results-cache"

query-results-cache.randomize-expiry

Use eclipselink.query-results-cache.randomize-expiry to specify the expiry time (query-results-cache.expiry) should be randomized by 10% of its set value.

Values

Table 4-32 describes this query hint's values.

Table 4-32 Valid Values for query-results-cache.randomize-expiry

Value	Description
`true`	Randomize the expiration time by 10%.
`false`	(Default) Do not randomize the expiration time.

Usage

Use this query hint to avoid bottlenecks from multiple cached values expiring at a fixed time.

Examples

Example 4-65 shows how to use this hint in a JPA query.

Example 4-65 Using query-results-cache.randomize-expiry in a JPA Query

import org.eclipse.persistence.config.HintValues;
 import org.eclipse.persistence.config.QueryHints;
 query.setHint("eclipselink.QUERY_RESULTS_CACHE_RANDOMIZE_EXPIRY", "TRUE");

Example 4-66 shows how to use this hint with the @QueryHint annotation.

Example 4-66 Using query-results-cache.randomize-expiry in a @QueryHint Annotation

import org.eclipse.persistence.config.HintValues;
 import org.eclipse.persistence.config.QueryHints;
 @QueryHint(name=QueryHints.QUERY_RESULTS_CACHE_RANDOMIZE_EXPIRY, value="TRUE");

See Also

For more information, see:

"query-results-cache"
"query-results-cache.expiry"

query-results-cache.size

Use eclipselink.query-results-cache.size to set the fixed size of the query's results cache.

Values

Table 4-33 describes this query hint's values.

Table 4-33 Valid Values for query-results-cache.size

Value	Description
Size	Integer or Strings that can be parsed to int values (Default: 100)

Usage

When using query-results-cache, if the same named query with the same arguments is re-executed EclipseLink will skip the database and return the cached results.

Note:

If a query has no arguments, use a size of 1 (as there is only a single result).

Examples

Example 4-67 shows how to use this hint in a JPA query.

Example 4-67 Using query-results-cache.size in a JPA Query

import org.eclipse.persistence.config.HintValues;
 import org.eclipse.persistence.config.QueryHints;
 query.setHint("eclipselink.QUERY_RESULTS_CACHE_SIZE", "150");

Example 4-68 shows how to use this hint with the @QueryHint annotation.

Example 4-68 Using query-results-cache.size in a @QueryHint Annotation

import org.eclipse.persistence.config.HintValues;
 import org.eclipse.persistence.config.QueryHints;
 @QueryHint(name=QueryHints.QUERY_RESULTS_CACHE_SIZE, value="150");

See Also

For more information, see:

"query-results-cache"

query-results-cache.type

Use eclipselink.query-results-cache.type to set the cache type used for the query's results cache.

Values

Table 4-34 describes this query hint's values.

Table 4-34 Valid Values for query-results-cache.type

Value	Description
Cache	(Default) Fixed size LRU cache (`CacheIdentityMap`)
Full	Provides full caching and guaranteed identity.
Hard_Weak	Similar to SOFT_WEAK, except that it uses hard references in the sub-cache.
None	No caching.
Soft	Similar to FULL, except the map holds the objects using soft references.
Soft_Weak	Similar to WEAK, except it maintains a most-frequently-used sub-cache.
Weak	Similar to FULL, except the map holds the objects using weak references.

Usage

Examples

Example 4-69 shows how to use this hint in a JPA query.

Example 4-69 Using query-results-cache.type in a JPA Query

import org.eclipse.persistence.config.HintValues;
 import org.eclipse.persistence.config.QueryHints;
 query.setHint("eclipselink.QUERY_RESULTS_CACHE_TYPE", "FULL");

Example 4-70 shows how to use this hint with the @QueryHint annotation.

Example 4-70 Using query-results-cache.type in a @QueryHint Annotation

import org.eclipse.persistence.config.HintValues;
 import org.eclipse.persistence.config.QueryHints;
 @QueryHint(name=QueryHints.QUERY_RESULTS_CACHE_TYPE, value="FULL");

See Also

For more information, see:

"@Cache"
"Caching Overview"http://wiki.eclipse.org/EclipseLink/UserGuide/JPA/Basic JPA Development/Caching/Caching Overview
"EclipseLink Caches" in the Understanding EclipseLink
"Scaling EclipseLink Applications in Clusters" in Solutions Guide for EclispeLink

query-type

Use eclipselink.query-type to specify which EclipseLink query type to use for the query.

Values

Table 4-35 describes this query hint's valid values.

Table 4-35 Valid Values for org.eclipse.persistence.config.QueryType

Value	Description
`Auto`	(Default = `0`) EclipseLink chooses the type of query.
`ReadAll`	Use a `ReadAllQuery`.
`ReadObject`	Use a `ReadObjectQuery`.
`Report`	Use a `ReportQuery`.

Usage

By default, EclipseLink uses org.eclipse.persistence.queries.ReportQuery or org.eclipse.persistence.queries.ReadAllQuery for most JPQL queries. Use the eclipselink.query-type hint lets to specify another query type, such as org.eclipse.persistence.queries.ReadObjectQuery for queries that will return a single object.

Examples

Example 4-71 shows how to use this hint in a JPA query.

Example 4-71 Using query-type in a JPA Query

import org.eclipse.persistence.config.QueryType;
 import org.eclipse.persistence.config.QueryHints;
 query.setHint(QueryHints.QUERY_TYPE, QueryType.ReadObject);

Example 4-72 shows how to use this hint with the @QueryHint annotation.

Example 4-72 Using query-type in a @QueryHint Annotation

import org.eclipse.persistence.config.QueryType;
 import org.eclipse.persistence.config.TargetDatabase;
 @QueryHint(name=QueryHints.QUERY_TYPE, value=QueryType.ReadObject);

See Also

For more information, see:

"Queries" in Understanding EclipseLink

read-only

Use eclipselink.read-only to retrieve read-only results back from a query.

Values

Table 4-36 describes this query hint's valid values.

Table 4-36 Valid Values for read-only

Value	Description
`TRUE`	Retrieve read-only results from the query.
`FALSE`	(Default) Do not retrieve read-only results from the query.

Usage

For non-transactional read operations, if the requested entity types are stored in the shared cache you can request that the shared instance be returned instead of a detached copy.

Note:

You should never modify objects returned from the shared cache.

Examples

Example 4-73 shows how to use this hint in a JPA query.

Example 4-73 Using read-only in a JPA Query

import org.eclipse.persistence.config.HintValues;
 import org.eclipse.persistence.config.QueryHints;
 query.setHint(QueryHints.READ_ONLY, HintValues.TRUE);

Example 4-74 shows how to use this hint with the @QueryHint annotation.

Example 4-74 Using read-only in a @QueryHint Annotation

import org.eclipse.persistence.config.HintValues;
 import org.eclipse.persistence.config.QueryHints;
 @QueryHint(name=QueryHints.READ_ONLY, value=HintValues.TRUE);

See Also

For more information, see:

"Oracle EclipseLink JPA Performance Tuning" in Oracle Fusion Middleware Performance and Tuning Guide

refresh

Use eclipselink.refresh to specify whether or not to update the EclipseLink session cache with objects returned by the query.

Values

Table 4-37 describes this query hint's valid values.

Table 4-37 Valid Values for eclipselink.refresh

Value	Description
`TRUE`	Refreshes the cache.
`FALSE`	(Default) Does not refresh the cache. You can use `""` instead of `FALSE`.

Usage

The eclipselink.refresh query hint configures the query to refresh the resulting objects in the cache and persistence context with the current state of the database. It also refreshes the objects in the shared cache, unless a flush has occurred. Any unflushed changes made to the objects are lost, unless this query triggers a flush before it executes). The refresh will cascade relationships based on the REFRESH_CASCADE hint value.

Examples

Example 4-75 shows how to use this hint in a JPA query.

Example 4-75 Using refresh in a JPA Query

import org.eclipse.persistence.config.HintValues;
 import org.eclipse.persistence.config.QueryHints;
 query.setHint(QueryHints.REFRESH, HintValues.TRUE);

Example 4-76 shows how to use this hint with the @QueryHint annotation.

Example 4-76 Using refresh in a @QueryHint Annotation

import org.eclipse.persistence.config.HintValues;
 import org.eclipse.persistence.config.QueryHints;
 @QueryHint(name=QueryHints.REFRESH, value=HintValues.TRUE);

See Also

For more information, see:

"refresh.cascade"

refresh.cascade

Use eclipselink.refresh.cascade to specify if a refresh query should cascade the refresh to relationships.

Values

Table 4-38 describes this query hint's valid values.

Table 4-38 Valid Values for eclipselink.refresh.cascade

Value	Description
`CascadeAllParts`	Cascade to all associations.
`CascadeByMapping`	Cascade by mapping metadata.
`CascadePrivateParts`	Cascade to privately-owned relationships.
`NoCascade`	Do not cascade.

Usage

You should also use a refresh hint in order to cause the refresh.

Examples

Example 4-77 shows how to use this hint in a JPA query.

Example 4-77 Using refresh.cascade in a JPA Query

import org.eclipse.persistence.config.HintValues
 import oorg.eclipse.persistence.config.QueryHints;
 query.setHint(QueryHints.REFRESH_CASCADE, CascadePolicy.CascadeAllParts);

Example 4-78 shows how to use this hint with the @QueryHint annotation.

Example 4-78 Using refresh.cascade in a @QueryHint Annotation

import org.eclipse.persistence.config.HintValues;
 import org.eclipse.persistence.config.QueryHints;
 @QueryHint(name=QueryHints.REFRESH_CASCADE, value=CascadePolicy.CascadeAllParts);

See Also

For more information, see:

"refresh"

result-collection-type

Use eclipselink.result-collection-type to configure the collection class implementation for the query's results.

Values

Table 4-39 describes this query hint's values.

Table 4-39 Valid Values for result-collection-type

Value	Description
`true`	Fully qualified class name, without `.class`, representing a collection type.
`false`	(Default) Do not ignore `null` results (that is, do cache results)

Usage

If you use a Collection type that is not a List, you must use getResultCollection() or getSingleResult() instead of getResultList().

Examples

Example 4-79 show how to use this hint in a JPA query.

Example 4-79 Using result-collection-type in a JPA Query

import org.eclipse.persistence.config.HintValues;
 import org.eclipse.persistence.config.QueryHints;
 query.setHint("eclipselink.RESULT_COLLECTION_TYPE", "<CLASS_NAME>");

Example 4-80 shows how to use this hint with the @QueryHint annotation.

Example 4-80 Using result-collection-type in a @QueryHint Annotation

import org.eclipse.persistence.config.HintValues;
 import org.eclipse.persistence.config.QueryHints;
 @QueryHint(name=QueryHints.RESULT_COLLECTION_TYPE, value="<CLASS_NAME>");

See Also

For more information, see:

"Collection Mappings" in the Understanding EclipseLink

sql.hint

Use eclipselink.sql.hint to include an SQL hint in the SQL for a query.

Values

Table 4-40 describes this query hint's values.

Table 4-40 Valid Values for sql.hint

Value	Description
value	The full hint string, including the comment \ delimiters

Usage

A SQL hint can be used on certain database platforms to define how the query uses indexes and other such low level usages. The SQL hint will be included in the SQL, after the SELECT/INSERT/UPDATE/DELETE command.

Examples

Example 4-81 shows how to use this hint in a JPA query.

Example 4-81 Using sql.hint in a JPA Query

import org.eclipse.persistence.config.HintValues;
import org.eclipse.persistence.config.QueryHints;
query.setHint("eclipselink.HINT", "/*+ index(scott.emp ix_emp) * /");

Example 4-82 shows how to use this hint with the @QueryHint annotation.

Example 4-82 Using sql.hint in a @QueryHint Annotation

import org.eclipse.persistence.config.HintValues;
import org.eclipse.persistence.config.QueryHints;
@QueryHint(name=QueryHints.HINT, value="/*+ index(scott.emp ix_emp) * /");

See Also

For more information, see:

"Query Hints" in Understanding EclipseLink
"Query" in Solutions Guide for EclispeLink
Section 10.3.1 "NamedQuery Annotation" in the JPA Specification (http://jcp.org/en/jsr/detail?id=317)