/*******************************************************************************
 * Copyright (c) 1998, 2013 Oracle and/or its affiliates. All rights reserved.
 * This program and the accompanying materials are made available under the 
 * terms of the Eclipse Public License v1.0 and Eclipse Distribution License v. 1.0 
 * which accompanies this distribution. 
 * The Eclipse Public License is available at http://www.eclipse.org/legal/epl-v10.html
 * and the Eclipse Distribution License is available at 
 * http://www.eclipse.org/org/documents/edl-v10.php.
 *
 * Contributors:
 *     Oracle - initial API and implementation from Oracle TopLink
 *     07/16/2009-2.0 Guy Pelletier 
 *       - 277039: JPA 2.0 Cache Usage Settings
 *     10/29/2010-2.2 Michael O'Brien 
 *       - 325167: Make reserved # bind parameter char generic to enable native SQL pass through
 *     06/30/2011-2.3.1 Guy Pelletier 
 *       - 341940: Add disable/enable allowing native queries    
 ******************************************************************************/  
package org.eclipse.persistence.config;

import org.eclipse.persistence.annotations.BatchFetch;
import org.eclipse.persistence.annotations.BatchFetchType;

/**
 * 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.
 * 
 * <p>JPA Query Hint Usage:
 * 
 * <p><code>query.setHint(QueryHints.CACHE_USAGE, CacheUsage.CheckCacheOnly);</code>
 * <p>or 
 * <p><code>@QueryHint(name=QueryHints.CACHE_USAGE, value=CacheUsage.CheckCacheOnly)</code>
 * 
 * <p>Hint values are case-insensitive; "" could be used instead of default value.
 * 
 * @see HintValues
 * @see CacheUsage
 * @see PessimisticLock
 * @see QueryType
 */
public class QueryHints {
    /**
     * "eclipselink.jdbc.bind-parameters"
     * <p>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 PersistenceUnitProperties#JDBC_BIND_PARAMETERS
     * @see org.eclipse.persistence.queries.DatabaseQuery#setShouldBindAllParameters(boolean)
     */
    public static final String BIND_PARAMETERS = "eclipselink.jdbc.bind-parameters";

    /**
     * "eclipselink.jdbc.parameter-delimiter"
     * <p>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 PersistenceUnitProperties#JDBC_BIND_PARAMETERS
     * @see org.eclipse.persistence.queries.DatabaseQuery#setShouldBindAllParameters(boolean)
     */
    public static final String PARAMETER_DELIMITER = "eclipselink.jdbc.parameter-delimiter";
    
    /**
     * "javax.persistence.cache.retrieveMode"
     * <p>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.</p>
     * @see org.eclipse.persistence.queries.DatabaseQuery#dontMaintainCache()
     * @see org.eclipse.persistence.queries.ObjectLevelReadQuery#shouldCheckDescriptorForCacheUsage()
     */
    public static final String CACHE_RETRIEVE_MODE = "javax.persistence.cache.retrieveMode";
    
    /**
     * "javax.persistence.cache.storeMode"
     * <p>Configures the behavior when data is read from the database and when 
     * data is committed into the database.</p>
     * @see org.eclipse.persistence.queries.DatabaseQuery#dontMaintainCache()
     * @see org.eclipse.persistence.queries.DatabaseQuery#maintainCache()
     * @see org.eclipse.persistence.queries.ObjectLevelReadQuery#refreshIdentityMapResult()
     */
    public static final String CACHE_STORE_MODE = "javax.persistence.cache.storeMode";
    
    /**
     * "eclipselink.cache-usage"
     * <p>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 CacheUsage
     * @see #QUERY_TYPE
     * @see org.eclipse.persistence.queries.ReadObjectQuery
     * @see org.eclipse.persistence.queries.ObjectLevelReadQuery#setCacheUsage(int)
     */
    public static final String CACHE_USAGE = "eclipselink.cache-usage";
    
    /**
     * "eclipselink.query-results-cache"
     * <p>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 org.eclipse.persistence.queries.QueryResultsCachePolicy
     * @see org.eclipse.persistence.queries.ReadQuery#setQueryResultsCachePolicy(org.eclipse.persistence.queries.QueryResultsCachePolicy)
     */
    public static final String QUERY_RESULTS_CACHE = "eclipselink.query-results-cache";

    /**
     * "eclipselink.query-results-cache.size"
     * <p>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 org.eclipse.persistence.queries.QueryResultsCachePolicy#setMaximumCachedResults(int)
     */
    public static final String QUERY_RESULTS_CACHE_SIZE = "eclipselink.query-results-cache.size";

    /**
     * "eclipselink.query-results-cache.expiry"
     * <p>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 org.eclipse.persistence.descriptors.invalidation.CacheInvalidationPolicy
     * @see org.eclipse.persistence.queries.QueryResultsCachePolicy#setCacheInvalidationPolicy(org.eclipse.persistence.descriptors.invalidation.CacheInvalidationPolicy)
     */
    public static final String QUERY_RESULTS_CACHE_EXPIRY = "eclipselink.query-results-cache.expiry";

    /**
     * "eclipselink.query-results-cache.randomize-expiry"
     * <p>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 org.eclipse.persistence.descriptors.invalidation.TimeToLiveCacheInvalidationPolicy#setInvalidationRandomized(boolean)
     */
    public static final String QUERY_RESULTS_CACHE_RANDOMIZE_EXPIRY = "eclipselink.query-results-cache.randomize-expiry";

    /**
     * "eclipselink.query-results-cache.ignore-null"
     * <p>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 org.eclipse.persistence.queries.QueryResultsCachePolicy#setIsNullIgnored(boolean)
     */
    public static final String QUERY_RESULTS_CACHE_IGNORE_NULL = "eclipselink.query-results-cache.ignore-null";
    
    /**
     * "eclipselink.query-results-cache.type"
     * <p>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 org.eclipse.persistence.annotations.CacheType
     * @see org.eclipse.persistence.queries.QueryResultsCachePolicy#setCacheType(java.lang.Class)
     */
    public static final String QUERY_RESULTS_CACHE_TYPE = "eclipselink.query-results-cache.type";
    
    /**
     * "eclipselink.query-results-cache.expiry-time-of-day"
     * <p>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 org.eclipse.persistence.descriptors.invalidation.CacheInvalidationPolicy
     * @see org.eclipse.persistence.queries.QueryResultsCachePolicy#setCacheInvalidationPolicy(org.eclipse.persistence.descriptors.invalidation.CacheInvalidationPolicy)
     */
    public static final String QUERY_RESULTS_CACHE_EXPIRY_TIME_OF_DAY = "eclipselink.query-results-cache.expiry-time-of-day";
    
    /**
     * "eclipselink.query.redirector"
     * <p>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.
     * <p>i.e. "org.acme.persistence.MyQueryRedirector"
     * <p> The value could also be a Class, or an instance that implements the QueryRedirector interface.
     * @see org.eclipse.persistence.queries.QueryRedirector
     * @see org.eclipse.persistence.queries.DatabaseQuery#setRedirector(org.eclipse.persistence.queries.QueryRedirector)
     */
    public static final String QUERY_REDIRECTOR = "eclipselink.query.redirector";
    
    /**
     * "eclipselink.partitioning"
     * <p>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 org.eclipse.persistence.annotations.Partitioning
     * @see org.eclipse.persistence.descriptors.partitioning.PartitioningPolicy
     */
    public static final String PARTITIONING = "eclipselink.partitioning";

    /**
     * "eclipselink.query-type"
     * <p>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.
     * <p>i.e. "org.acme.persistence.CustomQuery"
     * @see QueryType
     */
    public static final String QUERY_TYPE = "eclipselink.query-type";
    
