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 @NamedQueryjakarta.persistence.NamedQuery - JPA Annotation Declares a named query written in the Jakarta Persistence query language. annotation defines a query whose name is "Country.findAll" that retrieves all the Country objects in the database:

@NamedQueryjakarta.persistence.NamedQuery - JPA Annotation
 Declares a named query written in the Jakarta Persistence
 query language.(namejakarta.persistence.NamedQuery.name - JPA Annotation Attribute
 (Required) The name used to identify the query in calls to
 EntityManager#createNamedQuery.="Country.findAll", queryjakarta.persistence.NamedQuery.query - JPA Annotation Attribute
 (Required) The query string in the Jakarta Persistence
 query language.="SELECT c FROM Country c")

The @NamedQueryjakarta.persistence.NamedQuery - JPA Annotation Declares a named query written in the Jakarta Persistence query language. annotation contains four elements - two of which are required and two are optional. The two required elements, namejakarta.persistence.NamedQuery.name - JPA Annotation Attribute (Required) The name used to identify the query in calls to EntityManager#createNamedQuery. and queryjakarta.persistence.NamedQuery.query - JPA Annotation Attribute (Required) The query string in the Jakarta Persistence query language. define the name of the query and the query string itself and are demonstrated above. The two optional elements, lockModejakarta.persistence.NamedQuery.lockMode - JPA Annotation Attribute (Optional) The lock mode type to use in query execution. and hintsjakarta.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 @NamedQueryjakarta.persistence.NamedQuery - JPA Annotation Declares a named query written in the Jakarta 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 @NamedQueryjakarta.persistence.NamedQuery - JPA Annotation Declares a named query written in the Jakarta Persistence query language. to the Country entity class:

@Entityjakarta.persistence.Entity - JPA Annotation
 Declares that the annotated class is an entity.
@NamedQueryjakarta.persistence.NamedQuery - JPA Annotation
 Declares a named query written in the Jakarta Persistence
 query language.(namejakarta.persistence.NamedQuery.name - JPA Annotation Attribute
 (Required) The name used to identify the query in calls to
 EntityManager#createNamedQuery.="Country.findAll", queryjakarta.persistence.NamedQuery.query - JPA Annotation Attribute
 (Required) The query string in the Jakarta 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 @NamedQueriesjakarta.persistence.NamedQueries - JPA Annotation Declares multiple named Jakarta Persistence query language queries. annotation, as follows:

@Entityjakarta.persistence.Entity - JPA Annotation
 Declares that the annotated class is an entity.
@NamedQueries({
@NamedQueryjakarta.persistence.NamedQuery - JPA Annotation
 Declares a named query written in the Jakarta Persistence
 query language.(namejakarta.persistence.NamedQuery.name - JPA Annotation Attribute
 (Required) The name used to identify the query in calls to
 EntityManager#createNamedQuery.="Country.findAll",
    queryjakarta.persistence.NamedQuery.query - JPA Annotation Attribute
 (Required) The query string in the Jakarta Persistence
 query language.="SELECT c FROM Country c"),
@NamedQueryjakarta.persistence.NamedQuery - JPA Annotation
 Declares a named query written in the Jakarta Persistence
 query language.(namejakarta.persistence.NamedQuery.name - JPA Annotation Attribute
 (Required) The name used to identify the query in calls to
 EntityManager#createNamedQuery.="Country.findByName",
    queryjakarta.persistence.NamedQuery.query - JPA Annotation Attribute
 (Required) The query string in the Jakarta 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 @NamedQueryjakarta.persistence.NamedQuery - JPA Annotation Declares a named query written in the Jakarta 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 Queryjakarta.persistence.Query - JPA Interface Interface used to control query execution. and TypedQueryjakarta.persistence.TypedQuery - JPA Interface Interface used to control the execution of typed queries. interfaces but different EntityManagerjakarta.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 Jakarta Persistence query language named query. method receives a query name and a result type and returns a TypedQueryjakarta.persistence.TypedQuery - JPA Interface Interface used to control the execution of typed queries. instance:

    TypedQueryjakarta.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
 Jakarta 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 List<X>.();

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

    Queryjakarta.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 written in the Jakarta 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 Metamodeljakarta.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
 Obtain an instance of the Metamodel interface which
 provides access to metamodel objects describing the managed
 types belonging to 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.