org.eclipse.persistence.config

Class QueryHints

java.lang.Object

org.eclipse.persistence.config.QueryHints

Direct Known Subclasses:

QueryParameters

public class QueryHints
extends java.lang.Object

The class defines EclipseLink query hints. These query hints allow a JPA Query to be customized or optimized beyond what is available in the JPA specification.

JPA Query Hint Usage:

query.setHint(QueryHints.CACHE_USAGE, CacheUsage.CheckCacheOnly);

or

@QueryHint(name=QueryHints.CACHE_USAGE, value=CacheUsage.CheckCacheOnly)

Hint values are case-insensitive; "" could be used instead of default value.

See Also:

HintValues, CacheUsage, PessimisticLock, QueryType

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	ALLOW_NATIVE_SQL_QUERY The "eclipselink.jdbc.allow-native-sql-query" property specifies whether a single native SQL query should override a persistence unit level setting (eclipselink.jdbc.allow-native-sql-queries).
static java.lang.String	AS_OF "eclipselink.history.as-of" Configures the query to query the state of the object as-of a point in time.
static java.lang.String	AS_OF_SCN "eclipselink.history.as-of.scn" Configures the query to query the state of the object as-of a database SCN (System Change Number).
static java.lang.String	BATCH "eclipselink.batch" Configures the query to optimize the retrieval of the related objects, the related objects for all the resulting objects will be read in a single query (instead of n queries).
static java.lang.String	BATCH_SIZE "eclipselink.batch.size" Configures the batch size for batch fetching using the IN batch type.
static java.lang.String	BATCH_TYPE "eclipselink.batch.type" Configures the type of batch fetching to use for any batch fetched relationships on the query.
static java.lang.String	BATCH_WRITING "eclipselink.jdbc.batch-writing" Configures if this modify query can be batched through batch writing.
static java.lang.String	BIND_PARAMETERS "eclipselink.jdbc.bind-parameters" Configures parameter binding to be disabled or enabled just for this query (overrides persistent unit setting, which default to true).
static java.lang.String	CACHE_RETRIEVE_MODE "javax.persistence.cache.retrieveMode" Configures the behavior when data is retrieved by the find methods and by the execution of queries.
static java.lang.String	CACHE_STATMENT "eclipselink.jdbc.cache-statement" Configures if the query will cache its JDBC statement.
static java.lang.String	CACHE_STORE_MODE "javax.persistence.cache.storeMode" Configures the behavior when data is read from the database and when data is committed into the database.
static java.lang.String	CACHE_USAGE "eclipselink.cache-usage" Configures the query to utilize the EclipseLink cache, by default the cache is not checked on queries before accessing the database.
static java.lang.String	COMPOSITE_UNIT_MEMBER "eclipselink.composite-unit.member" This must be used on a native query executed on composite persistence unit.
static java.lang.String	CURSOR "eclipselink.cursor" Configures the query to return a CursoredStream.
static java.lang.String	CURSOR_INITIAL_SIZE "eclipselink.cursor.initial-size" Configures the query to return a CursoredStream with the initial threshold size.
static java.lang.String	CURSOR_PAGE_SIZE "eclipselink.cursor.page-size" Configures the query to return a CursoredStream with the page size.
static java.lang.String	CURSOR_SIZE "eclipselink.cursor.size-sql" Configures the SQL string for the size query of a Cursor query.
static java.lang.String	EXCLUSIVE_CONNECTION "eclipselink.exclusive-connection" Configures the query to use the exclusive (transactional/write) connection.
static java.lang.String	FETCH "eclipselink.join-fetch" Configures the query to optimize the retrieval of the related objects, the related objects will be joined into the query instead of being queried independently.
static java.lang.String	FETCH_GROUP "eclipselink.fetch-group" Configures the query to use the fetch group object.
static java.lang.String	FETCH_GROUP_ATTRIBUTE "eclipselink.fetch-group.attribute" Configures the query to use a dynamic fetch group that includes a list of attributes.
static java.lang.String	FETCH_GROUP_DEFAULT "eclipselink.fetch-group.default" Configures the query not to use the default fetch group.
static java.lang.String	FETCH_GROUP_LOAD "eclipselink.fetch-group.load" Configures a dynamic fetch group to load (default) or not to load its attributes.
static java.lang.String	FETCH_GROUP_NAME "eclipselink.fetch-group.name" Configures the query to use a named fetch group defined for the result class.
static java.lang.String	FLUSH "eclipselink.flush" Configures if the query should trigger a flush of the persistence context before execution.
static java.lang.String	HINT "eclipselink.sql.hint" Sets a SQL hint string into the query that will be generated into the SQL statement after the SELECT/INSERT/UPDATE/DELETE command.
static java.lang.String	INDIRECTION_POLICY "eclipselink.cache-usage.indirection-policy" This can be used on a query with a CACHE_USAGE hint to configure the behavior of in-memory querying and conforming's treatment of uninstantiated indirection/lazy relationships.
static java.lang.String	INHERITANCE_OUTER_JOIN "eclipselink.inheritance.outer-join" Configures the query to outer-join all subclasses.
static java.lang.String	JDBC_FETCH_SIZE "eclipselink.jdbc.fetch-size" Configures the JDBC fetch-size for the queries result-set.
static java.lang.String	JDBC_FIRST_RESULT "eclipselink.jdbc.first-result" Configures the query to skip the firstResult number of rows.
static java.lang.String	JDBC_MAX_ROWS "eclipselink.jdbc.max-rows" Configures the JDBC max-rows, if the query returns more rows than the max-rows the trailing rows will not be returned by the database.
static java.lang.String	JDBC_TIMEOUT "eclipselink.jdbc.timeout" Configures the JDBC timeout of the query execution, if the database query exceeds the timeout the database will terminate the query and return an exception.
static java.lang.String	JPA_FETCH_GRAPH "javax.persistence.fetchgraph" Configures a jpa entity graph to be used as a fetch graph template.
static java.lang.String	JPA_LOAD_GRAPH "javax.persistence.loadgraph" Configures a jpa entity graph to be used as a load graph template.
static java.lang.String	LEFT_FETCH "eclipselink.left-join-fetch" Configures the query to optimize the retrieval of the related objects, the related objects will be joined into the query instead of being queried independently.
static java.lang.String	LOAD_GROUP "eclipselink.load-group" Configures the query to use the load group object.
static java.lang.String	LOAD_GROUP_ATTRIBUTE "eclipselink.load-group.attribute" Configures the query to use load group that includes a list of attributes.
static java.lang.String	MAINTAIN_CACHE "eclipselink.maintain-cache" Configures the query to not use both the shared cache, and the transactional cache/persistence context.
static java.lang.String	NATIVE_CONNECTION "eclipselink.jdbc.native-connection" Configures if the query requires a native JDBC connection.
static java.lang.String	PARAMETER_DELIMITER "eclipselink.jdbc.parameter-delimiter" Configures parameter binding char to a user defined character (overrides default hash symbol).
static java.lang.String	PARTITIONING "eclipselink.partitioning" Used to provide a PartitioningPolicy instance or name to the query.
static java.lang.String	PESSIMISTIC_LOCK "eclipselink.pessimistic-lock" Configures the query to acquire a pessimistic lock (write-lock) on the resulting rows in the database.
static java.lang.String	PESSIMISTIC_LOCK_SCOPE "javax.persistence.lock.scope" By default pessimistic lock applied to only the tables mapped to the object being locked.
static java.lang.String	PESSIMISTIC_LOCK_TIMEOUT "javax.persistence.lock.timeout" Configures the WAIT timeout used in pessimistic locking, if the database query exceeds the timeout the database will terminate the query and return an exception.
static java.lang.String	PREPARE "eclipselink.prepare" Configures the query to not prepare its SQL.
static java.lang.String	QUERY_REDIRECTOR "eclipselink.query.redirector" Used to provide a QueryRedirector to the executing query.
static java.lang.String	QUERY_RESULTS_CACHE "eclipselink.query-results-cache" Configures the query to use a results cache.
static java.lang.String	QUERY_RESULTS_CACHE_EXPIRY "eclipselink.query-results-cache.expiry" Configures the time to live, or expiry time of the query's results cache.
static java.lang.String	QUERY_RESULTS_CACHE_EXPIRY_TIME_OF_DAY "eclipselink.query-results-cache.expiry-time-of-day" Configures the time of day expiry time of the query's results cache.
static java.lang.String	QUERY_RESULTS_CACHE_IGNORE_NULL "eclipselink.query-results-cache.ignore-null" Configures null results to not be cached.
static java.lang.String	QUERY_RESULTS_CACHE_RANDOMIZE_EXPIRY "eclipselink.query-results-cache.randomize-expiry" Configures a randomization on the expiry invalidation time.
static java.lang.String	QUERY_RESULTS_CACHE_SIZE "eclipselink.query-results-cache.size" Configures the size of the query's results cache.
static java.lang.String	QUERY_RESULTS_CACHE_TYPE "eclipselink.query-results-cache.type" Configures the cache type of the query's results cache.
static java.lang.String	QUERY_TYPE "eclipselink.query-type" Configures the EclipseLink query type to use for the query.
static java.lang.String	READ_ONLY "eclipselink.read-only" Configures the query to return shared (read-only) objects from the cache, instead of objects registered with the persistence context.
static java.lang.String	REFRESH "eclipselink.refresh" Configures the query to refresh the resulting objects in the cache and persistent context with the current state of the database.
static java.lang.String	REFRESH_CASCADE "eclipselink.refresh.cascade" Defines if a refresh query should cascade the refresh to relationships.
static java.lang.String	RESULT_COLLECTION_TYPE "eclipselink.result-collection-type" Configures the collection class implementation for the queries result.
static java.lang.String	RESULT_SET_ACCESS "eclipselink.result-set-access" Configures if this read object(s) query should keep result set until all result object(s) are built.
static java.lang.String	RESULT_SET_CONCURRENCY "eclipselink.cursor.scrollable.result-set-concurrency" This can be used on ScrollableCursor queries to set the JDBC ResultSet concurrency.
static java.lang.String	RESULT_SET_TYPE "eclipselink.cursor.scrollable.result-set-type" This can be used on ScrollableCursor queries to set the JDBC ResultSet scroll type.
static java.lang.String	RESULT_TYPE "eclipselink.result-type" By default in JPA for non-single select queries an Array of values is returned.
static java.lang.String	RETURN_NAME_VALUE_PAIRS "eclipselink.query-return-name-value-pairs" Configures a ResultSetMappingQuery to return populated DatabaseRecord(s) instead of raw data.
static java.lang.String	SCROLLABLE_CURSOR "eclipselink.cursor.scrollable" Configures the query to return a ScrollableCursor.
static java.lang.String	SERIALIZED_OBJECT "eclipselink.serialized-object" Configures if this read object(s) query use SerializedObjectPolicy if it's set on the descriptor.

