Skip Headers

# Creating a Finder

Previous

Next

In general, to create a finder for an entity bean that uses the TopLink query framework, you must define, declare, and configure it.

For predefined finders (see "Predefined Finders"), you do not need to explicitly create a finder.

For default finders (see "Default Finders"), you only need to define the finder method.

To create a finder for an entity bean that uses the TopLink query framework, follow these steps:

1. Define the finder method on the entity bean's `remoteHome` or `localHome` interface.

   For entity beans with container-managed persistence, define the method on the entity bean's `Home` interface.

   For default finders (see "Default Finders"), you must define the finder as follows:

   - `<``RETURN-TYPE``> findBy<``CMP-FIELD-NAME``>(<``CMP-FIELD-TYPE``>)`

   - the first letter of `<``CMP-FIELD-NAME``>` must be capitalized

   - `<``RETURN-TYPE``>` may be a single bean type or `Collection`.

   For example:

       EmployeeBean (Integer id, String name)
       EmployeeHome ..{
          Employee findById(Integer id) throws...;
          Collection findByName(String name) throws...;
       }

   Note: If you are using default finders (see "Default Finders"), you are finished. TopLink will implement the finder for you at run time.

2. Declare the finder in the `ejb-jar.xml` file (see "ejb-jar.xml Finder Options").

3. Start TopLink Workbench.

4. Click the project icon in the Navigator and select: Selected > Update Project from ejb-jar.xml to read in the finders.

5. Go to the Queries > Named Queries tab for the bean (see "Using Named Queries").

6. Select and configure the finder.

   Notes: For predefined finders `findOneByQuery` and `findManyByQuery`, the client creates a query at run time and passes it as a parameter to the finder. Because of this, do not configure query options on these finders. Instead, configure options on the query passed into the finder. For more information about predefined finders, see "Predefined Finders".

7. If required, create an implementation for the query. Some query options require a query definition in code on a helper class, but most common queries do not.

When you use TopLink CMP, define finder methods on the bean's `Home` interface, not in the entity bean itself. TopLink CMP provides this functionality and offers several strategies to create and customize finders. The EJB container and TopLink automatically generate the implementation.