Enterprise JavaBeans 3.1, 6th Edition

Named Queries

Java Persistence provides a mechanism so that you can predefine JPA QL or native SQL queries and reference them by name when creating a query. You would want to predeclare queries for the same reason you create String constant variables in Java: to reuse them in multiple situations. If you predefine your queries in one place, you have an easy way to fine-tune or modify them as time goes on. The @javax.persistence.NamedQuery annotation is used for predefining JPA QL queries:

package javax.persistence;

public @interface NamedQuery {
   String name( );
   String query( );
   QueryHint[] hints( ) default {};
}

public @interface QueryHint {
   String name( );
   String value( );
}

public @interface NamedQueries {
   NamedQuery[] value( );
}

You use the @javax.persistence.NamedQueries annotation when you are declaring more than one query on a class or package. The @javax.persistence.QueryHint annotation declares vendor-specific hints. These hints work in the same way as the Query.setHint() method described earlier in this chapter. Here’s an example:

@NamedQueries({
   @NamedQuery
(name="getAverageProductOrderAmount",
               query=
                 "SELECT AVG( o.amountPaid )
                  FROM ProductOrder as o")
})
@Entity
public class ProductOrder {...}

This example declares a JPA QL query on the ProductOrder entity bean class. You can then reference these declarations in the EntityManager.createNamedQuery() method:

Query query = em.createNamedQuery("getAverageProductOrderAmount");

Named Native Queries

The @javax.persistence.NamedNativeQuery ...