Configuring TopLink Query Hints in a JPA Query

Table 8-1 lists the TopLink EJB 3.0 JPA persistence provider query hints you can specify when you construct a JPA query, as Example 8-5 shows, or when you specify a JPA query using the @QueryHint annotation, as Example 8-6 shows. When you set a hint, you can set the value using the corresponding public static final field in the appropriate configuration class in oracle.toplink.essentials.config as follows:

• PessimisticLock

• TopLinkQueryHints

• HintValues

Note:

To access these classes, put the appropriate OC4J persistence JAR on your classpath (see "JPA Persistence JAR Files").

Example 8-5 Specifying a TopLink JPA Query Hint

import oracle.toplink.essentials.config.HintValues;
import oracle.toplink.essentials.config.TopLinkQueryHints;

Customer customer = (Customer)entityMgr.createNamedQuery("findCustomerBySSN"). setParameter("SSN", "123-12-1234").setHint(TopLinkQueryHints.BIND_PARAMETERS, HintValues.PERSISTENCE_UNIT_DEFAULT).getSingleResult();

Example 8-6 Specifying a TopLink JPA Query Hint With @QueryHint

import oracle.toplink.essentials.config.HintValues;
import oracle.toplink.essentials.config.TopLinkQueryHints;

@Entity
@NamedQuery(
    name="findAllEmployees",
    query="SELECT * FROM EMPLOYEE WHERE MGR=1"
    hints={
        @QueryHint={name=TopLinkQueryHints.BIND_PARAMETERS, value=HintValues.PERSISTENCE_UNIT_DEFAULT}
    }
)
public class Employee implements Serializable {
    ...
}

Table 8-1 TopLink JPA Query Hints

Hint	Usage	Default
toplink.jdbc.bind-parameters	Control whether or not the query uses parameter binding. For more information, see "Parameterized SQL (Binding) and Prepared Statement Caching" in the Oracle TopLink Developer's Guide. Valid values: oracle.toplink.essentials.config.HintValues true: bind all parameters. false: do not bind all parameters. PersistenceUnitDefault: use the parameter binding setting made in your TopLink session's database login. For more information, see "Configuring JDBC Options" in the Oracle TopLink Developer's Guide. Example: JPA Query API import oracle.toplink.essentials.config.HintValues; import oracle.toplink.essentials.config.TopLinkQueryHints; query.setHint(TopLinkQueryHints.BIND_PARAMETERS, HintValues.TRUE); Example: @QueryHint import oracle.toplink.essentials.config.HintValues; import oracle.toplink.essentials.config.TargetDatabase; @QueryHint(name=TopLinkQueryHints.BIND_PARAMETERS, value=HintValues.PERSISTENCE_UNIT_DEFAULT);	PersistenceUnitDefault
toplink.pessimistic-lock	Control whether or not pessimistic locking is used. Valid values: oracle.toplink.essentials.config.PessimisticLock NoLock: pessimistic locking is not used. Lock: TopLink issues a SELECT.... FOR UPDATE. LockNoWait: TopLink issues a SELECT.... FOR UPDATE NO WAIT. Example: JPA Query API import oracle.toplink.essentials.config.PessimisticLock; import oracle.toplink.essentials.config.TopLinkQueryHints; query.setHint(TopLinkQueryHints.PESSIMISTIC_LOCK, PessimisticLock.LockNoWait); Example: @QueryHint import oracle.toplink.essentials.config.PessimisticLock; import oracle.toplink.essentials.config.TopLinkQueryHints; @QueryHint(name=TopLinkQueryHints.PESSIMISTIC_LOCK, value=PessimisticLock.LockNoWait);	NoLock
toplink.refresh	Control whether or not to update the TopLink session cache with objects that the query returns. Valid values: oracle.toplink.essentials.config.HintValues true: refresh cache. false: do not refresh cache. Example: JPA Query API import oracle.toplink.essentials.config.HintValues; import oracle.toplink.essentials.config.TopLinkQueryHints; query.setHint(TopLinkQueryHints.REFRESH, HintValues.TRUE); Example: @QueryHint import oracle.toplink.essentials.config.HintValues; import oracle.toplink.essentials.config.TopLinkQueryHints; @QueryHint(name=TopLinkQueryHints.REFRESH, value=HintValues.TRUE);	false