JPA Named Queries

A named query is a statically defined query with a predefined unchangeable query string. Using named queries instead of dynamic queries may improve code organization by separating the JPQL query strings from the Java code. It also enforces the use of query parameters rather than embedding literals dynamically into the query string and results in more efficient queries.

@NamedQuery and @NamedQueries Annotations

The following @NamedQueryjavax.persistence.NamedQuery - JPA Annotation Specifies a static, named query in the Java Persistence query language. annotation defines a query whose name is "Country.findAll" that retrieves all the Country objects in the database:

@NamedQueryjavax.persistence.NamedQuery - JPA Annotation
 Specifies a static, named query in the Java Persistence query language.(namejavax.persistence.NamedQuery.name - JPA Annotation Attribute
 (Required) The name used to refer to the query with the EntityManager
 methods that create query objects.="Country.findAll", queryjavax.persistence.NamedQuery.query - JPA Annotation Attribute (Required)
 The query string in the Java Persistence query language.="SELECT c FROM Country c")

The @NamedQueryjavax.persistence.NamedQuery - JPA Annotation Specifies a static, named query in the Java Persistence query language. annotation contains four elements - two of which are required and two are optional. The two required elements, namejavax.persistence.NamedQuery.name - JPA Annotation Attribute (Required) The name used to refer to the query with the EntityManager methods that create query objects. and queryjavax.persistence.NamedQuery.query - JPA Annotation Attribute (Required) The query string in the Java Persistence query language. define the name of the query and the query string itself and are demonstrated above. The two optional elements, lockModejavax.persistence.NamedQuery.lockMode - JPA Annotation Attribute (Optional) The lock mode type to use in query execution. and hintsjavax.persistence.NamedQuery.hints - JPA Annotation Attribute (Optional) Query properties and hints., provide static replacement for the setLockModeQuery.setLockMode(lockMode) - JPA Method Set the lock mode type to be used for the query execution. and setHintQuery.setHint(hintName,value) - JPA Method Set a query property or hint. methods.

Every @NamedQueryjavax.persistence.NamedQuery - JPA Annotation Specifies a static, named query in the Java Persistence query language. annotation is attached to exactly one entity class or mapped superclass - usually to the most relevant entity class. But since the scope of named queries is the entire persistence unit, names should be selected carefully to avoid collision (e.g. by using the unique entity name as a prefix).

It makes sense to add the above @NamedQueryjavax.persistence.NamedQuery - JPA Annotation Specifies a static, named query in the Java Persistence query language. to the Country entity class:

@Entityjavax.persistence.Entity - JPA Annotation
 Specifies that the class is an entity.
@NamedQueryjavax.persistence.NamedQuery - JPA Annotation
 Specifies a static, named query in the Java Persistence query language.(namejavax.persistence.NamedQuery.name - JPA Annotation Attribute
 (Required) The name used to refer to the query with the EntityManager
 methods that create query objects.="Country.findAll", queryjavax.persistence.NamedQuery.query - JPA Annotation Attribute (Required)
 The query string in the Java Persistence query language.="SELECT c FROM Country c") 
public class Country {
    ...
}

Attaching multiple named queries to the same entity class requires wrapping them in a @NamedQueriesjavax.persistence.NamedQueries - JPA Annotation Specifies multiple named Java Persistence query language queries. annotation, as follows:

@Entityjavax.persistence.Entity - JPA Annotation
 Specifies that the class is an entity.
@NamedQueries({
@NamedQueryjavax.persistence.NamedQuery - JPA Annotation
 Specifies a static, named query in the Java Persistence query language.(namejavax.persistence.NamedQuery.name - JPA Annotation Attribute
 (Required) The name used to refer to the query with the EntityManager
 methods that create query objects.="Country.findAll",
    queryjavax.persistence.NamedQuery.query - JPA Annotation Attribute (Required)
 The query string in the Java Persistence query language.="SELECT c FROM Country c"),
@NamedQueryjavax.persistence.NamedQuery - JPA Annotation
 Specifies a static, named query in the Java Persistence query language.(namejavax.persistence.NamedQuery.name - JPA Annotation Attribute
 (Required) The name used to refer to the query with the EntityManager
 methods that create query objects.="Country.findByName",
    queryjavax.persistence.NamedQuery.query - JPA Annotation Attribute (Required)
 The query string in the Java Persistence query language.="SELECT c FROM Country c WHERE c.name = :name"),
}) 
public class Country {
...
}

