Implementing EJB QL Select Methods

Select methods (ejbSelect) are used to retrieve entity bean references or values of container-managed persistent or relationship fields (see "Understanding Select Methods").

The format for an ejbSelect method definition is as follows:

public abstract type ejbSelect<METHOD>(...);

Although the select method is not based on the identity of the entity bean instance on which it is invoked, it can use the primary key of an entity bean as an argument. This creates a query that is logically scoped to a particular entity bean instance. For information on how to define the select method return type, see "Defining the Return Type for the Select Method".

To define a select method, follow this procedure:

Define an ejbSelect<NAME> method in the bean class for each select method. Each method is defined as public abstract. The SQL that is necessary for this method is not included in the implementation.
Define the full query or the conditional statement alone (the WHERE clause) for the select method in the deployment descriptor. An EJB QL statement is created for each select method in its own <query> element. The container uses this statement to translate the condition into the relevant SQL statements.

Note:

You cannot modify the query statement for an ejbSelect method in the orion-ejb-jar.xml file, as you can for finder methods.

Example 6-6 Defining the Select Method in the Bean Class

Example 6-6 demonstrates the definition of a select method to retrieve all employees whose salary falls within a specified range:

public abstract Collection ejbSelectBySalaryRange(Float s1, Float s2) throws FinderException;

Because the preceding select method retrieves multiple employees, a Collection is returned. The low and high ends of the salary range are input parameters, which are substituted in the EJB QL for?1 and ?2 parameters. The first input parameter is returned in?1; the second input parameter is returned in ?2. The order of the all declared method parameters is the same as the order of the ?1, ?2, ... ?n EJB QL parameters.

Example 6-7 Providing the Select Method Definition in the Deployment Descriptor

Each select method is defined in the deployment descriptor in a <query> element. Example 6-7 shows the deployment descriptor for the ejbSelectBySalaryRange method defined in the bean class in Example 6-6:

<query>
    <description></description>
    <query-method>
        <method-name>ejbSelectBySalaryRange</method-name>
        <method-params>
            <method-param>java.lang.Float</method-param>
            <method-param>java.lang.Float</method-param>
        </method-params>
    </query-method>
    <ejb-ql>SELECT DISTINCT OBJECT(emp) From Employee emp 
            WHERE emp.salary BETWEEN ?1 AND ?2</ejb-ql>
</query>

The ejbSelectBySalaryRange method has two input parameters of type float. The types of these expected input parameters are defined in the <method-param> elements.

The EJB QL is defined in the <ejb-ql> element. The ejbSelectBySalaryRange method evaluates the persistent field of salary within the EJB QL statement by the emp.salary. The emp represents the Employee object; the salary represents the persistent field within that object. The separating period between them indicates the relationship between the entity bean and its persistent field.

The two input parameters designate the low and high salary ranges and are substituted in the ?1 and ?2 positions respectively.

The ejbSelectBySalaryRange method returns objects, where the DISTINCT keyword ensures that no duplicate records are returned.

Note:

Select methods must throw FinderException.

Defining the Return Type for the Select Method

The following is the list of conditions that you must consider when defining return types for your select methods:

If the select method does not find any objects, a FinderException is raised.
If you want your select method to find a single object, the container returns the same type as returned in the ejbSelect<NAME> method. If multiple objects are returned, a FinderException is raised.
If you want your select method to find multiple objects, you must define the return type of the ejbSelect<NAME> method as either a Set or Collection. A Set eliminates duplicates. A Collection may include duplicates. For example, if you want to retrieve all zip codes of all customers, use a Set to eliminate duplicates. To retrieve all customer names, use a Collection to retrieve the full list. An empty Collection or Set is returned if no matches are found.
- If your select method returns a bean interface, the default interface type returned within the Set or Collection is the local bean interface. You can change this to the remote bean interface in the <result-type-mapping> element, as follows:
```
<result-type-mapping>Remote</result-type-mapping>
```
- If your select method returns a Set or Collection of CMP values, the container determines the object type from the EJB QL select statement.