EJB Finders

An EJB finder is a query as defined by the EJB specification. It returns EJB, collections, and enumerations. The difference between a finder and a query is that queries return Java objects, but finders return EJB. The TopLink query framework lets you create and execute complex finders that retrieve entity beans.

Finders contain finder methods that define search criteria. The work involved in creating these methods depends on whether you are building container-managed persistence (CMP) bean finders or bean-managed persistence (BMP) bean finders:

• CMP finders require the developer to define the finder API method signature on the bean Home interface. The CMP provider generates the actual code mechanisms for the finder from the API definition.

• BMP finders require the developer to provide the code required to execute the finder methods.

In either case, you define finders in the Home interface of the bean.

You can implement finders using any TopLink query feature and you can take advantage of predefined finder implementations that TopLink provides for both CMP and BMP EJB.

This section describes the following:

• Predefined Finders

• Default Finders

• Call Finders

• DatabaseQuery Finders

• Named Query Finders

• Primary Key Finders

• Expression Finders

• EJB QL Finders

• SQL Finders

• Redirect Finders

• The ejbSelect Method

For more information, see "Using EJB Finders".

Predefined Finders

TopLink provides predefined finder implementations that provide a rich API that lets you dynamically specify query properties at run time and take full advantage of TopLink query features.

TopLink provides the following predefined finders:

• Predefined CMP Finders for EJB 2.0

• Predefined CMP Finders for EJB 1.1

• Predefined BMP Finders

For more information, see the following:

• "Understanding the EJB Entity Beans with CMP Architecture"

• "Understanding the EJB Entity Beans With BMP Architecture"

Predefined CMP Finders for EJB 2.0

Table 96-5 lists the predefined finders you can use with TopLink CMP for EJB 2.0 (using OC4J or BEA WebLogic Server).

The TopLink runtime reserves the method names listed in Table 96-5.

Table 96-5 Predefined CMP Finders for EJB2.0

Method	Arguments	Return
findAll	()	Collection
findManyByEJBQL	(String ejbql) (String ejbql, Vector arguments)	Collection
findManyByQuery	(DatabaseQuery query)(DatabaseQuery query, Vector arguments)	Collection
findManyBySQL	(String sql)(String sql, Vector arguments)	Collection
findByPrimaryKey	(Object primaryKeyObject)	EJBObject
findOneByEJBQL	(String ejbql) (String ejbql, Vector arguments)	EJBObject
findOneByQuery	(DatabaseQuery query)(DatabaseQuery query, Vector arguments)	EJBObject
findOneBySQL	(String sql)(String sql, Vector arguments)	EJBObject

Note: With EJB 2.0, if the finder is located on a local home, replace EJBObject with EJBLocalObject in finders that contain findOneBy.

You can also use each of these finders without a vector of arguments. For example, EJBObject findOneByEJBQL(String ejbql) is a valid dynamic finder, but you must replace the return type of EJBObject with your bean's component interface.

For more information, see "Using EJB Finders".

Predefined CMP Finders for EJB 1.1

Table 96-6 lists the predefined finders you can use with TopLink CMP for EJB1.1 (using IBM WebSphere Application server). In Table 96-6, finder methods with the suffix <name> can be declared with any name you choose provided the name has the given prefix and signature.

The TopLink runtime reserves the method names listed in Table 96-6.

Table 96-6 Predefined CMP Finders for EJB 1.1

Method	Arguments	Return
findAll	()	Enumeration
findAll<name>	(Call)(Expression)(ReadAllQuery)	Enumeration
findAllByNamedQuery	(String queryName, Vector arguments)	Enumeration
findByPrimaryKey	(Object primaryKeyObject)	Object
findOne<name>	(Call)(Expression)(ReadObjectQuery)	Object
findOneByNamedQuery	(String queryName, Vector arguments)	Object

For more information and examples on using predefined CMP finders for EJB 1.1, see "Using EJB Finders".

Predefined BMP Finders

Table 96-7 lists the predefined finders you can use if you extend your BMP EJB from oracle.toplink.ejb.bmp.BMPEntityBase (see "Understanding the EJB Entity Beans With BMP Architecture").

The TopLink runtime reserves the method names listed in Table 96-7.

Table 96-7 Predefined BMP Finders

Method	Arguments	Return
findAll	()(Call)(Expression)(ReadAllQuery)	Enumeration
findAllByNamedQuery	(String queryName, Vector arguments)	Enumeration
findByPrimaryKey	(Object primaryKeyObject)	Object
findOne	(Call) (Expression) (ReadObjectQuery)	Object
findOneByNamedQuery	(String queryName, Vector arguments)	Object

For more information about using EJB finders, see "Using EJB Finders".

Default Finders

For each finder method defined on the home interface of an entity bean, whose name matches findBy<CMP-FIELD-NAME> where <CMP-FIELD-NAME> is the name of a persistent field on the bean, TopLink generates a finder implementation including a TopLink query that uses the TopLink expressions framework. If the return type is a single bean type, TopLink creates a ReadObjectQuery; if the return type is an Enumeration (EJB 1.x) or Collection (EJB 2.x), TopLink creates a ReadAllQuery.

Although you must still define the finder in the entity home, you do not need to declare the finder in the ejb-jar.xml file.

For more information, see "Creating a Finder".

Call Finders

Finders that use a Call lets you create dynamic queries that you generate at run time rather than at deployment time.

For more information, see the following:

• "Call Queries".

• "Predefined Finders"

DatabaseQuery Finders

Finders that use a DatabaseQuery lets you create dynamic queries that you generate at run time rather than at deployment time.

In addition to finders that take a DatabaseQuery, TopLink also provides a default findAll finder that returns all the EJB of a given type. As with other dynamic finders, the TopLink runtime reserves the name findAll.

For more information, see "Database Queries".

For more information on TopLink predefined finders that take a DatabaseQuery, see "Predefined Finders".

Named Query Finders

Finders that use a named DatabaseQuery stored in a DescriptorQueryManager or Session lets you efficiently reuse frequently executed queries.

For more information, see

• "Named Queries"

• "Predefined Finders"

Primary Key Finders

TopLink provides predefined finder implementations that take a primary key class as a Java Object.

Because the EJB 2.0 specification requires the container to implement the findByPrimaryKey call on each bean Home interface, do not delete this finder from a bean.

For more information, see "Predefined Finders".

Expression Finders

Using a finder based on a TopLink Expression offers the following advantages:

• Version-controlled standardized queries in Java code

• Ability to simplify most complex operations

• A more complete set of querying features than is available through EJB QL

Because expressions lets you specify finder search criteria based on the object model, they are frequently the best choice for constructing your finders.

For more information, see "TopLink Expressions".

For more information on TopLink predefined finders that take an Expression, see "Predefined Finders".

You can also use an Expression in a finder that takes a DatabaseQuery by using DatabaseQuery method setSelectionCriteria. For more information on TopLink predefined finders that take a DatabaseQuery, see "DatabaseQuery Finders".

EJB QL Finders

TopLink supports EJB QL for both EJB 1.1 and EJB 2.0 beans. EJB QL finders lets you specify an EJB QL string as the implementation of the query.

EJB QL offers several advantages:

• It is the EJB 2.0 standard for queries.

• You can use it to construct most queries.

• You can implement dependent-object queries with EJB QL.

The disadvantage of EJB QL is that it is difficult to use when you construct complex queries.

For more information about EJB QL support in TopLink, see "Query Languages".

For more information on TopLink predefined finders that take EJB QL, see "Predefined Finders".

SQL Finders

Using SQL to define a finder offers the following advantages:

• You can implement logic that cannot be expressed when you use EJB QL or a TopLink Expression.

• It allows for the use of a stored procedure instead of TopLink generated SQL.

• There may be cases in which custom SQL will improve performance.

SQL finders also have the following disadvantages:

• Writing complex custom SQL statements requires a significant maintenance effort if the database tables change.

• Hard-coded SQL limits portability to other databases.

• No validation is performed on the SQL string. Errors in SQL statements will not be detected until run time.

• The use of SQL for a function other than SELECT may result in unpredictable errors.

For more information on TopLink predefined finders that take SQL, see "Predefined Finders".

Redirect Finders

Redirect finders enable you to implement a finder that is defined on an arbitrary helper class as a static method. When you invoke the finder, TopLink redirects the call to the specified static method.

Redirect queries are complex and require an extra helper method to define the query. However, because they support complex logic, they are often the best choice when you need to implement logic unrelated to the bean on which the redirect method is called.

For more information, see the following:

• "Redirect Queries"

• "Using EJB Finders"

The ejbSelect Method

The ejbSelect method is a query method intended for internal use within an entity bean instance. Specified on the abstract bean itself, the ejbSelect method is not directly exposed to the client in the home or component interface. Defined as abstract, each bean can include zero or more such methods.

ejbSelect methods have the following characteristics:

• The method name must have ejbSelect as its prefix.

• It must be declared as public.

• It must be declared as abstract.

• The throws clause must specify the javax.ejb.FinderException, although it may also specify application-specific exceptions as well.

• Under EJB 2.0, the result-type-mapping tag in the ejb-jar.xml file determines the return type for ejbSelect methods. Set the flag to Remote to return EJBObjects; set it to Local to return EJBLocalObjects.

The format for an ejbSelect method definition looks like this:

public abstract type ejbSelect<METHOD>(...);

The ejbSelect query return type is not restricted to the entity bean type on which the ejbSelect is invoked. Instead, it can return any type corresponding to a container-managed relationship or container-managed field.

Although the select method is not based on the identity of the entity bean instance on which it is invoked, it can use the primary key of an entity bean as an argument. This creates a query that is logically scoped to a particular entity bean instance.

For more information and examples on using TopLink queries in the ejbSelect method, see "Using EJB Finders".