    /**
     * "eclipselink.pessimistic-lock"
     * <p>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 PessimisticLock
     * @see org.eclipse.persistence.queries.ObjectLevelReadQuery#setLockMode(short)
     * 
     * <B>Note:</B> As of JPA 2.0 there is a standard way to configure pessimistic locking.
     * @see javax.persistence.LockModeType
     * @see javax.persistence.EntityManager (find(), refresh(), lock())
     * @see javax.persistence.Query (setLockMode())
     */
    public static final String PESSIMISTIC_LOCK = "eclipselink.pessimistic-lock";
    
    /**
     * "javax.persistence.lock.timeout"
     * <p>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 #JDBC_TIMEOUT
     * @see org.eclipse.persistence.queries.ObjectLevelReadQuery#setWaitTimeout(Integer)
     */
    public static final String PESSIMISTIC_LOCK_TIMEOUT = "javax.persistence.lock.timeout";
    
    /**
     * "eclipselink.refresh"
     * <p>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 #REFRESH_CASCADE
     * @see org.eclipse.persistence.queries.ObjectLevelReadQuery#setShouldRefreshIdentityMapResult(boolean)
     */
    public static final String REFRESH = "eclipselink.refresh";
    
    /**
     * "eclipselink.batch"
     * <p>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.
     * <p>e.g. "e.manager.phoneNumbers"
     * <p>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 BatchFetch
     * @see #BATCH_TYPE
     * @see BatchFetchType
     * @see org.eclipse.persistence.queries.ReadAllQuery#addBatchReadAttribute(String)
     */
    public static final String BATCH = "eclipselink.batch";

    /**
     * "eclipselink.batch.type"
     * <p>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 #BATCH
     * @see BatchFetchType
     * @see BatchFetch
     * @see org.eclipse.persistence.queries.ObjectLevelReadQuery#setBatchFetchType(BatchFetchType)
     */
    public static final String BATCH_TYPE = "eclipselink.batch.type";

    /**
     * "eclipselink.batch.size"
     * <p>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 #BATCH
     * @see #BATCH_TYPE
     * @see BatchFetchType
     * @see BatchFetch
     * @see org.eclipse.persistence.queries.ObjectLevelReadQuery#setBatchFetchSize(int)
     */
    public static final String BATCH_SIZE = "eclipselink.batch.size";
    
    /**
     * "eclipselink.join-fetch"
     * <p>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.
     * <p>e.g. e.manager.phoneNumbers
     * @see #BATCH
     * @see #LEFT_FETCH
     * @see org.eclipse.persistence.queries.ObjectLevelReadQuery#addJoinedAttribute(String)
     */
    public static final String FETCH = "eclipselink.join-fetch";
    
    /**
     * "eclipselink.left-join-fetch"
     * <p>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.
     * <p>e.g. e.manager.phoneNumbers
     * @see #BATCH
     * @see #FETCH
     * @see org.eclipse.persistence.queries.ObjectLevelReadQuery#addJoinedAttribute(String)
     */
    public static final String LEFT_FETCH = "eclipselink.left-join-fetch";
    
    /**
     * "eclipselink.read-only"
     * <p>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 org.eclipse.persistence.queries.ObjectLevelReadQuery#setIsReadOnly(boolean)
     */
    public static final String READ_ONLY = "eclipselink.read-only";
    
    /**
     * "eclipselink.jdbc.timeout"
     * <p>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 org.eclipse.persistence.queries.DatabaseQuery#setQueryTimeout(int)
     */
    public static final String JDBC_TIMEOUT = "eclipselink.jdbc.timeout";
    
    /**
     * "eclipselink.jdbc.fetch-size"
     * <p>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 org.eclipse.persistence.queries.ReadQuery#setFetchSize(int)
     */
    public static final String JDBC_FETCH_SIZE = "eclipselink.jdbc.fetch-size";
    
    /**
     * "eclipselink.jdbc.max-rows"
     * <p>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 javax.persistence.Query#setMaxResults(int)
     * @see org.eclipse.persistence.queries.ReadQuery#setMaxRows(int)
     */
    public static final String JDBC_MAX_ROWS = "eclipselink.jdbc.max-rows";
    
