Index: openjpa-project/src/doc/manual/jpa_overview_query.xml
===================================================================
--- openjpa-project/src/doc/manual/jpa_overview_query.xml (revision 564408)
+++ openjpa-project/src/doc/manual/jpa_overview_query.xml (working copy)
@@ -640,6 +640,159 @@
parameter, then executes the query with those values.
+
+
+ Query Hints
+
+
+JPQL provides support for hints which are name/value pairs used to control locking and optimization keywords in sql.
+The following example shows how to use the JPA hint api to set the ReadLockMode and ResultCount in the OpenJPA fetch plan. This will result in the sql keywords OPTIMIZE FOR 2 ROWS and UPDATE to be emitted into the sql provided that a pessimistic LockManager is being used.
+
+
+
+ Query Hints
+
+
+...
+Query q = em.createQuery("select m from Magazine m where ... ");
+q.setHint("openjpa.hint.OptimizeResultCount", new Integer(2));
+q.setHint("openjpa.FetchPlan.ReadLockMode","WRITE");
+List r = q.getResultList();
+...
+
+
+
+Invalid hints or hints which can not be processed by a particular database are ignored. Otherwise, invalid hints will result in an ArgumentException being thrown.
+
+
+
+ Locking Hints
+
+
+To avoid deadlock and optimistic update exceptions among multiple updaters, use a pessimistic LockManager, specified in the persistence unit definition, and use a hint name of "openjpa.FetchPlan.ReadLockMode" on queries for entities that must be locked for serialization. The value of ReadLockMode can be either "READ" or "WRITE". This results in FOR UPDATE or USE AND KEEP UPDATE LOCKS in sql.
+
+
+Using a ReadLockMode hint with JPA optimistic locking ( i.e. specifying LockManager = "version") will result in the entity version field either being reread at end of transaction in the case of a value of "READ" or the version field updated at end of transaction in the case of "WRITE". You must define a version field in the entity mapping when using a version LockManager and using ReadLockMode.
+
+
+
+ Interaction of ReadLockMode hint and LockManager
+
+
+
+
+
+
+
+
+ ReadLockMode
+
+
+ LockManager=pessimistic
+
+
+ LockManager=version
+
+
+
+
+
+
+ READ
+
+
+ sql with UPDATE
+
+ sql without update;
+
+reread version field at the end of transaction and check for no change.
+
+
+
+
+
+ WRITE
+
+
+ sql with UPDATE
+
+
+ sql without update;
+
+force update version field at the end of transaction
+
+
+
+
+
+ not specified
+
+
+ sql without update
+
+
+ sql without update
+
+
+
+
+
+
+
+
+ Result Set Size Hint
+
+
+To specify a result set size hint to those databases that support it, specify a hint name of "openjpa.hint.OptimizeResultCount" with an integer value greater than zero. This causes the sql keyword OPTIMIZE FOR to be generated.
+
+
+
+
+ Isolation Level Hint
+
+
+To specify an isolation level, specify a hint name of "openjpa.FetchPlan.Isolation". The value will be used to specify isolation level using the sql WITH <isolation> clause for those databases that support it. This hint only works in conjunction with the ReadLockMode hint.
+
+
+
+
+ Other Fetchplan Hints
+
+
+Any property of an OpenJPA FetchPlan can be changed using a hint by using a name of the form "openjpa.FetchPlan."<property name>.Valid property names include :
+MaxFetchDepth, FetchBatchSize, LockTimeOut, EagerFetchMode, SubclassFetchMode and Isolation.
+
+
+
+
+ Oracle Query Hints
+
+
+The hint name "openjpa.hint.OracleSelectHint" can be used to specify a string value of an Oracle query hint that will inserted into sql for an Oracle database.See for an example.
+
+
+
+
+ Named Query Hints
+
+
+Hints can also be included as part of a NamedQuery definition.
+
+
+
+ Named Query using Hints
+
+
+...
+@NamedQuery(name=" magsOverPrice",
+query="SELECT x FROM Magazine x WHERE x.price > ?1",
+hints={ @QueryHint (name="openjpa.hint.OptimizeResultCount", value="2"),
+ @QueryHint (name="openjpa.FetchPlan.ReadLockMode",value="WRITE")} )
+...
+
+
+
+