Jakarta Persistence API (JPA) Extensions Reference for EclipseLink, Release 3.0
  Go To Table Of Contents
 Search
 PDFComments
Comments

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:

EclipseLink supplies the following query hints:

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:

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.


NoteNote:

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:


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.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 Jakarta 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:


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:


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:


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


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:


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:


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.


NoteNote:

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

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


NoteNote:

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:


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").


NoteNote:

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:


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.JDBC_BIND_PARAMETERS, "true");


See Also

For more information, see:


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.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.fetch-size

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


NoteNote:

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

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:


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

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:


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:


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:


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

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


NoteNote:

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

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:


join-fetch

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


NoteNote:

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:


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.


NoteNote:

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


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

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:


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:


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:


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:


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.


NoteNote:

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:


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


NoteNote:

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


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:


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.


NoteNote:

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:


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

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:


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:


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: