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.NamedQueryDeclares 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.NamedQueryDeclares a named query written in the Jakarta Persistence query language.(namejakarta.persistence.NamedQuery.name(Required) The name used to identify the query in calls to EntityManager.createNamedQuery.="Country.findAll", queryjakarta.persistence.NamedQuery.query(Required) The query string in the Jakarta Persistence query language.="SELECT c FROM Country c")

The @NamedQueryjakarta.persistence.NamedQueryDeclares 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(Required) The name used to identify the query in calls to EntityManager.createNamedQuery. and queryjakarta.persistence.NamedQuery.query(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(Optional) The lock mode type to use in query execution. and hintsjakarta.persistence.NamedQuery.hints(Optional) Query properties and hints., provide static replacement for the setLockModejakarta.persistence.Query.setLockMode(LockModeType)Set the lock mode type to be used for the query execution. and setHintjakarta.persistence.Query.setHint(String,Object)Set a query property or hint. methods.

Every @NamedQueryjakarta.persistence.NamedQueryDeclares 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.NamedQueryDeclares a named query written in the Jakarta Persistence query language. to the Country entity class:

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

@Entityjakarta.persistence.EntityDeclares that the annotated class is an entity.
@NamedQueries({
@NamedQueryjakarta.persistence.NamedQueryDeclares a named query written in the Jakarta Persistence query language.(namejakarta.persistence.NamedQuery.name(Required) The name used to identify the query in calls to EntityManager.createNamedQuery.="Country.findAll",
    queryjakarta.persistence.NamedQuery.query(Required) The query string in the Jakarta Persistence query language.="SELECT c FROM Country c"),
@NamedQueryjakarta.persistence.NamedQueryDeclares a named query written in the Jakarta Persistence query language.(namejakarta.persistence.NamedQuery.name(Required) The name used to identify the query in calls to EntityManager.createNamedQuery.="Country.findByName",
    queryjakarta.persistence.NamedQuery.query(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.NamedQueryDeclares 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.QueryInterface used to control query execution. and TypedQueryjakarta.persistence.TypedQueryInterface used to control the execution of typed queries. interfaces but different EntityManagerjakarta.persistence.EntityManagerInterface used to interact with the persistence context. factory methods are used to instantiate them. The createNamedQueryjakarta.persistence.EntityManager.createNamedQuery(String,Class)Create an instance of TypedQuery<X> for executing a Jakarta Persistence query language named query. method receives a query name and a result type and returns a TypedQueryjakarta.persistence.TypedQueryInterface used to control the execution of typed queries. instance:

    TypedQueryjakarta.persistence.TypedQueryInterface used to control the execution of typed queries.<Country> query =
        em.createNamedQueryjakarta.persistence.EntityManager.createNamedQuery(String,Class)Create an instance of TypedQuery<X> for executing a Jakarta Persistence query language named query.("Country.findAll", Country.class);
    List<Country> results = query.getResultListjakarta.persistence.TypedQuery.getResultList()Execute a SELECT query and return the query results as a typed List<X>.();

Another form of createNamedQueryjakarta.persistence.EntityManager.createNamedQuery(String)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.QueryInterface used to control query execution. instance:

    Queryjakarta.persistence.QueryInterface used to control query execution. query = em.createNamedQueryjakarta.persistence.EntityManager.createNamedQuery(String)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.getResultListjakarta.persistence.Query.getResultList()Execute a SELECT query and return the query results as an untyped List<E>.();

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.MetamodelProvides access to the metamodel of persistent entities in the persistence unit. interface. For example:

    em.getMetamodeljakarta.persistence.EntityManager.getMetamodel()Obtain an instance of the Metamodel interface which provides access to metamodel objects describing the managed types belonging to the persistence unit.().managedTypejakarta.persistence.metamodel.Metamodel.managedType(Class)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.