EJB Finders

entity tag

The entity tag encapsulates a definition for an EJB entity bean. Each bean has its own entity tag that contains several other tags that define bean functionality, including bean finders.

Example 6-76 illustrates the structure of a typical finder defined within the ejb-jar.xml file.

<entity>...    <query>        <query-method>            <method-name>findLargeAccounts</method-name>                <method-params>                <method-param>double</method-param>            </method-params>        </query-method>    <ejb-ql><![CDATA[SELECT OBJECT(account) FROM AccountBean account WHERE       account.balance > ?1]]></ejb-ql>    </query>...</entity>

Creating Call Finders

OracleAS TopLink provides the implementation for Call finders. To use this feature in a bean, add the following finder definition to the Home interface of your bean.

public Enumeration findAll(Call call) throws RemoteException, FinderException;

Executing a Call Finder

When you execute a Call finder, OracleAS TopLink creates the call on the client using the OracleAS TopLink interface oracle.toplink.queryframework.Call. This call has three implementors: EJBQLCall, SQLCall and StoredProcedureCall.

{
    SQLCall call = new SQLCall();
    call.setSQLString("SELECT * FROM EMPLOYEE");
    Enumeration employees = getEmployeeHome().findAll(call);
}

{
    StoredProcedureCall call = new StoredProcedureCall();
    call.setProcedureName("READ_ALL_EMPLOYEES");
    Enumeration employees = getEmployeeHome().findAll(call);
}

Creating an EJB QL Finder Under EJB 1.1

To create an EJB QL finder under EJB 1.1:

1. Declare the finder on the remote interface.

2. Start OracleAS TopLink Mapping Workbench.

3. Choose the Queries > Finders > Named Queries tab for the bean.

4. Add a finder and give it a name that matches the method name you declared in Step 1.

5. Set the required parameters.

6. Set Query Format to EJB QL, and enter the EJB QL query in the Query String field.

Creating an EJB QL Finder Under EJB 2.0

To create an EJB QL finder under EJB 2.0:

1. Declare the finder on either the localHome or the remoteHome interface.

2. Start OracleAS TopLink Mapping Workbench.

3. Re-import the ejb-jar.xml file to synchronize the project to the file.

   OracleAS TopLink Mapping Workbench synchronizes changes between the project and the ejb-jar.xml file.

The following is an example of a simple EJB QL query that requires one parameter. In this example, the question mark (Ò?Ó) in?1 specifies a parameter.

SELECT OBJECT(employee) FROM Employee employee WHERE (employee.name =?1)

Creating an EJB QL Finder for a CMP Bean

To create an EJB QL finder for a CMP bean:

1. Declare the finder in the ejb-jar.xml file, and enter the EJB QL string in the ejb-ql tag.

2. Declare the finder on the Home interface, the localHome interface, or both, as required.

3. Start OracleAS TopLink Mapping Workbench.

4. Specify the ejb-jar.xml file location and choose File > Updated Project from the ejb-jar.xml file to read in the finders.

5. Choose the Queries > Finders > Named Queries tab for the bean.

6. Add a finder, and give it the same name as the finder you declared on your bean's home. Then add any required parameters.

7. Select and configure the finder.

The following is an example of a simple EJB QL query that requires one parameter. In this example, the question mark (Ò?Ó) in?1 specifies a parameter.

SELECT OBJECT(employee) FROM Employee employee WHERE (employee.name =?1)

ReadAll Query and EJB QL

To execute a query normally, you supply either a reference class or a SELECT clause.

The basic API for a ReadAll query with EJB QL is:

ReadAllQuery setEJBQLString("...")

ReadAllQuery theQuery = new ReadAllQuery();
theQuery.setReferenceClass(EmployeeBean.class);
theQuery.setEJBQLString("SELECT OBJECT(emp) FROM EmployeeBean emp");
…
Vector returnedObjects = (Vector)aSession.executeQuery(theQuery);

