Writing Finder Methods

The finder methods allow multiple clients to share an entity EJB. This is a difference between session beans and entity beans. Sessions beans cannot be shared and therefore do not have finder methods. All entity beans must contain a findByPrimaryKey() method in their home interfaces. The findByPrimaryKey() method in the remote home interface will return an instance of the remote interface. The findByPrimaryKey() method in the local home interface will return an instance of the local interface. The parameter to findByPrimaryKey() is used to match against the primary key of an existing instance of the entity bean. The deployment descriptor of the entity bean specifies the <prim-key-class> . The parameter must therefore be of the same class type as the primary key class. In a BMP implementation, the entity bean will have a corresponding method named ejbFindByPrimaryKey() that takes the same parameter as findByPrimaryKey() ; however, the ejbFindByPrimaryKey() return type is the primary key where the findByPrimaryKey() return type is the remote interface.

The bean provider can supply additional finder methods in the home interfaces, both local and remote. The return type must be the same as the return type for findByPrimaryKey() . The parameters are application specific to provide convenient access for multiple clients to share entity beans. Each findBy XXX () method in the home interface will have a corresponding ejbFindBy XXX () method in the entity bean. The return value for ejbFindBy XXX () is the primary key of the matching entity bean. In a BMP implementation, the ejbFindBy XXX () methods will execute SQL SELECT statements to find the matching entry in the relational database. Refer to the "Bean-Managed Persistence Example" later in this chapter for an example of the findByPrimaryKey() method.

Enterprise JavaBean Query Language

For Container-Managed Persistence, EJB 2.0 introduced EJB-QL, the Enterprise JavaBean Query Language. This standard query language enhances portability over proprietary query languages. The WebLogic Query Language (WLQL) provides extensions to EJB-QL ; however, you cannot use WLQL with entity beans that use EJB 2.0 features or EJB 2.0 deployment descriptors. Rather than coding SELECT statements directly in the entity bean, the deployment descriptor contains an <ejb-ql> tag that specifies the query to be performed using EJB-QL syntax. The ShoppingCart in the "Container-Managed Relationship Example" uses EJB-QL to implement the findAll() method that returns a java.util.Collection of all the books in the shopping cart. The following components provide the implementation of a finder method that uses EJB-QL; it must

Provide application-specific finder methods in the home interfaces
Include the <ejb-ql> tag following the <query-method> in the deployment descriptor

An example of an EJB-QL query method is shown in Listing 21.11. This example was extracted as a snippet from the deployment descriptor for the book store example .

Listing 21.11 EJB-QL Allows You to Place the SQL Statement for Finder Methods in the Deployment Descriptor

 <query>         <query-method>           <method-name>findAll</method-name>           <method-params>           </method-params>         </query-method>         <ejb-ql><![CDATA[SELECT OBJECT(s) FROM ShoppingCartSchema                    AS s]]></ejb-ql>       </query>

The XML syntax uses the special tag <![CDATA[...]]> . It tells the XML parser to treat the EJB-QL statement literally and to not attempt to parse it as XML. The EJB-QL statement is entered between the square brackets of the CDATA .