    /**
     * "eclipselink.jdbc.first-result"
     * <p>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 javax.persistence.Query#setFirstResult(int)
     * @see org.eclipse.persistence.queries.ReadQuery#setFirstResult(int)
     */
    public static final String JDBC_FIRST_RESULT = "eclipselink.jdbc.first-result";
    
    /**
     * "eclipselink.result-collection-type"
     * <p>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().
     * <p>e.g. "java.util.ArrayList"
     * @see org.eclipse.persistence.jpa.JpaQuery#getResultCollection()
     * @see org.eclipse.persistence.queries.ReadAllQuery#useCollectionClass(Class)
     */
    public static final String RESULT_COLLECTION_TYPE = "eclipselink.result-collection-type";
    
    /**
     * "eclipselink.refresh.cascade"
     * <p>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 CascadePolicy
     * @see #REFRESH
     * @see org.eclipse.persistence.queries.DatabaseQuery#setCascadePolicy(int)
     */
    public static final String REFRESH_CASCADE = "eclipselink.refresh.cascade";
    
    /**
     * "eclipselink.maintain-cache"
     * <p>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 org.eclipse.persistence.queries.DatabaseQuery#setShouldMaintainCache(boolean)
     */
    public static final String MAINTAIN_CACHE = "eclipselink.maintain-cache";

    /**
     * "eclipselink.prepare"
     * <p>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 org.eclipse.persistence.queries.DatabaseQuery#setShouldPrepare(boolean)
     */
    public static final String PREPARE = "eclipselink.prepare";

    /**
     * "eclipselink.jdbc.cache-statement"
     * <p>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 PersistenceUnitProperties#CACHE_STATEMENTS
     * @see org.eclipse.persistence.queries.DatabaseQuery#setShouldCacheStatement(boolean)
     */
    public static final String CACHE_STATMENT = "eclipselink.jdbc.cache-statement";
    
    /**
     * "eclipselink.flush"
     * <p>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 javax.persistence.EntityManager#setFlushMode(javax.persistence.FlushModeType)
     * @see PersistenceUnitProperties#PERSISTENCE_CONTEXT_FLUSH_MODE
     * @see org.eclipse.persistence.queries.DatabaseQuery#setFlushOnExecute(Boolean)
     */
    public static final String FLUSH = "eclipselink.flush";
    
    /**
     * "eclipselink.sql.hint"
     * <p>
     * Sets a SQL hint string into the query that will be generated into the SQL statement after
     * the SELECT/INSERT/UPDATE/DELETE command.
     * <p>
     * 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 org.eclipse.persistence.queries.DatabaseQuery#setHintString(String)
     */
    public static final String HINT = "eclipselink.sql.hint";

    /**
     * "eclipselink.jdbc.native-connection"
     * <p>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 PersistenceUnitProperties#TARGET_SERVER
     * @see org.eclipse.persistence.queries.DatabaseQuery#setIsNativeConnectionRequired(boolean)
     */
    public static final String NATIVE_CONNECTION = "eclipselink.jdbc.native-connection";
    
    /**
     * "eclipselink.cursor"
     * <p>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 org.eclipse.persistence.jpa.JpaQuery#getSingleResult()
     * @see org.eclipse.persistence.jpa.JpaQuery#getResultCursor()
     * @see org.eclipse.persistence.queries.Cursor
     * @see org.eclipse.persistence.queries.CursoredStream
     * @see org.eclipse.persistence.queries.ReadAllQuery#useCursoredStream()
     */
    public static final String CURSOR = "eclipselink.cursor";

    /**
     * "eclipselink.cursor.initial-size"
     * <p>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 org.eclipse.persistence.queries.ReadAllQuery#useCursoredStream(int, int)
     */
    public static final String CURSOR_INITIAL_SIZE = "eclipselink.cursor.initial-size";