Constructor Summary

Constructors

Constructor and Description
QueryHints()

Method Summary

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

BIND_PARAMETERS

public static final java.lang.String BIND_PARAMETERS

"eclipselink.jdbc.bind-parameters"

Configures parameter binding to be disabled or enabled just for this query (overrides persistent unit setting, which default to true). Valid values are: HintValues.PERSISTENCE_UNIT_DEFAULT, HintValues.TRUE, HintValues.FALSE, "" could be used instead of default value HintValues.PERSISTENCE_UNIT_DEFAULT

See Also:

PersistenceUnitProperties.JDBC_BIND_PARAMETERS, DatabaseQuery.setShouldBindAllParameters(boolean), Constant Field Values

PARAMETER_DELIMITER

public static final java.lang.String PARAMETER_DELIMITER

"eclipselink.jdbc.parameter-delimiter"

Configures parameter binding char to a user defined character (overrides default hash symbol). Valid values are: ParameterDelimiterType.DEFAULT, other valid single character, "" can not be used and will instead default to ParameterDelimiterType.DEFAULT

See Also:

PersistenceUnitProperties.JDBC_BIND_PARAMETERS, DatabaseQuery.setShouldBindAllParameters(boolean), Constant Field Values

CACHE_RETRIEVE_MODE

public static final java.lang.String CACHE_RETRIEVE_MODE

