Cmobilecom JPA 2.0.RC1 Developer Guide

21. Query Properties/Hints

Query property(hint) names are defined in com.cmobilecom.jpa.Constants, including both JPA standard properties and Cmobilecom JPA-specific properties. JPA providers look for a property in the order of the following decreasing precedence:
  1. argument to method of Query, TypedQuery, EntityManager
  2. NamedQuery (xml or annotation)
  3. argument of createEntityManager
  4. argument of createEntityManagerFactory
  5. META-INF/persistence.xml

Standard Properties

Standard properties are defined in JPA specification.

Persistence Provider

	public static final String PERSISTENCE_PROVIDER = "javax.persistence.provider";
The fully qualified class name of the persistence provider for a persistence unit.

JDBC Connection

	public static final String JDBC_DRIVER = "javax.persistence.jdbc.driver";
	public static final String JDBC_URL = "javax.persistence.jdbc.url";
	public static final String JDBC_USER = "javax.persistence.jdbc.user";
	public static final String JDBC_PASSWORD = "javax.persistence.jdbc.password";
Properties for establishing JDBC connection by connection url, username and password.

Transaction and Data Source

	public static final String TRANSACTION_TYPE = "javax.persistence.transactionType";
	public static final String JTA_DATA_SOURCE = "javax.persistence.jtaDataSource";
	public static final String NON_JTA_DATA_SOURCE = "javax.persistence.nonJtaDataSource";
Transaction type is RESOURCE_LOCAL or JTA, and data source is a JNDI name for JTA or non-JTA.

Entity Graph

	public static final String FETCH_GRAPH = "javax.persistence.fetchgraph";
	public static final String FETCH_GRAPH = "javax.persistence.fetchgraph";
A fetch graph is to retrieve the exact (not more or less) object graph specified by the entity graph. However, a load graph is to retrieve at least the object graph specified by the entity graph.

Cache

	public static final String SHARED_CACHE_MODE = "javax.persistence.sharedCache.mode";
	public static final String CACHE_RETRIEVE_MODE = "javax.persistence.cache.retrieveMode";
	public static final String CACHE_STORE_MODE = "javax.persistence.cache.storeMode";
Shared cache mode, cache retrieve mode, and cache store mode. To override shared cache mode in persistence.xml, specify the property when creating EntityManagerFactory.

Lock

	public static final String LOCK_TIMEOUT = "javax.persistence.lock.timeout";
	public static final String LOCK_SCOPE = "javax.persistence.lock.scope";
Lock timeout in milliseconds, and pessimistic lock scope (PessimisticLockScope).

Query Timeout

	public static final String QUERY_TIMEOUT = "javax.persistence.query.timeout";
Query timeout in milliseconds.

Validation

	public static final String VALIDATION_MODE = "javax.persistence.validation.mode";
	public static final String VALIDATION_GROUP_PRE_PERSIST = "javax.persistence.validation.group.pre-persist";
	public static final String VALIDATION_GROUP_PRE_UPDATE = "javax.persistence.validation.group.pre-update";
	public static final String VALIDATION_GROUP_PRE_REMOVE = "javax.persistence.validation.group.pre-remove";
	public static final String VALIDATION_FACTORY = "javax.persistence.validation.factory";
Validation factory, validation mode (NONE, AUTO or CALLBACK), and validation groups for prePersist, preUpdate and preRemove events. If validation factory is not specified, a default factory will be built from a validation provider in classpath. The value of a validation group property is a list of fully qualified class names separated by comma.

Schema Generation

	public static final String SCHEMA_GENERATION_DB_ACTION = "javax.persistence.schema-generation.database.action";
	public static final String SCHEMA_GENERATION_SCRIPTS_ACTION = "javax.persistence.schema-generation.scripts.action";
	public static final String SCHEMA_GENERATION_CREATE_SOURCE = "javax.persistence.schema-generation.create-source";
	public static final String SCHEMA_GENERATION_DROP_SOURCE = "javax.persistence.schema-generation.drop-source";
	public static final String SCHEMA_GENERATION_SCRIPTS_CREATE_TARGET = "javax.persistence.schema-generation.scripts.create-target";
	public static final String SCHEMA_GENERATION_SCRIPTS_DROP_TARGET = "javax.persistence.schema-generation.scripts.drop-target";
	public static final String SCHEMA_GENERATION_CREATE_SCRIPT_SOURCE = "javax.persistence.schema-generation.create-script-source";
	public static final String SCHEMA_GENERATION_DROP_SCRIPT_SOURCE = "javax.persistence.schema-generation.drop-script-source";
	public static final String SQL_LOAD_SCRIPT_SOURCE = "javax.persistence.sql-load-script-source";
	public static final String SCHEMA_GENERATION_CONNECTION = "javax.persistence.schema-generation.connection";
	public static final String DATABASE_PRODUCT_NAME = "javax.persistence.database-product-name";
	public static final String DATABASE_MAJOR_VERSION = "javax.persistence.database-major-version";
	public static final String DATABASE_MINOR_VERSION = "javax.persistence.database-minor-version";