    /**
     * "eclipselink.cursor.page-size"
     * <p>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 org.eclipse.persistence.queries.ReadAllQuery#useCursoredStream(int, int)
     */
    public static final String CURSOR_PAGE_SIZE = "eclipselink.cursor.page-size";

    /**
     * "eclipselink.cursor.size-sql"
     * <p>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 #CURSOR
     * @see org.eclipse.persistence.queries.Cursor#size()
     * @see org.eclipse.persistence.queries.ReadAllQuery#useCursoredStream(int, int, org.eclipse.persistence.queries.ValueReadQuery)
     */
    public static final String CURSOR_SIZE = "eclipselink.cursor.size-sql";
    
    /**
     * "eclipselink.cursor.scrollable"
     * <p>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 org.eclipse.persistence.jpa.JpaQuery#getSingleResult()
     * @see org.eclipse.persistence.jpa.JpaQuery#getResultCursor()
     * @see org.eclipse.persistence.queries.Cursor
     * @see org.eclipse.persistence.queries.ScrollableCursor
     * @see org.eclipse.persistence.queries.ReadAllQuery#useScrollableCursor()
     */
    public static final String SCROLLABLE_CURSOR = "eclipselink.cursor.scrollable";

    /**
     * "eclipselink.cursor.scrollable.result-set-type"
     * <p>This can be used on ScrollableCursor queries to set the JDBC ResultSet scroll type.
     * @see ResultSetType
     * @see #SCROLLABLE_CURSOR
     * @see org.eclipse.persistence.queries.ScrollableCursorPolicy#setResultSetType(int)
     */
    public static final String RESULT_SET_TYPE = "eclipselink.cursor.scrollable.result-set-type";
    
    /**
     * "eclipselink.cursor.scrollable.result-set-concurrency"
     * <p>This can be used on ScrollableCursor queries to set the JDBC ResultSet concurrency.
     * @see ResultSetConcurrency
     * @see #SCROLLABLE_CURSOR
     * @see org.eclipse.persistence.queries.ScrollableCursorPolicy#setResultSetConcurrency(int)
     */
    public static final String RESULT_SET_CONCURRENCY = "eclipselink.cursor.scrollable.result-set-concurrency";
    
    /**
     * "eclipselink.fetch-group"
     * <p>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 #FETCH_GROUP_NAME
     * @see #FETCH_GROUP_ATTRIBUTE
     * @see #FETCH_GROUP_DEFAULT
     * @see #LOAD_GROUP
     * @see org.eclipse.persistence.queries.FetchGroup
     * @see org.eclipse.persistence.queries.FetchGroup#setShouldLoad
     * @see org.eclipse.persistence.descriptors.FetchGroupManager
     * @see org.eclipse.persistence.queries.ObjectLevelReadQuery#setFetchGroup(org.eclipse.persistence.queries.FetchGroup)
     */
    public static final String FETCH_GROUP = "eclipselink.fetch-group";
    
    /**
     * "eclipselink.fetch-group.name"
     * <p>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 #FETCH_GROUP_ATTRIBUTE
     * @see #FETCH_GROUP_DEFAULT
     * @see #LOAD_GROUP
     * @see org.eclipse.persistence.descriptors.FetchGroupManager
     * @see org.eclipse.persistence.queries.FetchGroup
     * @see org.eclipse.persistence.queries.ObjectLevelReadQuery#setFetchGroupName(String)
     */
    public static final String FETCH_GROUP_NAME = "eclipselink.fetch-group.name";
    
    /**
     * "eclipselink.fetch-group.attribute"
     * <p>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 #FETCH_GROUP_NAME
     * @see #FETCH_GROUP_DEFAULT
     * @see #FETCH_GROUP_LOAD
     * @see #LOAD_GROUP
     * @see org.eclipse.persistence.queries.FetchGroup
     * @see org.eclipse.persistence.queries.ObjectLevelReadQuery#setFetchGroup(org.eclipse.persistence.queries.FetchGroup)
     */
    public static final String FETCH_GROUP_ATTRIBUTE = "eclipselink.fetch-group.attribute";
    
