Query Methods Overview

Query methods can be finder or select methods:

• Finder Methods: Use finder methods to retrieve entity bean references.

• Select Methods: Select methods are for internal use for the entity bean only. Use them to retrieve either entity bean references or CMP values.

Both query method types must throw the FinderException.

Finder Methods

Finder methods are used to retrieve entity bean references. The findByPrimaryKey finder method is always defined in both home interfaces (local and remote) to retrieve the entity reference for this bean using a primary key. You can define other finder methods in either or both the home interfaces to retrieve one or several entity bean references.

Do the following to define finder methods:

1. Define the find<name> method in the desired home interface. You can specify different finder methods in the remote or the local home interface. If you define the same finder method in both home interfaces, it maps to the same bean class definition. The container returns the appropriate home interface type.

2. Define the full query or just the conditional statement (the WHERE clause) for the finder method in the deployment descriptor.

   You can define the query using either EJB QL syntax or OC4J-specific syntax. You can specify either a full query or only the conditional part of the query (the WHERE clause).

   • EJB QL syntax is defined within the ejb-jar.xml file. The syntax is defined by Sun Microsystems in Chapter 11 of the EJB 2.0 specification. An EJB QL statement is created for each finder method in its own <query> element. The container uses this statement to translate the condition on how to retrieve the entity bean references into the relevant SQL statements.

     Currently, EJB QL has limited support for GROUP BY and ORDER BY functions, such as AVERAGE and SUM.

     See "Specifying Finder Methods With EJB QL Syntax" for more information.

   • OC4J-specific syntax is defined within the orion-ejb-jar.xml file. When you deploy your application, OC4J translates the EJB QL syntax into the OC4J-specific syntax, which is specified in the query attribute of the <finder-method> element. You can modify the statement in the query attribute for a more complex query using the OC4J syntax. The OC4J-specific query statement in the orion-ejb-jar.xml file takes precedence over its EJB QL statement in the ejb-jar.xml file.

     See "Specifying Finder Methods With OC4J-Specific Syntax" for more information.

If you retrieve only a single entity bean reference, the container returns the same type as returned in the find<name> method. If you request multiple entity bean references, you must define the return type of the find<name> method to return a Collection. If you want to ensure that no duplicates are returned, specify the DISTINCT keyword in the EJB QL statement. An empty Collection is returned if no matches are found.

See the "Finder Method Example" for more information on both types of finder methods.

Select Methods

Select methods are used primarily to return values for CMP or CMR fields. All values are returned in their own object type; any primitive types are wrapped in objects that have similar functions (for example, a primitive int type is wrapped in an Integer object). See section 10.5.7 of the EJB 2.0 specification for more information on select methods.

These methods are for internal use within the bean. These methods cannot be called from a client. Thus, you do not define them in the home interfaces. Select methods are used to retrieve entity bean references or the value of a CMP field.

Do the following to define select methods:

1. Define an ejbSelect<name> method in the bean class for each select method. Each method is defined as public abstract. The SQL that is necessary for this method is not included in the implementation.

2. Define the full query or just the conditional statement (the WHERE clause) for the select method in the deployment descriptor. An EJB QL statement is created for each select method in its own <query> element. The container uses this statement to translate the condition into the relevant SQL statements.

See the "Select Method Example" for more information on both types of finder methods.

Return Objects

Here are the rules for defining return types for the select method:

• No objects: If no objects are found, a FinderException is raised.

• Single object: If you retrieve only a single item, the container returns the same type as returned in the ejbSelect<name> method. If multiple objects are returned, a FinderException is raised.

• Multiple objects: If you request multiple items, you must define the return type of the ejbSelect<name> method as either a Set or Collection. A Set eliminates duplicates. A Collection may include duplicates. For example, if you want to retrieve all zip codes of all customers, use a Set to eliminate duplicates. To retrieve all customer names, use a Collection to retrieve the full list. An empty Collection or Set is returned if no matches are found.

  • Bean interface: If you return the bean interface, the default interface type returned within the Set or Collection is the local bean interface. You can change this to the remote bean interface in the <result-type-mapping> element, as follows:

    <result-type-mapping>Remote</result-type-mapping>
    
    

  • CMP values: If you return a Set or Collection of CMP values, the container determines the object type from the EJB QL select statement.