"javax.persistence.cache.retrieveMode"

Configures the behavior when data is retrieved by the find methods and by the execution of queries. The cache retrieve mode is ignored for the refresh method, which always causes data to be retrieved from the database and not the cache.

See Also:

DatabaseQuery.dontMaintainCache(), ObjectLevelReadQuery.shouldCheckDescriptorForCacheUsage(), Constant Field Values

CACHE_STORE_MODE

public static final java.lang.String CACHE_STORE_MODE

"javax.persistence.cache.storeMode"

Configures the behavior when data is read from the database and when data is committed into the database.

See Also:

DatabaseQuery.dontMaintainCache(), DatabaseQuery.maintainCache(), ObjectLevelReadQuery.refreshIdentityMapResult(), Constant Field Values

CACHE_USAGE

public static final java.lang.String CACHE_USAGE

"eclipselink.cache-usage"

Configures the query to utilize the EclipseLink cache, by default the cache is not checked on queries before accessing the database. Valid values are all declared in CacheUsage class. For primary key cache hits the QUERY_TYPE hint must also be set to QueryType.ReadObject.

See Also:

CacheUsage, QUERY_TYPE, ReadObjectQuery, ObjectLevelReadQuery.setCacheUsage(int), Constant Field Values

QUERY_RESULTS_CACHE

public static final java.lang.String QUERY_RESULTS_CACHE

"eclipselink.query-results-cache"

Configures the query to use a results cache. By default the query will cache 100 query results, such that the same named query with the same arguments is re-executed it will skip the database and just return the cached results. Valid values are: HintValues.PERSISTENCE_UNIT_DEFAULT, HintValues.TRUE, HintValues.FALSE, "" could be used instead of default value HintValues.PERSISTENCE_UNIT_DEFAULT. By default query results are not cached. This is not, and is independent from the object cache.

See Also:

QueryResultsCachePolicy, ReadQuery.setQueryResultsCachePolicy(org.eclipse.persistence.queries.QueryResultsCachePolicy), Constant Field Values

QUERY_RESULTS_CACHE_SIZE

public static final java.lang.String QUERY_RESULTS_CACHE_SIZE

"eclipselink.query-results-cache.size"

Configures the size of the query's results cache. By default the query will cache 100 query results, such that the same named query with the same arguments is re-executed it will skip the database and just return the cached results. If the query has no arguments a size of 1 should be used (as there is only a single result). Valid values are Integer or Strings that can be parsed to int values.

See Also:

QueryResultsCachePolicy.setMaximumCachedResults(int), Constant Field Values

QUERY_RESULTS_CACHE_EXPIRY

public static final java.lang.String QUERY_RESULTS_CACHE_EXPIRY

"eclipselink.query-results-cache.expiry"

Configures the time to live, or expiry time of the query's results cache. By default the query results cache will not expiry results. Valid values are number of milliseconds, Integer or Strings that can be parsed to int values.

See Also:

CacheInvalidationPolicy, QueryResultsCachePolicy.setCacheInvalidationPolicy(org.eclipse.persistence.descriptors.invalidation.CacheInvalidationPolicy), Constant Field Values

QUERY_RESULTS_CACHE_RANDOMIZE_EXPIRY

public static final java.lang.String QUERY_RESULTS_CACHE_RANDOMIZE_EXPIRY

"eclipselink.query-results-cache.randomize-expiry"

Configures a randomization on the expiry invalidation time. This can be used to avoid bottlenecks from the cached values expiring at the same time. By default expiry is not randomized. Valid values are "true" and "false", false is the default.

See Also:

org.eclipse.persistence.descriptors.invalidation.TimeToLiveCacheInvalidationPolicy#setInvalidationRandomized(boolean), Constant Field Values

QUERY_RESULTS_CACHE_IGNORE_NULL

public static final java.lang.String QUERY_RESULTS_CACHE_IGNORE_NULL

"eclipselink.query-results-cache.ignore-null"

Configures null results to not be cached. This can be used to use the query cache as a secondary key index, and allow inserts of new objects. By default null results are cached. Valid values are "true" and "false", false is the default.

See Also:

QueryResultsCachePolicy.setIsNullIgnored(boolean), Constant Field Values

QUERY_RESULTS_CACHE_TYPE

public static final java.lang.String QUERY_RESULTS_CACHE_TYPE

"eclipselink.query-results-cache.type"

Configures the cache type of the query's results cache. By default the a fixed sized LRU cache is used (CACHE). Valid values are defined in the CacheType enum (as Strings).

See Also:

CacheType, QueryResultsCachePolicy.setCacheType(java.lang.Class), Constant Field Values

QUERY_RESULTS_CACHE_EXPIRY_TIME_OF_DAY

public static final java.lang.String QUERY_RESULTS_CACHE_EXPIRY_TIME_OF_DAY

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

Configures the time of day expiry time of the query's results cache. By default the query results cache will not expiry results. Valid values are String Time format, "HH:MM:SS".

See Also:

CacheInvalidationPolicy, QueryResultsCachePolicy.setCacheInvalidationPolicy(org.eclipse.persistence.descriptors.invalidation.CacheInvalidationPolicy), Constant Field Values

QUERY_REDIRECTOR

public static final java.lang.String QUERY_REDIRECTOR

"eclipselink.query.redirector"

Used to provide a QueryRedirector to the executing query. The redirector must implement the QueryRedirector interface. This can be used to perform advanced query operations in code, or dynamically customize the query in code before execution. The value should be the name of the QueryRedirector class.

i.e. "org.acme.persistence.MyQueryRedirector"

The value could also be a Class, or an instance that implements the QueryRedirector interface.

See Also:

QueryRedirector, DatabaseQuery.setRedirector(org.eclipse.persistence.queries.QueryRedirector), Constant Field Values

