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:

argument to method of Query, TypedQuery, EntityManager
NamedQuery (xml or annotation)
argument of createEntityManager
argument of createEntityManagerFactory
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:

Database action: none, create, drop-and-create or drop.
Scripts action: none, create, drop-and-create or drop.
Create source: metadata, script, metadata-then-script or script-then-metadata.
Drop source: metadata, script, metadata-then-script or script-then-metadata.
Script create target: where to write create SQL (java.io.Writer or URL string).
Script drop target: where to write drop SQL (java.io.Writer or URL string).
Create script source: where to read create SQL (java.io.Reader or URL string).
Drop script source: where to read drop SQL (java.io.Reader or URL string).
SQL load script source: data loading SQL (java.io.Reader or URL string).
Connection: JDBC connection for database action. Not applicable for android.
Database name and version.

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);

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

jpa: distinct applies to JPA, not database.
db: distinct applies to database, not JPA.
both: distinct applies to both JPA and database. This is default.

Application Managed Multitenancy

	public static final String MULTITENANT_APP_MANAGED = "com.cmobilecom.jpa.multitenant.appManaged";

Specify whether multitenancy is managed by application or Cmobilecom-JPA. If this property is false or not specified, default to Cmobilecom-JPA managed multitenancy. This property can be set in query hints, EntityManager, EntityManagerFactory or META-INF/persistence.xml. See Multitenant for detail.

	public static final String MULTITENANT_APP_MANAGED_SUPPORTED = "com.cmobilecom.jpa.multitenant.appManaged.supported";

Specify whether application-managed multitenancy is supported to enforce the validation of the metamodel being built, which verifies that entity identifiers are unique among all tenants. This property can be set in EntityManagerFactory or META-INF/persistence.xml.

	public static final String MULTITENANT_FETCH_TENANT_ATTR = "com.cmobilecom.jpa.multitenant.fetchTenantAttr";

Specify whether to fetch entity's tenant attributes when multitenancy is managed by JPA (i.e., MULTITENANT_APP_MANAGED is false). Default is false.

	public static final String MULTITENANT_TENANT = "com.cmobilecom.jpa.multitenant.tenant";

Persist/merge entity tenant hint. If entity multitenancy is managed by JPA and an entity type is multitenant-enabled, the tenant hint provides multitenant attribute value for entities to be persisted or merged. The tenant hint also applies to cascaded(persist or merge) entities. If an entity tenant is already set and different from tenant hint, PersistenceException will be raised.

	public static final String MULTITENANT_TENANT_SKIP_MANAGED = "com.cmobilecom.jpa.multitenant.tenant.shipManaged";

Persist/merge hint on whether to ship already manged entities for MULTITENANT_TENANT hint.

See Multitenant on how to use Cmobilecom JPA ExtendedEntityManager and how to pass tenant-related hints to persist() and merge() methods.

Metamodel Lazy Initialization

	public static final String METAMODEL_LAZY_INIT = "com.cmobilecom.jpa.metamodel.lazyInit";

This property specifies whether metamodel lazy initialization is enabled. Metamodel lazy initialization provides on-demand minimal initialization and thus better responsiveness, but it is not multi-threading safe. Turn it ON (true) only for a single-threading environment. It can be set in META-INF/persistence.xml or when creating EntityManagerFactory at runtime. Default is false.

← Entity Graph→ ValidationFrames / No Frames