// First define the query
ReadAllQuery theQuery = new ReadAllQuery();
theQuery.setReferenceClass(EmployeeBean.class);
theQuery.setEJBQLString("SELECT OBJECT(emp) FROM EmployeeBean emp WHERE emp.firstName = ?1");
theQuery.addArgument("1");
...
// Next define the Arguments
Vector theArguments = new Vector();
theArguments.add("Bob");
...
// Finally execute the query passing in the arguments
Vector returnedObjects = (Vector)aSession.executeQuery(theQuery, theArguments);

EJB QL Session Queries

When you execute EJB QL directly against the session, it returns a vector of the objects specified by the reference class. The basic API is as follows:

aSession.readAllObjects(<ReferenceClass>, <EJBQLCall>)

/* <EJBQLCall> is the EJBQL string to be executed and <ReferenceClass> is the return class type */
// Call ReadAllObjects on a session.
Vector theObjects = (Vector)aSession.readAllObjects(EmployeeBean.class, new EJBQLCall( "SELECT OBJECT (emp) from EmployeeBean emp));

Creating a SQL Finder

To create a SQL finder:

1. Declare the finder in the ejb-jar.xml file, and leave the ejb-ql tag empty.

2. Start OracleAS TopLink Mapping Workbench.

3. Specify the ejb-jar.xml file location and choose File > Updated Project from the ejb-jar.xml file to read in the finders.

4. Choose the Queries > Named Queries tab for the bean.

5. Select the finder, check the SQL radio button, and enter the SQL string.

6. Configure the finder.

The following is an example of a simple SQL finder that requires one parameter. In this example, the hash character, '#', is used to bind the argument projectName within the SQL string.

SELECT * FROM EJB_PROJECT WHERE (PROJ_NAME = #projectName)

Creating a Dynamic Finder

To create a dynamic finder:

1. Declare the finder in the ejb-jar.xml file, and leave the ejb-ql tag empty.

2. Declare the finder on the Home interface, the localHome interface, or both, as required.

3. Start OracleAS TopLink Mapping Workbench.

4. Specify the ejb-jar.xml file location and choose File > Updated Project from the ejb-jar.xml file to read in the finders.

5. Go to the Queries > Named Queries tab for the bean.

6. Select and configure the finder.

Using findAll

In addition to the preceding dynamic finder, OracleAS TopLink provides a default findAll query that returns all the beans of a given type. As with other dynamic finders, the OracleAS TopLink runtime reserves the name findAll.

For more information about defining and configuring the finder, see "Creating a Dynamic Finder".

Using findByPrimaryKey

OracleAS TopLink creates the findByPrimaryKey finder to a bean class when the class initializes. You can configure the findByPrimaryKey finder with the various OracleAS TopLink query options.

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.

Creating READALL Finders

OracleAS TopLink provides an implementation for ReadAll finders. To use this feature in a bean, add the following finder definition to the Home interface of your bean.

public Enumeration findAll(ReadAllQuery query) throws RemoteException, FinderException;

To execute a ReadAll finder, create the query on the client.

{
    ReadAllQuery query = new ReadAllQuery(Employee.class);
    query.addJoinedAttribute("address");
    Enumeration employees = getEmployeeHome().findAll(query);
}

Using the OracleAS TopLink Expression Framework

Using OracleAS TopLink expressions offers the following advantages:

• Version controlled, standardized queries to Java code

• Ability to simplify most complex operations

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

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

For more information about implementing finders using OracleAS TopLink expressions, see "Expression Finders".

Using 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, OracleAS 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.

Using SQL

Using SQL to define a finder offers the following advantages:

• SQL enables you to implement logic that cannot be expressed when you use EJB QL or the OracleAS TopLink expression framework.

• It allows for the use of a stored procedure instead of OracleAS 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.

• The hard coded SQL limits portability to other databases.

• No validation is performed on the SQL String. Errors in the SQL will not be detected until runtime.

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

Caching Options

You can apply various configurations to the underlying query to achieve the correct caching behavior for the application. Several ways are available to control the caching options for queries. For most queries, you can set caching options with OracleAS TopLink Mapping Workbench. For more information, see ÒCaching objectsÓ in the Oracle Application Server TopLink Mapping Workbench User's Guide.

You can set the caching options on a per-finder basis. Table 6-8 lists the valid values.

For more information about the OracleAS TopLink queries as well as the OracleAS TopLink Unit of Work and how it integrates with JTS, see Chapter 7, "Transactions".

Disable Cache for Returned Finder Results

By default, OracleAS TopLink adds all returned objects to the session cache. However, if you know the set of returned objects is large, and you want to avoid the expense of storing these objects, you can disable this behavior. To override the default configuration, implement the dontMaintainCache() call on the query, or disable returned object caching for the query in OracleAS TopLink Mapping Workbench.

For more information about disabling caching for returned finder results, see the Oracle Application Server TopLink Mapping Workbench User's Guide.

Refreshing Finder Results

A finder may return information from the database for an object whose primary key is already in the cache. When set to true, the Refresh Cache option (in OracleAS TopLink Mapping Workbench) causes the query to refresh the nonprimary key attributes of the object with the returned information. This occurs on findByPrimaryKey finders as well as all expression and SQL finders for the bean.

If you build a query in Java code, you can set this option by including the refreshIdentityMapResult() method. This method automatically cascades changes to privately owned parts of the beans. If you require different behavior, then configure the query using a dynamic finder instead.

If your application includes an OptimisticLock field, then use the refresh cache option in conjunction with the onlyRefreshCacheIfNewerVersion() option. This ensures that the application refreshes objects in the cache only if the version of the object in the database is newer than the version in the cache.

For finders that have no refresh cache setting, the onlyRefreshCacheIfNewerVersion() method has no effect.

Managing Large Result Sets with Cursored Streams

Large result sets can be resource intensive to collect and process. To give the client more control over the returned results, configure OracleAS TopLink finders to use cursors. This combines OracleAS TopLink CursoredStream with the ability of the database to cursor data, and breaks up the result set into smaller, more manageable pieces.

The behavior of a finder including a cursored stream differs from other finder as follows:

• Only the elements requested by the client are sent to the client.

• Nothing is cached on the client in the CursoredEnumerator.

• If you use the transactional attribute REQUIRED for your entity bean, then you must wrap all reads in a UserTransaction begin() and commit() to ensure that reads beyond the first page of the cursor have a transaction in which to work.

ReadAllQuery raq = new ReadAllQuery();
ExpressionBuilder bldr = new ExpressionBuilder();
raq.setReferenceClass(ProjectBean.class);
raq.useCursoredStream();
raq.addArgument("projectName");
raq.setSelectionCriteria(bldr.get("name").
like(bldr.getParameter("projectName")));
descriptor.getQueryManager().addQuery ("findByNameCursored", query);

import oracle.toplink.ejb.cmpwls11. CursoredEnumerator;
//... other imports as necessary
getTransaction().begin();
CursoredEnumerator cursoredEnumerator = (CursoredEnumerator)getProjectHome()  .findByNameCursored("proj%");

Vector projects = new Vector();
for (int index = 0; index < 50; i++) {
Project project = (Project)cursoredEnumerator.nextElement();
projects.addElement(project);
}
// Rest all at once ...
Vector projects2 = cursoredEnumerator.nextElements(50);
cursoredEnumerator.close();
getTransaction().commit();

//import both CursoredCollection and CursoredIterator
import oracle.toplink.ejb.cmp.wls.*;
//... other imports as necessary
getTransaction().begin();
CursoredIterator cursoredIterator = (CursoredIterator) getProjectHome().findByNameCursored("proj%").iterator();
Vector projects = new Vector();
for (int index = 0; index < 50; i++) {
Project project = (Project)cursoredIterator.next();
projects.addElement(project);
}
// Rest all at once ...
Vector projects2 = cursoredIterator.next(50);
cursoredIterator.close();
getTransaction().commit();