PARTITIONING

public static final java.lang.String PARTITIONING

"eclipselink.partitioning"

Used to provide a PartitioningPolicy instance or name to the query. This allows the query to execute on a specific, or on multiple connection pools.

See Also:

Partitioning, PartitioningPolicy, Constant Field Values

QUERY_TYPE

public static final java.lang.String QUERY_TYPE

"eclipselink.query-type"

Configures the EclipseLink query type to use for the query. By default EclipseLink ReportQuery or ReadAllQuery are used for most JPQL queries, this allows other query types to be used, such as ReadObjectQuery which can be used for queries that are know to return a single object, and has different caching semantics. Valid values are all declared in QueryType class. A fully qualified class name of a valid subclass of DatabaseQuery can also be used.

i.e. "org.acme.persistence.CustomQuery"

See Also:

QueryType, Constant Field Values

PESSIMISTIC_LOCK

public static final java.lang.String PESSIMISTIC_LOCK

"eclipselink.pessimistic-lock"

Configures the query to acquire a pessimistic lock (write-lock) on the resulting rows in the database. Valid values are all declared in PessimisticLock class. Pessimistic locking support and behavior may differ on difference database platforms.

See Also:

PessimisticLock, Note: As of JPA 2.0 there is a standard way to configure pessimistic locking., LockModeType, (find(), refresh(), lock()), (setLockMode()), Constant Field Values

PESSIMISTIC_LOCK_TIMEOUT

public static final java.lang.String PESSIMISTIC_LOCK_TIMEOUT

"javax.persistence.lock.timeout"

Configures the WAIT timeout used in pessimistic locking, if the database query exceeds the timeout the database will terminate the query and return an exception. Valid values are Integer or Strings that can be parsed to int values. Some database platforms may not support lock timeouts, you may consider setting a JDBC_TIMEOUT hint for these platforms.

See Also:

JDBC_TIMEOUT, ObjectLevelReadQuery.setWaitTimeout(Integer), Constant Field Values

REFRESH

public static final java.lang.String REFRESH

"eclipselink.refresh"

Configures the query to refresh the resulting objects in the cache and persistent context with the current state of the database. This will also refresh the objects in the shared cache, unless a flush has occurred. Any unflushed changes made to the objects will be lost (unless this query triggers a flush before execution). The refresh will cascade relationships based on the REFRESH_CASCADE hint value. Valid values are: HintValues.FALSE, HintValues.TRUE, "" could be used instead of default value HintValues.FALSE

See Also:

REFRESH_CASCADE, ObjectBuildingQuery.setShouldRefreshIdentityMapResult(boolean), Constant Field Values

BATCH

public static final java.lang.String BATCH

"eclipselink.batch"

Configures the query to optimize the retrieval of the related objects, the related objects for all the resulting objects will be read in a single query (instead of n queries). Batch reading is normally more efficient than join fetch, especially for collection relationships. Valid values are strings that represent JPQL style navigations to a relationship.

e.g. "e.manager.phoneNumbers"

Note: Batch reading produces two lines of SQL to read the requested object graph and uses the 'where clause' of the first SQL as part of the 'where clause' of the second. When indirect attributes of the objects returned from the first query are referenced the second query is executed to return those attributes. If changes are made to data referenced in the 'where clause' after the first SQL results are returned but before the second query executes then these attributes may not be returned by the second query. To prevent this reference these attributes before changing data associated with the query."

See Also:

BatchFetch, BATCH_TYPE, BatchFetchType, ObjectLevelReadQuery.addBatchReadAttribute(String), Constant Field Values

BATCH_TYPE

public static final java.lang.String BATCH_TYPE

"eclipselink.batch.type"

Configures the type of batch fetching to use for any batch fetched relationships on the query. Valid values are defined in BatchFetchType ("JOIN", "EXISTS", "IN").

See Also:

BATCH, BatchFetchType, BatchFetch, ObjectLevelReadQuery.setBatchFetchType(BatchFetchType), Constant Field Values

BATCH_SIZE

public static final java.lang.String BATCH_SIZE

"eclipselink.batch.size"

Configures the batch size for batch fetching using the IN batch type. Valid values are integer values > 0. The default size is 256, or the cursor pageSize.

See Also:

BATCH, BATCH_TYPE, BatchFetchType, BatchFetch, ObjectLevelReadQuery.setBatchFetchSize(int), Constant Field Values

FETCH

public static final java.lang.String FETCH

"eclipselink.join-fetch"

Configures the query to optimize the retrieval of the related objects, the related objects will be joined into the query instead of being queried independently. This allow for nested join fetching which is not supported in JPQL. It also allows for join fetching with native queries. This uses an INNER join and will filter null or empty values, see LEFT_FETCH for outer joins. Valid values are strings that represent JPQL style navigations to a relationship.

e.g. e.manager.phoneNumbers

See Also:

BATCH, LEFT_FETCH, ObjectLevelReadQuery.addJoinedAttribute(String), Constant Field Values

LEFT_FETCH

public static final java.lang.String LEFT_FETCH

"eclipselink.left-join-fetch"

Configures the query to optimize the retrieval of the related objects, the related objects will be joined into the query instead of being queried independently. This allow for nested join fetching which is not supported in JPQL. It also allows for join fetching with native queries. This uses an OUTER join to allow null or empty values. Valid values are strings that represent JPQL style navigations to a relationship.

e.g. e.manager.phoneNumbers

See Also:

BATCH, FETCH, ObjectLevelReadQuery.addJoinedAttribute(String), Constant Field Values

READ_ONLY

public static final java.lang.String READ_ONLY

"eclipselink.read-only"

Configures the query to return shared (read-only) objects from the cache, instead of objects registered with the persistence context. This improves performance by avoiding the persistence context registration and change tracking overhead to read-only objects. Valid values are: HintValues.FALSE, HintValues.TRUE, "" could be used instead of default value HintValues.FALSE

See Also:

ObjectLevelReadQuery.setIsReadOnly(boolean), Constant Field Values