Note: Named queries can be defined in JPA XML mapping files instead of using the @NamedQueryjavax.persistence.NamedQuery - JPA Annotation Specifies a static, named query in the Java Persistence query language. annotation. ObjectDB supports JPA XML mapping files, including the definition of named queries. But, because mapping files are useful mainly for Object Relational Mapping (ORM) JPA providers and less so when using ObjectDB, this alternative is not covered in this manual.

Using Named Queries at Runtime

Named queries are represented at runtime by the same Queryjavax.persistence.Query - JPA Interface Interface used to control query execution. and TypedQueryjavax.persistence.TypedQuery - JPA Interface Interface used to control the execution of typed queries. interfaces but different EntityManagerjavax.persistence.EntityManager - JPA Interface Interface used to interact with the persistence context. factory methods are used to instantiate them. The createNamedQueryEntityManager.createNamedQuery(name,resultClass) - JPA Method Create an instance of TypedQuery for executing a Java Persistence query language named query. method receives a query name and a result type and returns a TypedQueryjavax.persistence.TypedQuery - JPA Interface Interface used to control the execution of typed queries. instance:

    TypedQueryjavax.persistence.TypedQuery - JPA Interface
 Interface used to control the execution of typed queries.<Country> query =
        em.createNamedQueryEntityManager.createNamedQuery(name,resultClass) - JPA Method
 Create an instance of TypedQuery for executing a
 Java Persistence query language named query.("Country.findAll", Country.class);
    List<Country> results = query.getResultListTypedQuery.getResultList() - JPA Method
 Execute a SELECT query and return the query results
 as a typed List.();

Another form of createNamedQueryEntityManager.createNamedQuery(name) - JPA Method Create an instance of Query for executing a named query (in the Java Persistence query language or in native SQL). receives a query name and returns a Queryjavax.persistence.Query - JPA Interface Interface used to control query execution. instance:

    Queryjavax.persistence.Query - JPA Interface
 Interface used to control query execution. query = em.createNamedQueryEntityManager.createNamedQuery(name) - JPA Method
 Create an instance of Query for executing a named query
 (in the Java Persistence query language or in native SQL).("Country.findAll");
    List results = query.getResultListQuery.getResultList() - JPA Method
 Execute a SELECT query and return the query results
 as an untyped List.();

One of the reasons that JPA requires the listing of managed classes in a persistence unit definition is to support named queries. Notice that named queries may be attached to any entity class or mapped superclass. Therefore, to be able to always locate any named query at runtime a list of all these managed persistable classes must be available.

ObjectDB makes the definition of a persistence unit optional. Named queries are automatically searched for in all the managed classes that ObjectDB is aware of, and that includes all the entity classes that have objects in the database. However, an attempt to use a named query still might fail if that named query is defined on a class that is still unknown to ObjectDB.

As a workaround, you may introduce classes to ObjectDB before accessing named queries, by using the JPA 2 Metamodeljavax.persistence.metamodel.Metamodel - JPA Interface Provides access to the metamodel of persistent entities in the persistence unit. interface. For example:

    em.getMetamodelEntityManager.getMetamodel() - JPA Method
 Return an instance of Metamodel interface for access to the
 metamodel of the persistence unit.().managedTypeMetamodel.managedType(cls) - JPA Method
  Return the metamodel managed type representing the
  entity, mapped superclass, or embeddable class.(MyEntity.class);

Following the above code ObjectDB will include MyEntity in searching named queries.