8 Using EJB 3.0 Query API

This section describes how to create pre-defined, static queries that you can access at runtime, including:

Implementing an EJB 3.0 Named Query
Implementing an EJB 3.0 Dynamic Query

Note:

In this release, OC4J supports a subset of the functionality specified in the EJB 3.0 public review draft. You may need to make code changes to your EJB 3.0 OC4J application after the EJB 3.0 specification is finalized and OC4J is updated to full EJB 3.0 compliance. For more information, see "Understanding EJB Support in OC4J".

There are no OC4J-proprietary EJB 3.0 annotations. For all OC4J-specific configuration, you must still use the EJB 2.1 orion-ejb-jar.xml file.

For more information, see "How Do You Query for an EJB 3.0 Entity?".

Implementing an EJB 3.0 Named Query

A named query is a pre-defined query that you create and associate with a CMP entity (see "Using Annotations"). At deployment time, OC4J stores named queries on the EntityManager (see "How Do You Query for an EJB 3.0 Entity?").

At runtime, you can use the EntityManager to acquire, configure, and execute a named query (see "Querying for an EJB 3.0 Entity Using the EntityManager").

Note:

In this release, OC4J does not support EJB 3.0 named queries using native SQL. For more information, see "Understanding Native SQL Query Syntax".

Using Annotations

Example 8-1 shows how to use the @NamedQuery annotation to define an EJB QL query that you can acquire by name findAllEmployeesByFirstName at runtime using the EntityManager.

Example 8-1 Implementing a Query Using @NamedQuery

@Entity
@NamedQuery(
    name="findAllEmployeesByFirstName",
    queryString="SELECT OBJECT(emp) FROM Employee emp WHERE emp.firstName = 'John'"
)
public class Employee implements Serializable
{
...
}

Example 8-2 shows how to use the @NamedQuery annotation to define an EJB QL query that takes a parameter named firstname. Example 8-3 shows how you use the EntityManager to acquire this query and use Query method setParameter to set the firstname parameter. For more information on using the EntityManager with named queries, see "Querying for an EJB 3.0 Entity Using the EntityManager".

Example 8-2 Implementing a Query with Parameters Using @NamedQuery

@Entity
@NamedQuery(
    name="findAllEmployeesByFirstName",
    queryString="SELECT OBJECT(emp) FROM Employee emp WHERE emp.firstName = :firstname"
)
public class Employee implements Serializable
{
...
}

Example 8-3 Setting Parameters in a Named Query

Query queryEmployeesByFirstName = em.createNamedQuery("findAllEmployeesByFirstName");
queryEmployeeByFirstName.setParameter("firstName", "John");
Collection employees = queryEmployessByFirstName.getResultList();

Implementing an EJB 3.0 Dynamic Query

Using EntityManager methods createQuery and createNativeQuery(String sqlString, Class resultType), you can create a Query object dynamically at runtime (see "Using Java").

Using the Query methods getResultList, getSingleResult, or executeUpdate you can execute the query (see "Executing a Query").

For more information, see:

Using Java

Example 8-4 shows how to create a dynamic EJB QL query with parameters and how to execute the query. In this example, the query returns multiple results so we use Query method getResultList.

Example 8-4 Implementing and Executing a Dynamic Query

Query queryEmployees = entityManager.createQuery(
    "SELECT OBJECT(emp) FROM Employee emp WHERE emp.firstName = :firstname"
);

queryEmployeeByFirstName.setParameter("firstName", "Joan");

Collection employees = queryEmployees.getResultList();