JDBC_TIMEOUT

public static final java.lang.String JDBC_TIMEOUT

"eclipselink.jdbc.timeout"

Configures the JDBC timeout of the query execution, if the database query exceeds the timeout the database will terminate the query and return an exception. Valid values are Integer or Strings that can be parsed to int values.

See Also:

DatabaseQuery.setQueryTimeout(int), Constant Field Values

JDBC_FETCH_SIZE

public static final java.lang.String JDBC_FETCH_SIZE

"eclipselink.jdbc.fetch-size"

Configures the JDBC fetch-size for the queries result-set. This can improve the performance for queries that return large result-sets. Valid values are Integer or Strings that can be parsed to int values.

See Also:

ReadQuery.setFetchSize(int), Constant Field Values

JDBC_MAX_ROWS

public static final java.lang.String JDBC_MAX_ROWS

"eclipselink.jdbc.max-rows"

Configures the JDBC max-rows, if the query returns more rows than the max-rows the trailing rows will not be returned by the database. This is the same as JPA Query setMaxResults(), but can be set in meta-data for NamedQuerys. Valid values are Integer or Strings that can be parsed to int values.

See Also:

Query.setMaxResults(int), ReadQuery.setMaxRows(int), Constant Field Values

JDBC_FIRST_RESULT

public static final java.lang.String JDBC_FIRST_RESULT

"eclipselink.jdbc.first-result"

Configures the query to skip the firstResult number of rows. This is the same as JPA Query setFirstResults(), but can be set in meta-data for NamedQuerys. Valid values are Integer or Strings that can be parsed to int values.

See Also:

Query.setFirstResult(int), ReadQuery.setFirstResult(int), Constant Field Values

RESULT_COLLECTION_TYPE

public static final java.lang.String RESULT_COLLECTION_TYPE

"eclipselink.result-collection-type"

Configures the collection class implementation for the queries result. The fully qualified class name must be used, without the .class. Valid values are a Class representing a collection type or a String representing the class' name of the collection type. If a Collection type that is not a List is used, getResultCollection() or getSingleResult() must be used instead of getResultList().

e.g. "java.util.ArrayList"

See Also:

JpaQuery.getResultCollection(), ReadAllQuery.useCollectionClass(Class), Constant Field Values

REFRESH_CASCADE

public static final java.lang.String REFRESH_CASCADE

"eclipselink.refresh.cascade"

Defines if a refresh query should cascade the refresh to relationships. Valid values are all declared in CascadePolicy class. The REFRESH hint should also be set to cause a refresh.

See Also:

CascadePolicy, REFRESH, DatabaseQuery.setCascadePolicy(int), Constant Field Values

MAINTAIN_CACHE

public static final java.lang.String MAINTAIN_CACHE

"eclipselink.maintain-cache"

Configures the query to not use both the shared cache, and the transactional cache/persistence context. Resulting objects will be read and built directly from the database, and not registered in the persistence context. Changes made to the objects will not be updated unless merged, object identity will not be maintained. This can be used to read the current state of the database, without affecting the current persistence context. By default the cache is always maintained. Valid values are: HintValues.FALSE, HintValues.TRUE, "" could be used instead of default value HintValues.FALSE

See Also:

DatabaseQuery.setShouldMaintainCache(boolean), Constant Field Values

PREPARE

public static final java.lang.String PREPARE

"eclipselink.prepare"

Configures the query to not prepare its SQL. By default queries generate their SQL the first time they are executed, and avoid the cost of generating the SQL on subsequent executions. This can be used to generate the SQL on every execution if the query requires usage of dynamic SQL, such as to handle null parameters (use IS NULL instead of = null). This only effects the SQL generation, not parameter binding or statement caching. Valid values are: HintValues.FALSE, HintValues.TRUE, "" could be used instead of default value HintValues.FALSE

See Also:

DatabaseQuery.setShouldPrepare(boolean), Constant Field Values

CACHE_STATMENT

public static final java.lang.String CACHE_STATMENT

"eclipselink.jdbc.cache-statement"

Configures if the query will cache its JDBC statement. 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. If statement caching is desired, it should normally be set for the entire persistence unit in the persistence.xml, not in each query. If a DataSource is used statement caching must be set in the DataSource configuration, not in EclipseLink. Valid values are: HintValues.FALSE, HintValues.TRUE, "" could be used instead of default value HintValues.FALSE

See Also:

PersistenceUnitProperties.CACHE_STATEMENTS, DatabaseQuery.setShouldCacheStatement(boolean), Constant Field Values

FLUSH

public static final java.lang.String FLUSH

"eclipselink.flush"

Configures if the query should trigger a flush of the persistence context before execution. If the query may access objects that have been changed in the persistence context, trigger a flush is required for the query to see these changes. If the query does not require seeing the changes, then avoid the flush can improve performance. The default flush-mode can be set on the EntityManager or configured as a persistence unit property. By default the flush-mode is AUTO, which requires a flush before any query execution. Conforming can also be used to query changes without requiring a flush, refer to the CACHE_USAGE query hint for conforming. Valid values are: HintValues.FALSE, HintValues.TRUE, "" could be used instead of default value HintValues.FALSE

See Also:

EntityManager.setFlushMode(javax.persistence.FlushModeType), PersistenceUnitProperties.PERSISTENCE_CONTEXT_FLUSH_MODE, DatabaseQuery.setFlushOnExecute(Boolean), Constant Field Values

HINT

public static final java.lang.String HINT

"eclipselink.sql.hint"

Sets a SQL hint string into the query that will be generated into the SQL statement after the SELECT/INSERT/UPDATE/DELETE command.

A SQL hint can be used on certain database platforms to define how the query uses indexes and other such low level usages. This should be the full hint string including the comment \ delimiters.

See Also:

DatabaseQuery.setHintString(String), Constant Field Values

NATIVE_CONNECTION

public static final java.lang.String NATIVE_CONNECTION

"eclipselink.jdbc.native-connection"