Schema generation properties:

Proprietary Properties

The followings are the list of Cmobilecom JPA-specific query properties/hints.

Android

	public static final String ANDROID_CONTEXT = "com.cmobilecom.jpa.android.context";
	public static final String ANDROID_CONNECTION_URL = "com.cmobilecom.jpa.android.connection.url";
Android context and URL for connecting to Android sqlite database.

Flush Before Query

	public static final String FLUSH_BEFORE_QUERY = "com.cmobilecom.jpa.query.flushBeforeQuery";
Specify whether to flush entities before executing query. Its value is true or false. default is true. It should be set to false to improve performance if there are changes in persistence context that will not affect query results.

Fetch Max Depth

	public static final String FETCH_MAX_DEPTH = "com.cmobilecom.jpa.query.fetchMaxDepth";
The max depth of fetches from explicit fetches and entity graph boundary. The depth of those in the boundary is 0, and the depth of direct fetches from the boundary is 1. Outside boundary, the depth of a fetch from a fetchParent of depth N is N+1. Default fetch max depth is 1.
	|--------------|
	|   depth:0    | -------- fetch --------- fetch ---------- fetch
	|--------------|         depth:1         depth:2          depth:3
	          boundary
The max depth of fetches from explicit fetch and entity graph boundary. The depth of those in the boundary is 0. Default value is 1.

On Delete Cascade

	public static final String PK_AS_FK_ON_DELETE_CASCADE = "com.cmobilecom.jpa.PKasFK.onDeleteCascade";
Specify whether ON DELETE CASCADE is enabled in database for primary key as foreign key constraints, including secondary tables, subclass entity tables for joined inheritance and OneToOne associations. Default is false. If it is enabled for the constraints in database, set this property to true in persistence units for better performance.

Schema generation will add "ON DELETE CASCADE" to such foreign key constraints. For example, ProjectDetail is a secondary table of entity table Project:

create table ProjectDetail(..., 
	CONSTRAINT FK_projectId FOREIGN KEY (projectId)	REFERENCES Project (id) ON DELETE CASCADE;
);

Return Generated Schema Objects

	public static final String SCHEMA_GENERATION_RETURN_SCHEMA_OBJECTS = "com.cmobilecom.jpa.schema-generation.return-schema-objects";
Schema generation property to return generated schema objects from metadata. If the property is set to true, its value will be set to the list of generated schema objects (type: List<String>). A schema object can be either table or sequence, and its naming format is: 0.tableName, 1.sequenceName, where object name is fully qualified if it does not belong to current database schema. For example, [0.Employee, 0.Employer, 1.Id_Gen_Sequence].

Return Generated SQL

For a JPA query(select, update, delete), there can be multiple SQL statements generated. To return generated SQL statements, set the following query property/hint:
	public static final String RETURN_SQL = "com.cmobilecom.jpa.query.return-sql";
If the property is set to a List(type: List<String>), generated SQL statements will be added to the list. The property is passed to methods of EntityManager, Query or TypedQuery as a hint. For example,
	TypedQuery<Project> query = em.createQuery("select p from Project p", Project.class);
	query.setHint(Constants.RETURN_SQL, new ArrayList<>());
	List<Project> projects = query.getResultList();
	List<String> generatedSQLs = (List<String>) properties.get(Constants.RETURN_SQL);
or
	List<String> generatedSQLs = new ArrayList<>();
	query.setHint(Constants.RETURN_SQL, generatedSQLs);

Distinct Mode

Distinct mode controls how "distinct" is applied to query. JPA query distinct eliminates duplicate references of same entities from result list, and SQL query distinct eliminates duplicate rows from query results. If there is no duplicate rows from SQL query, do not apply distinct to SQL query for better performance.
	public static final String DISTINCT_MODE = "com.cmobilecom.jpa.query.distinctMode";
The query hint specifies the distinct mode for distinct CriteriaQuery or JPQL query. Its value can be "jpa", "db" or "both"(default).

Multitenant Fetch Tenant

	public static final String MULTITENANT_FETCH_TENANT = "com.cmobilecom.jpa.multitenant.fetchTenant";
When multitenant is enabled, specify whether to fetch tenant info for query. Default is false. See Multitenant for detail.
Entity GraphValidationFrames / No Frames