Skip Headers

Oracle TopLink Developer's Guide 10g Release 3 (10.1.3) B13593-01 |
| Home | Solution Area | Contents | Index

Previous | Next |

# 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".