Configures if the query requires a native JDBC connection. 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 are known by EclipseLink to require native connections this will default to true, otherwise is false. Valid values are: HintValues.FALSE, HintValues.TRUE, "" could be used instead of default value HintValues.FALSE

See Also:

PersistenceUnitProperties.TARGET_SERVER, DatabaseQuery.setIsNativeConnectionRequired(boolean), Constant Field Values

CURSOR

public static final java.lang.String CURSOR

"eclipselink.cursor"

Configures the query to return a CursoredStream. A cursor is a stream of the JDBC ResultSet. Cursor implements Enumeration, when the each next() will fetch the next from the JDBC ResultSet, and build the resulting Object or value. A Cursor requires and will keep a live JDBC connection, close() must be called to free the Cursor's resources. A Cursor can be accessed from a JPA Query through getSingleResult(), or from JpaQuery using getResultCursor(). Cursors are useful for large results sets, and if only the first few results are desired. MAX_ROWS and FIRST_RESULT can also be used instead of cursors to obtain a page of results. Valid values are: HintValues.FALSE, HintValues.TRUE, "" could be used instead of default value HintValues.FALSE

See Also:

TypedQuery.getSingleResult(), JpaQuery.getResultCursor(), Cursor, CursoredStream, ReadAllQuery.useCursoredStream(), Constant Field Values

CURSOR_INITIAL_SIZE

public static final java.lang.String CURSOR_INITIAL_SIZE

"eclipselink.cursor.initial-size"

Configures the query to return a CursoredStream with the initial threshold size. The initial size is the initial number of objects that are prebuilt for the stream before a next() is called. Valid values are Integer or Strings that can be parsed to int values.

See Also:

ReadAllQuery.useCursoredStream(int, int), Constant Field Values

CURSOR_PAGE_SIZE

public static final java.lang.String CURSOR_PAGE_SIZE

"eclipselink.cursor.page-size"

Configures the query to return a CursoredStream with the page size. The page size is the number of objects that are fetched from the stream on a next() called, if the buffer of objects is empty. Valid values are Integer or Strings that can be parsed to int values.

See Also:

ReadAllQuery.useCursoredStream(int, int), Constant Field Values

CURSOR_SIZE

public static final java.lang.String CURSOR_SIZE

"eclipselink.cursor.size-sql"

Configures the SQL string for the size query of a Cursor query. This is only required for cursor queries that use native SQL or procedures. The size query is only used if the size() is called on the Cursor. The SQL should perform a COUNT of the rows returned by the original query.

See Also:

CURSOR, Cursor.size(), ReadAllQuery.useCursoredStream(int, int, org.eclipse.persistence.queries.ValueReadQuery), Constant Field Values

SCROLLABLE_CURSOR

public static final java.lang.String SCROLLABLE_CURSOR

"eclipselink.cursor.scrollable"

Configures the query to return a ScrollableCursor. A cursor is a stream of the JDBC ResultSet. ScrollableCursor implements ListIterator, when the each next() will fetch the next from the JDBC ResultSet, and build the resulting Object or value. ScrollableCursor can scroll forwards and backwards and position into the ResultSet. A Cursor requires and will keep a live JDBC connection, close() must be called to free the Cursor's resources. A Cursor can be accessed from a JPA Query through getSingleResult(), or from JpaQuery using getResultCursor(). Cursors are useful for large results sets, and if only some of the results are desired. MAX_ROWS and FIRST_RESULT can also be used instead of cursors to obtain a page of results. Valid values are: HintValues.FALSE, HintValues.TRUE, "" could be used instead of default value HintValues.FALSE

See Also:

TypedQuery.getSingleResult(), JpaQuery.getResultCursor(), Cursor, ScrollableCursor, ReadAllQuery.useScrollableCursor(), Constant Field Values

RESULT_SET_TYPE

public static final java.lang.String RESULT_SET_TYPE

"eclipselink.cursor.scrollable.result-set-type"

This can be used on ScrollableCursor queries to set the JDBC ResultSet scroll type.

See Also:

ResultSetType, SCROLLABLE_CURSOR, ScrollableCursorPolicy.setResultSetType(int), Constant Field Values

RESULT_SET_CONCURRENCY

public static final java.lang.String RESULT_SET_CONCURRENCY

"eclipselink.cursor.scrollable.result-set-concurrency"

This can be used on ScrollableCursor queries to set the JDBC ResultSet concurrency.

See Also:

ResultSetConcurrency, SCROLLABLE_CURSOR, ScrollableCursorPolicy.setResultSetConcurrency(int), Constant Field Values

FETCH_GROUP

public static final java.lang.String FETCH_GROUP

"eclipselink.fetch-group"

Configures the query to use the fetch group object. This is an instance of FetchGroup. The query will only fetch the attributes defined in the fetch group, if any other attribute is accessed it will cause the object to be refreshed. To load all FetchGroup's relationship attributes set the FetchGroup's boolean flag "shouldLoad" to true. FetchGroups are only supported for queries returning objects (only a single alias can be the select clause). Weaving is required to allow usage of fetch groups.

See Also:

FETCH_GROUP_NAME, FETCH_GROUP_ATTRIBUTE, FETCH_GROUP_DEFAULT, LOAD_GROUP, FetchGroup, FetchGroup.setShouldLoad(boolean), FetchGroupManager, ObjectLevelReadQuery.setFetchGroup(org.eclipse.persistence.queries.FetchGroup), Constant Field Values

FETCH_GROUP_NAME

public static final java.lang.String FETCH_GROUP_NAME

"eclipselink.fetch-group.name"

Configures the query to use a named fetch group defined for the result class. This is the name of the fetch group, as defined on the ClassDescriptor. Currently FetchGroups can only be defined on the ClassDescriptor using a DescriptorCustomizer. The query will only fetch the attributes defined in the fetch group, if any other attribute is accessed it will cause the object to be refreshed. To load all FetchGroup's relationship attributes set the FetchGroup's boolean flag "load" to true. FetchGroups are only supported for queries returning objects (only a single alias can be the select clause). Weaving is required to allow usage of fetch groups.

