Implementing an EJB 2.1 EJB QL Select Method

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

For more information, see "Understanding Select Methods".

1. Define the select method as a public, abstract method of your abstract entity bean class (see "Using Java").

2. In the ejb-jar.xml file (see "Using Deployment XML"), do the following:

   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 your <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.

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

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

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

      The <query> element has the following two main elements:

      • The <method-name> element identifies the select method: configure this element with the same name as defined in the bean class.

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

   3. If the query returns a Collection of CMR values, decide on the interface type you want returned:

      The ejb-jar.xml file <result-type-mapping> element determines the return type for select methods. Set the flag to Remote to return EJBObjects; set it to Local to return EJBLocalObjects.

Using Java

Example 16-3 shows an abstract entity bean class called UserAccountBean for an EJB 2.1 entity bean with container-managed persistence with select methods.

Example 16-3 Implementation of an EJB 2.1 Entity Bean With Container-Managed Persistence With Select Methods

package oracle.otnsamples.ejbql;

import javax.ejb.*;
import java.util.*;

public abstract class UserAccountBean implements EntityBean {

    // Non-Persistent State

    protected EntityContext ctx;

    /**
     * Begin abstract get/set methods. Container-managed
     * persistent fields are specified in the ejb-jar.xml 
     * deployment descriptor.
     */

    public abstract Long getAccountnumber();
    public abstract void setAccountnumber(Long newAccountnumber);
 
    public abstract Long getCreditlimit();
    public abstract void setCreditlimit(Long newCreditlimit);
 
    /**
     * Select methods. These are implemented by the container. You can
     * customize the functionality of these methods in the deployment
     * descriptor through EJB-QL.
     *
     * These methods are NOT exposed in the bean's home interface.
     */

    public abstract Long ejbSelectCreditLimit(Long accountnumber) throws FinderException;
    public abstract Collection ejbSelectByTopAccounts() throws FinderException;
 
    /**
     * Begin buisness logic methods that use select methods.
     * 
     * These methods are exposed in the bean's home interfaces.
     */

    /**
     * Method to perform post-processing operations on all the
     * UserAccounts retrieved by calling ejbSelectByTopAccounts. This
     * method further process the retrieved UserAccounts and checks
     * for the Accounts with TopCredits (credit limits) and returns the
     * collection of input number of UserAccounts.
     * Post-processing information within the EJB container itself
     * has the following two advantages: 
     *     1) It improves performance as the application can now leverage 
     *            the advantage of the vast resources available to the server.
     *     2) The data-processing code should go into the business logic
     *            and not the Web-tier. This helps in maintaining the code.
     * Consider these advantages when deciding between ejbFind and 
     * ejbSelect methods.
     *
     * @return Collection of <input number of> Top (credited) UserAccounts
     */
    public Collection ejbHomeTopAccounts(String accountNumbers) throws FinderException {
        // Invoke the ejbSelect method and get all the Account Information.
        Collection collection = this.ejbSelectByTopAccounts();
        ...
        return topAccounts;
    }
 
    /**
     * Method to call ejbSelectCreditLimit and return the credit limit value
     * for the input accountnumber without post-processing.
     * Please note that this method returns a Long instead of a collection
     * that is returned normally by the EJB container. This is a major 
     * advantage of ejbSelect methods. Using these methods, You can return
     * an object from 'within' the CMP instead of 'the' CMP. This way, the 
     * application uses the server and the EJB container resources more 
     * effeciently.
     *
     * @return Credit Limit of the input UserAccount
     */
    public Long ejbHomeCreditLimit(Long accountnumber) throws FinderException {
        // Return the Credit Limit of the specified Account
        return this.ejbSelectCreditLimit(accountnumber);
    }
    ...
}

Using Deployment XML

Example 16-4 shows the ejb-jar.xml file for the select methods defined in the abstract entity bean class that Example 16-3 shows.

Example 16-4 ejb-jar.xml For EJB 2.1 EJB QL Select Methods

<enterprise-beans>
    <entity>
      <description>Entity Bean ( CMP )</description>
      <display-name>UserAccount</display-name>
      <ejb-name>UserAccount</ejb-name>
      <local-home>oracle.otnsamples.ejbql.UserAccountLocalHome</local-home>
      <local>oracle.otnsamples.ejbql.UserAccount</local>
      <ejb-class>oracle.otnsamples.ejbql.UserAccountBean</ejb-class>
      <persistence-type>Container</persistence-type>
      <prim-key-class>java.lang.Long</prim-key-class>
      <abstract-schema-name>UserAccount</abstract-schema-name>
      <cmp-field>
        <field-name>accountnumber</field-name>
      </cmp-field>
      <cmp-field>
        <field-name>creditlimit</field-name>
      </cmp-field>
      <primkey-field>accountnumber</primkey-field>
      <query>
        <description>Selects all accounts and post-process to find top accounts</description>
        <query-method>
          <method-name>ejbSelectByTopAccounts</method-name>
        </query-method>
        <ejb-ql>select distinct object(ua) from UserAccount ua</ejb-ql>
      </query>
      <query>
        <description>Retrieves the Credit Limit for an Account</description>
        <query-method>
          <method-name>ejbSelectCreditLimit</method-name>
          <method-params>
            <method-param>java.lang.Long</method-param>
          </method-params>
        </query-method>
        <ejb-ql>
            select ua.creditlimit from UserAccount ua where ua.accountnumber = ?1
        </ejb-ql>
      </query>
    </entity>
  </enterprise-beans>

Using TopLink Workbench

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

For more information, see "Creating a Finder" in the Oracle TopLink Developer's Guide