    /**
     * "eclipselink.fetch-group.load"
     * <p>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 #FETCH_GROUP_ATTRIBUTE
     * @see org.eclipse.persistence.queries.FetchGroup
     * @see org.eclipse.persistence.queries.FetchGroup#setShouldLoad(boolean)
     */
    public static final String FETCH_GROUP_LOAD = "eclipselink.fetch-group.load";
    
    /**
     * "javax.persistence.fetchgraph"
     * <p> 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.
     */
    public static final String JPA_FETCH_GRAPH = "javax.persistence.fetchgraph";
    
    /**
     * "eclipselink.fetch-group.default"
     * <p>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 #FETCH_GROUP_NAME
     * @see #FETCH_GROUP_ATTRIBUTE
     * @see org.eclipse.persistence.queries.FetchGroup
     * @see org.eclipse.persistence.queries.ObjectLevelReadQuery#setShouldUseDefaultFetchGroup(boolean)
     */
    public static final String FETCH_GROUP_DEFAULT = "eclipselink.fetch-group.default";

    /**
     * "eclipselink.load-group"
     * <p>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 #LOAD_GROUP_ATTRIBUTE
     * @see org.eclipse.persistence.queries.LoadGroup
     * @see org.eclipse.persistence.queries.ObjectLevelReadQuery#setLoadGroup(org.eclipse.persistence.queries.LoadGroup)
     */
    public static final String LOAD_GROUP = "eclipselink.load-group";
    
    /**
     * "javax.persistence.loadgraph"
     * <p> 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.
     */
    public static final String JPA_LOAD_GRAPH = "javax.persistence.loadgraph";
    
    /**
     * "eclipselink.load-group.attribute"
     * <p>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 #LOAD_GROUP
     * @see org.eclipse.persistence.queries.LoadGroup
     * @see org.eclipse.persistence.queries.ObjectLevelReadQuery#setLoadGroup(org.eclipse.persistence.queries.FetchGroup)
     */
    public static final String LOAD_GROUP_ATTRIBUTE = "eclipselink.load-group.attribute";
    
    /**
     * "eclipselink.exclusive-connection"
     * <p>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 PersistenceUnitProperties#EXCLUSIVE_CONNECTION_MODE
     * @see org.eclipse.persistence.sessions.server.ConnectionPolicy#setExclusiveMode(org.eclipse.persistence.sessions.server.ConnectionPolicy.ExclusiveMode)
     * @see org.eclipse.persistence.queries.ObjectLevelReadQuery#setShouldUseExclusiveConnection(boolean)
     */
    public static final String EXCLUSIVE_CONNECTION = "eclipselink.exclusive-connection";
    
    /**
     * "eclipselink.inheritance.outer-join"
     * <p>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 org.eclipse.persistence.descriptors.InheritancePolicy#setShouldOuterJoinSubclasses(boolean)
     * @see org.eclipse.persistence.queries.ObjectLevelReadQuery#setShouldOuterJoinSubclasses(boolean)
     */
    public static final String INHERITANCE_OUTER_JOIN = "eclipselink.inheritance.outer-join";

    /**
     * The <code>"eclipselink.jdbc.allow-native-sql-query"</code> 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.
     * <p>
     * Allowed Values (String):
     * <ul>
     * <li>"true" - allow native SQL (and override the persistence unit flag)
     * <li>"false" - (DEFAULT) do not allow native SQL (and respect the persistence unit flag if set.)
     * </ul>
     * 
     * @see DatabaseQuery#setAllowNativeSQLQuery(boolean) {
     */
    public static final String ALLOW_NATIVE_SQL_QUERY = "eclipselink.jdbc.allow-native-sql-query";
    