See Also:

FETCH_GROUP_ATTRIBUTE, FETCH_GROUP_DEFAULT, LOAD_GROUP, FetchGroupManager, FetchGroup, ObjectLevelReadQuery.setFetchGroupName(String), Constant Field Values

FETCH_GROUP_ATTRIBUTE

public static final java.lang.String FETCH_GROUP_ATTRIBUTE

"eclipselink.fetch-group.attribute"

Configures the query to use a dynamic fetch group that includes a list of attributes. Each attribute must be defined using a separate hint. The primary key and version are always included. The query will only fetch the attributes defined in the fetch group, if any other attribute is accessed it will cause the object to be refreshed. To load all FetchGroup's relationship attributes set FETCH_GROUP_LOAD to "true". FetchGroups are only supported for queries returning objects (only a single alias can be the select clause). Weaving is required to allow usage of fetch groups. Both local and nested attributes are supported.

See Also:

FETCH_GROUP_NAME, FETCH_GROUP_DEFAULT, FETCH_GROUP_LOAD, LOAD_GROUP, FetchGroup, ObjectLevelReadQuery.setFetchGroup(org.eclipse.persistence.queries.FetchGroup), Constant Field Values

FETCH_GROUP_LOAD

public static final java.lang.String FETCH_GROUP_LOAD

"eclipselink.fetch-group.load"

Configures a dynamic fetch group to load (default) or not to load its attributes. Could be used with FETCH_ATTRIBUTES hint. To load all FetchGroup's relationship attributes set this hint to "true". Weaving is required to allow usage of fetch groups. Valid values are: HintValues.FALSE, HintValues.TRUE, "" could be used instead of default value HintValues.TRUE

See Also:

FETCH_GROUP_ATTRIBUTE, FetchGroup, FetchGroup.setShouldLoad(boolean), Constant Field Values

JPA_FETCH_GRAPH

public static final java.lang.String JPA_FETCH_GRAPH

"javax.persistence.fetchgraph"

Configures a jpa entity graph to be used as a fetch graph template. Those attributes included in the entity graph will have their values fetched and populated. Attributes of the represented entity that are not present in the entity graph will be treated as FetchType.LAZY.

See Also:

Constant Field Values

FETCH_GROUP_DEFAULT

public static final java.lang.String FETCH_GROUP_DEFAULT

"eclipselink.fetch-group.default"

Configures the query not to use the default fetch group. The default fetch group is defined by all non-lazy Basic mappings. If set to FALSE all attributes will be fetched, including lazy Basics, this still excludes lazy relationships, they will fetch their foreign keys, but not their values. FetchGroups are only supported for queries returning objects (only a single alias can be the select clause). Weaving is required to allow usage of fetch groups. Valid values are: HintValues.FALSE, HintValues.TRUE, "" could be used instead of default value HintValues.TRUE

See Also:

FETCH_GROUP_NAME, FETCH_GROUP_ATTRIBUTE, FetchGroup, ObjectLevelReadQuery.setShouldUseDefaultFetchGroup(boolean), Constant Field Values

LOAD_GROUP

public static final java.lang.String LOAD_GROUP

"eclipselink.load-group"

Configures the query to use the load group object. This is an instance of LoadGroup. Ensures that all relational attributes an the group are loaded. LoadGroups are only supported for queries returning objects (only a single alias can be the select clause).

See Also:

LOAD_GROUP_ATTRIBUTE, LoadGroup, ObjectLevelReadQuery.setLoadGroup(org.eclipse.persistence.queries.LoadGroup), Constant Field Values

JPA_LOAD_GRAPH

public static final java.lang.String JPA_LOAD_GRAPH

"javax.persistence.loadgraph"

Configures a jpa entity graph to be used as a load graph template. Those attributes included in the entity graph will have their values fetched and populated. Attributes of the represented entity that are not present in the entity graph will be loaded based on their mapping based FetchType settings.

See Also:

Constant Field Values

LOAD_GROUP_ATTRIBUTE

public static final java.lang.String LOAD_GROUP_ATTRIBUTE

"eclipselink.load-group.attribute"

Configures the query to use load group that includes a list of attributes. Each attribute must be defined using a separate hint. The query will load 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:

LOAD_GROUP, LoadGroup, org.eclipse.persistence.queries.ObjectLevelReadQuery#setLoadGroup(org.eclipse.persistence.queries.FetchGroup), Constant Field Values

EXCLUSIVE_CONNECTION

public static final java.lang.String EXCLUSIVE_CONNECTION

"eclipselink.exclusive-connection"

Configures the query to use the exclusive (transactional/write) connection. This is only relevant if a EXCLUSIVE_CONNECTION_MODE property has been set for the persistence unit (such as VPD). If an EXCLUSIVE_CONNECTION_MODE has been configured, this will ensure that the query is executed through the exclusive connection. This may be required in certain cases. An example being where database security will prevent a query joining to a secure table from returning the correct results when executed through the shared connection. Valid values are: HintValues.FALSE, HintValues.TRUE.

See Also:

PersistenceUnitProperties.EXCLUSIVE_CONNECTION_MODE, ConnectionPolicy.setExclusiveMode(org.eclipse.persistence.sessions.server.ConnectionPolicy.ExclusiveMode), ObjectBuildingQuery.setShouldUseExclusiveConnection(boolean), Constant Field Values

INHERITANCE_OUTER_JOIN

public static final java.lang.String INHERITANCE_OUTER_JOIN

"eclipselink.inheritance.outer-join"

Configures the query to outer-join all subclasses. This is only relevant for queries to root or branch inherited classes. By default a separate query is executed for each subclass. This can also be configured for the class using a DescriptorCustomizer. This is required for correct ordering, firstResult, maxResult, and cursors. Valid values are: HintValues.FALSE, HintValues.TRUE.

See Also:

InheritancePolicy.setShouldOuterJoinSubclasses(boolean), ObjectLevelReadQuery.setShouldOuterJoinSubclasses(boolean), Constant Field Values

ALLOW_NATIVE_SQL_QUERY

