Oracle® Containers for J2EE Enterprise JavaBeans Developer's Guide 10g (10.1.3.5.0) Part Number E13981-01 |
|
|
View PDF |
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".
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.
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.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).
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".
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); }
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 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