    /**
     * "eclipselink.history.as-of"
     * <p>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 org.eclipse.persistence.descriptors.HistoryPolicy
     * @see org.eclipse.persistence.queries.ObjectLevelReadQuery#setAsOfClause(org.eclipse.persistence.history.AsOfClause)
     */
    public static final String AS_OF = "eclipselink.history.as-of";
    
    /**
     * "eclipselink.history.as-of.scn"
     * <p>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 org.eclipse.persistence.queries.ObjectLevelReadQuery#setAsOfClause(org.eclipse.persistence.history.AsOfClause)
     */
    public static final String AS_OF_SCN = "eclipselink.history.as-of.scn";

    /**
     * "eclipselink.result-type"
     * <p> 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.
     * <p>i.e. "Select e.firstName, e.lastName from Employee e" returns List<Object[]>
     * <p>or the native query, "SELECT * FROM EMPLOYEE" returns List<Object[]>
     * <p>The ResultType can be used to instead return a Map of values (DatabaseRecord, ReportQueryResult).
     * <p>It can also be used to return a single column, or single value.
     * Valid values are defined in ResultType.
     * @see ResultType
     * @see org.eclipse.persistence.sessions.Record
     * @see org.eclipse.persistence.sessions.DatabaseRecord
     * @see org.eclipse.persistence.queries.ReportQueryResult
     * @see org.eclipse.persistence.queries.ReportQuery#setReturnType(int)
     * @see org.eclipse.persistence.queries.DataReadQuery#setUseAbstractRecord(boolean)
     */
    public static final String RESULT_TYPE = "eclipselink.result-type";
    
    /**
     * "eclipselink.cache-usage.indirection-policy"
     * <p>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 CacheUsageIndirectionPolicy
     * @see #CACHE_USAGE
     * @see org.eclipse.persistence.queries.ObjectLevelReadQuery#setInMemoryQueryIndirectionPolicyState(int)
     */
    public static final String INDIRECTION_POLICY = "eclipselink.cache-usage.indirection-policy";
    
    /**
     * "javax.persistence.lock.scope"
     * <p> By default pessimistic lock applied to only the tables mapped to the object being locked.
     * <p> 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 javax.persistence.PessimisticLockScope
     * @see javax.persistence.LockModeType
     */
    public static final String PESSIMISTIC_LOCK_SCOPE = "javax.persistence.lock.scope";

    /**
     * "eclipselink.composite-unit.member"
     * <p>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 org.eclipse.persistence.queries.DatabaseQuery#setSessionName(String)
     */
    public static final String COMPOSITE_UNIT_MEMBER = "eclipselink.composite-unit.member";
    
    /**
     * "eclipselink.jdbc.batch-writing"
     * <p>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 org.eclipse.persistence.queries.ModifyQuery#setIsBatchExecutionSupported(boolean)
     */
    public static final String BATCH_WRITING = "eclipselink.jdbc.batch-writing";

    /**
     * "eclipselink.result-set-access"
     * <p>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 org.eclipse.persistence.queries.ObjectLevelReadQuery#setIsResultSetAccessOptimizedQuery(boolean)
     * @see org.eclipse.persistence.queries.ObjectLevelReadQuery#clearIsResultSetOptimizedQuery
     */
    public static final String RESULT_SET_ACCESS = "eclipselink.result-set-access";

    /**
     * "eclipselink.serialized-object"
     * <p>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 org.eclipse.persistence.queries.ObjectLevelReadQuery#setShouldUseSerializedObjectPolicy(boolean)
     */
    public static final String SERIALIZED_OBJECT = "eclipselink.serialized-object";

    /**
     * "eclipselink.query-return-name-value-pairs"
     * <p>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 org.eclipse.persistence.queries.ResultSetMappingQuery#setShouldReturnNameValuePairs(boolean)
     * @see org.eclipse.persistence.queries.ResultSetMappingQuery#shouldReturnNameValuePairs()
     */
    public static final String RETURN_NAME_VALUE_PAIRS = "eclipselink.query-return-name-value-pairs";
}