public static final java.lang.String ALLOW_NATIVE_SQL_QUERY

The "eclipselink.jdbc.allow-native-sql-query" property specifies whether a single native SQL query should override a persistence unit level setting (eclipselink.jdbc.allow-native-sql-queries). The PU level flag is of particular importance within a multitenant to minimize the potential impact of revealing multitenant. However in some cases the application may need to allow certain native SQL queries through.

Allowed Values (String):

• "true" - allow native SQL (and override the persistence unit flag)
• "false" - (DEFAULT) do not allow native SQL (and respect the persistence unit flag if set.)

See Also:

{, Constant Field Values

AS_OF

public static final java.lang.String AS_OF

"eclipselink.history.as-of"

Configures the query to query the state of the object as-of a point in time. This can only be used if the class has been configured with historical support, or if Oracle Flashback is used. Valid values are timestamps in the form "YYYY/MM/DD HH:MM:SS.n".

See Also:

org.eclipse.persistence.descriptors.HistoryPolicy, ObjectLevelReadQuery.setAsOfClause(org.eclipse.persistence.history.AsOfClause), Constant Field Values

AS_OF_SCN

public static final java.lang.String AS_OF_SCN

"eclipselink.history.as-of.scn"

Configures the query to query the state of the object as-of a database SCN (System Change Number). This can only be used with Oracle Flashback support. Valid values are Integer SCN values.

See Also:

ObjectLevelReadQuery.setAsOfClause(org.eclipse.persistence.history.AsOfClause), Constant Field Values

RESULT_TYPE

public static final java.lang.String RESULT_TYPE

"eclipselink.result-type"

By default in JPA for non-single select queries an Array of values is returned. If getSingleResult() is called the first array is returned, for getResultList() a List of arrays is returned.

i.e. "Select e.firstName, e.lastName from Employee e" returns List

or the native query, "SELECT * FROM EMPLOYEE" returns List

The ResultType can be used to instead return a Map of values (DatabaseRecord, ReportQueryResult).

It can also be used to return a single column, or single value. Valid values are defined in ResultType.

See Also:

ResultType, Record, DatabaseRecord, ReportQueryResult, ReportQuery.setReturnType(int), org.eclipse.persistence.queries.DataReadQuery#setUseAbstractRecord(boolean), Constant Field Values

INDIRECTION_POLICY

public static final java.lang.String INDIRECTION_POLICY

"eclipselink.cache-usage.indirection-policy"

This can be used on a query with a CACHE_USAGE hint to configure the behavior of in-memory querying and conforming's treatment of uninstantiated indirection/lazy relationships. This is only relevant when the query traverses a join across a lazy relationship. Valid values are defined in CacheUsageIndirectionPolicy.

See Also:

CacheUsageIndirectionPolicy, CACHE_USAGE, ObjectLevelReadQuery.setInMemoryQueryIndirectionPolicyState(int), Constant Field Values

PESSIMISTIC_LOCK_SCOPE

public static final java.lang.String PESSIMISTIC_LOCK_SCOPE

"javax.persistence.lock.scope"

By default pessimistic lock applied to only the tables mapped to the object being locked.

It could be extended to apply also to relation (join) tables (ManyToMany and OneToOne case), and CollectionTables (ElementCollection case). Valid values are defined in PessimisticLockScope.

See Also:

PessimisticLockScope, LockModeType, Constant Field Values

COMPOSITE_UNIT_MEMBER

public static final java.lang.String COMPOSITE_UNIT_MEMBER

"eclipselink.composite-unit.member"

This must be used on a native query executed on composite persistence unit. It specifies the name of composite member persistence unit to execute the query on.

See Also:

DatabaseQuery.setSessionName(String), Constant Field Values

BATCH_WRITING

public static final java.lang.String BATCH_WRITING

"eclipselink.jdbc.batch-writing"

Configures if this modify query can be batched through batch writing. Some types of queries cannot be batched, such as DDL on some databases. Disabling batch writing will also allow the row count to be returned. Valid values are: HintValues.PERSISTENCE_UNIT_DEFAULT, HintValues.TRUE, HintValues.FALSE, "" could be used instead of default value HintValues.PERSISTENCE_UNIT_DEFAULT

See Also:

ModifyQuery.setIsBatchExecutionSupported(boolean), Constant Field Values

RESULT_SET_ACCESS

public static final java.lang.String RESULT_SET_ACCESS

"eclipselink.result-set-access"

Configures if this read object(s) query should keep result set until all result object(s) are built. That allows to avoid getting potentially huge objects (LOBs) from ResultSet in case they would not be used because the object is found in the cache. Valid values are: HintValues.PERSISTENCE_UNIT_DEFAULT, HintValues.TRUE, HintValues.FALSE, "" could be used instead of default value HintValues.PERSISTENCE_UNIT_DEFAULT

See Also:

ObjectLevelReadQuery.setIsResultSetAccessOptimizedQuery(boolean), ObjectLevelReadQuery.clearIsResultSetOptimizedQuery(), Constant Field Values

SERIALIZED_OBJECT

public static final java.lang.String SERIALIZED_OBJECT

"eclipselink.serialized-object"

Configures if this read object(s) query use SerializedObjectPolicy if it's set on the descriptor. Valid values are: HintValues.TRUE, HintValues.FALSE, "" could be used instead of default value HintValues.FALSE

See Also:

ObjectLevelReadQuery.setShouldUseSerializedObjectPolicy(boolean), Constant Field Values

RETURN_NAME_VALUE_PAIRS

public static final java.lang.String RETURN_NAME_VALUE_PAIRS

"eclipselink.query-return-name-value-pairs"

Configures a ResultSetMappingQuery to return populated DatabaseRecord(s) instead of raw data. This is particularly useful when the structure of the returned data is not known.

See Also:

ResultSetMappingQuery.setShouldReturnNameValuePairs(boolean), ResultSetMappingQuery.shouldReturnNameValuePairs(), Constant Field Values

Constructor Detail

QueryHints

public QueryHints()