Skip Headers

Oracle® Containers for J2EE Enterprise JavaBeans Developer's Guide 10g Release 3 (10.1.3) B14428-01 |
| Home | Solution Area | Contents | Index

Previous | Next |

# 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>` sub-element.

      The `<abstract-schema-name>` sub-element 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 sub-elements:

      - `<description>`: optional explanatory text

      - `<query-method>`: describes the finder method and includes the following sub-elements:

        `<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>` sub-element 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 an EJB 2.1 CMP Entity Bean Container-Managed Relationship Field".

## Using Java

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

Example 16-1 Finder Methods in an EJB 2.1 CMP Entity Bean 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. We 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:

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

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