Implementing an EJB 2.1 EJB QL Finder Method

The following procedure describes how to implement an EJB 2.1 EJB QL finder method.

Before implementing a finder method, consider the predefined and default finders that OC4J provides (see "Predefined TopLink Finders" and "Default TopLink Finders").

For more information, see "Understanding Finder Methods".

1. Define the finder method in the home interface (see "Using Java").

   If you are exposing only predefined or default finders (see "Predefined TopLink Finders" and "Default TopLink Finders"), you are done.

   If you are exposing a custom finder, proceed to step 2.

2. Configure the ejb-jar.xml file (see "Using Deployment XML").

   Note:

   You can do this manually as described here or you can use the TopLink Workbench (see "Using TopLink Workbench") to automate this step and to take advantage of advanced TopLink finder configuration.

   1. For each entity bean that you plan to reference in your EJB QL query, configure the <entity> element <abstract-schema-name> subelement.

      The <abstract-schema-name> subelement defines the name that identifies the entity bean in the EJB QL statement. For example, given an entity bean class named EmpBean, if you define its <abstract-schema-name> as Employee, then in your EJB QL statement, when you use the name Employee, the container will map that name to the EmpBean entity bean (see Example 16-2).

   2. Define a <query> element for each finder method that you exposed in the EJB home interface.

      Note:

      Do not define a <query> element for predefined or default finders, including findByPrimaryKey.

      The <query> element has the following subelements:

      • <description>: optional explanatory text.

      • <query-method>: describes the finder method and includes the following subelements:

        <method-name>: identifies the finder method. Configure this element with the same method name as defined in the home interface.

        <method-params>: if the finder takes arguments, define this element and for each argument, define a <method-param> subelement that gives the argument type. The type and order of arguments must match that specified by this finder's signature.

      • <ejb-ql>: contains the EJB QL statement for this method.

        You can define a full query or just the conditional statement (the WHERE clause).

        If the finder method returns a Collection, to ensure that no duplicates are returned, specify the DISTINCT keyword in the EJB QL statement.

        To use parameters (as specified by <method-params>) in your EJB QL, use the <integer>? notation where <integer> begins with 1. For example,?1 corresponds to the first <method-param> element,?2 corresponds to the second <method-param> element, and so on (see the findAllByEmpName finder in Example 16-2).

        To define an EJB QL statement that relates this EJB with another, you must first define the appropriate container-managed relationship. The findByDeptNo finder in Example 16-2 requires the relationship with <ejb-relation-name> Employee-Departments. For more information, see "Configuring a Container-Managed Relationship Field for an EJB 2.1 Entity Bean With Container-Managed Persistence".

Using Java

Example 16-1 shows a remote home interface called EmpBeanHome.

Example 16-1 Finder Methods in an EJB 2.1 Entity Bean With Container-Managed Persistence Remote Home Interface

package cmpapp;

import javax.ejb.*;
import java.rmi.*;

public interface EmpBeanHome extends EJBHome {
    public EmpBean create(Integer empNo, String empName) throws CreateException;

    /**
     * Finder methods. These are implemented by the container. You can
     * customize the functionality of these methods in the deployment
     * descriptor through EJB-QL.
     **/

// Predefined Finders: <query> element in ejb-jar.xml not required

    public Topic findByPrimaryKey(Integer key) throws FinderException;
    public Collection findManyBySQL(String sql, Vector args) throws FinderException

// Default Finder: <query> element in ejb-jar.xml not required

    public Topic findByEmpNo(Integer empNo) throws FinderException;

// Custom Finders: <query> element is required in ejb-jar.xml

    public Collection findAllRegionalEmployees(Integer empNo) throws FinderException;
    public Collection findAllByEmpName(String empName) throws FinderException;
    public Topic findByDeptNo(Integer deptNo) thorws FinderException
    public Collection findAllBetweenSalaries(Integer lowSalary, Integer highSalary);

}

Using Deployment XML

Example 16-2 shows the ejb-jar.xml for the finders declared in the home interface that Example 16-1 shows.

Example 16-2 ejb-jar.xml For EJB 2.1 EJB QL Finders

<enterprise-beans>
    <entity>
        <display-name>EmpBean</display-name>
        <ejb-name>EmpBean</ejb-name>
        ...
        <abstract-schema-name>Employee</abstract-schema-name>
        <cmp-field><field-name>empNo</field-name></cmp-field>
        <cmp-field><field-name>empName</field-name></cmp-field>
        <cmp-field><field-name>salary</field-name></cmp-field>
        <primkey-field>empNo</primkey-field>
        <prim-key-class>java.lang.Integer</prim-key-class>
        ...
        <query>
            <description>Regional employees have empNo greater than 10000</description>
            <query-method>
                    <method-name>findAllRegionalEmployees</method-name>
                    <method-params></method-params>
            </query-method>
            <ejb-ql>SELECT OBJECT(e) FROM Employee e WHERE e.empNo > 10000</ejb-ql>
        </query>
        <query>
            <description>Find all employees with the given name</description> 
            <query-method>
                <method-name>findAllByEmpName</method-name>
                <method-params>
                    <method-param>java.lang.String</method-param>
                </method-params>
            </query-method>
            <ejb-ql>SELECT OBJECT(e) FROM Employee e WHERE e.empName = ?1</ejb-ql>
        </query>
        <query>
            <description>Relationship finder</description>
            <query-method>
                <method-name>findByDeptNo</method-name>
                <method-params>
                    <method-param>java.lang.Integer</method-param>
                </method-params>
            </query-method>
            <ejb-ql>
              SELECT DISTINCT OBJECT(e) From Employee e, IN (e.dept) AS d WHERE d.deptNo = ?1
           </ejb-ql>
        </query>
        <query>
            <description>Find all employees with salaries in the given range</description> 
            <query-method>
                <method-name>findAllBetweenSalaries</method-name>
                <method-params>
                    <method-param>java.lang.Integer</method-param>
                    <method-param>java.lang.Integer</method-param>
                </method-params>
            </query-method>
            <ejb-ql>
                SELECT  OBJECT (e) FROM Employee e WHERE e.salary BETWEEN ?1 and ?2
            </ejb-ql>
        </query>
    ...
    </entity>
...
</enterprise-beans>
<relationships>
    <ejb-relation>
        <ejb-relation-name>Employee-Departments</ejb-relation-name>
        <ejb-relationship-role>
            <ejb-relationship-role-name>Employee-has-Departments</ejb-relationship-role-name>
            <multiplicity>One</multiplicity>
            <relationship-role-source>
                <ejb-name>Department</ejb-name>
            </relationship-role-source>
            <cmr-field>
                <cmr-field-name>dept</cmr-field-name>
                <cmr-field-type>java.lang.Integer</cmr-field-type>
            </cmr-field>
        </ejb-relationship-role>
    <ejb-relation>
...
<relationships>

Using TopLink Workbench

Using the TopLink Workbench, you can configure your toplink-ejb-jar.xml file with a custom TopLink finder and update your ejb-jar.xml file.

For more information, see the following:

• "Creating a Finder" in the Oracle TopLink Developer's Guide

• "Configuring Named Queries at the Descriptor Level" in the Oracle TopLink Developer's Guide