8
The Single Bean Example Application

TopLink includes several TopLink EJB 1.1 CMP example applications for WebSphere in the \examples directory:

• Single Bean

• Relationships

• Advanced

See <INSTALL_DIR>/doc/demos.html for links to all the examples and details on configuring the examples for WebSphere Application Server.

This chapter details how the Single Bean example is built. Although the Single Bean example involves persisting just one entity bean, the information provided on development, configuration and deployment is the same as is needed for more complex multi-bean applications.

Understanding the Single Bean example

The Single Bean example application shows how a single bean can be made persistent using TopLink Container-Managed Persistence container managed persistence support. This example illustrates simple direct-to-field mappings and introduces the basic steps required to deploy a bean. The example consists of an entity bean called AccountBean.

The example is configured to on the IBM WebSphere Application Server.

The Single Bean example application demonstrates:

• The use of an entity bean in an application

• That persistence-related code is not required in the entity bean

• That implementation of ejbFind methods is not required in the entity bean (in the example, query logic for each finder method included in the home interface is defined using the Mapping Workbench or in an amendment method)

• The use of the TopLink deployment XML file, which contains bean-to-database mapping meta information

• How TopLink transparently manages persistence for beans when they are being created, updated, removed, and queried

The Client application performs the following steps:

• Creates a simple AccountBean instance, makes a deposit and a withdrawal from the account

• Populates the database with several account bean instances

• Finds all accounts in the database whose balances are greater than the provided sum

• Finds an account in the database whose owner matches a provided search string

• Removes all accounts created

The Object model

The Single Bean example provides a simplified view of the standard "bank account" example, and shows how a single class can be modeled as an entity bean and made persistent using TopLink.

The interface

examples.ejb.cmp11.singlebean.Account provides the public interface for the bean. It extends the javax.ejb.EJBObject interface, and contains all of the business methods that are accessible to clients of the entity. This includes getters and setters for the instance data, as well as deposit() and withdraw() methods.

The class

examples.ejb.cmp11.singlebean.AccountBean provides the actual bean implementation for the bank account. It has methods corresponding to the methods on the remote interface, as well as the methods required by the javax.ejb.EntityBean interface, which it extends. The AccountBean's fields include accountId (String), balance (double), and owner (String).

The home interface

examples.ejb.cmp11.singlebean.AccountHome provides the "home" interface of the bean. It extends the javax.ejb.EJBHome interface, and defines the required create, remove, and finder methods.

Figure 8-1 Structure of the Single Bean Example

Text description of the illustration jspejbex.gif

Database schema

The Account data is stored in a single table.

Table 8-1 The EJB11_ACCOUNT table

Column Name	Column Type	Details
ACCOUNT_ID	VARCHAR	primary key
BALANCE	DOUBLE / NUMERIC	balance in account
OWNER	VARCHAR	owner's name

Entity Development

A deployable component is typically developed as follows:

• Create the interfaces.

• Create and implement the bean classes.

• Create the deployment descriptors.

• Map the entities to the database.

• Generate code for deployment.

• Deploy the EAR file.

• Run the client.

Create the interfaces

Each entity can contain either a home or remote interface, or both. These interfaces dictate how the bean is used by other components of the application. The Account interfaces required for the Single Bean example are located in the was/examples/ejb/cmp11/singlebean example directory.

Create and implement the bean classes

Define instance variables for each CMP field and corresponding get and set methods. Also implement business methods on the bean. The AccountBean class required for the Single Bean example is located in the was/examples/ejb/cmp11/single bean example directory.

Create the deployment descriptors

A JAR file requires an ejb-jar.xml and a toplink-ejb-jar.xml. The EAR file requires other descriptors, as do client application JAR files. The WebSphere AAT or other tools can be used to generate all but the toplink-ejb-jar.xml. The developer must manually create this TopLink deployment descriptor.

The TopLink deployment descriptor: toplink-ejb-jar.xml

The TopLink deployment descriptor is included in the EJB JAR in the same META-INF directory as the ejb-jar.xml and the ibm extension files. This descriptor provides the information that TopLink needs to deploy the entities in the EJB JAR.

Because the entities deployed in a EJB JAR are all encompassed by a TopLink project, the deployment JAR file is associated with exactly one project. This project is in turn associated with exactly one TopLink session (as implied by the single session element in the descriptor).

The elements that have been modified for the Single Bean example in the toplink-ejb-jar.xml file are:

<name>

A session name (unique among all deployed JARs) that is used as a key for the deployed TopLink project (or the JAR that contains the project).

<project-xml>

project deployment XML file that can be stored either in the deployable JAR file at the root directory or left on the file system.

<session-type>

The session type should always be set to <server-session/>.

<platform-class>

The class specified controls the format of the SQL generated and other database specific behavior.

Note: You can use a <project-class> element rather than a <project-xml> if you choose. With the <project-class> element, specify the fully-qualified name of the TopLink project class. This class should be included in the deployable JAR file. The project class can either be generated by the Mapping Workbench or written manually.

<uses-external-connection-pool> and <uses-external-transaction-controller>

For TopLink to participate in WebSphere JTS transactions these should be both set to true.

<external-transaction-controller-class>

This is the TopLink server-specific JTS controller class required when using external transaction control. For WebSphere 4.0 use oracle.toplink.jts.was.
JTSExternalTransactionController_4_0.

<enable-logging>

When set to true, TopLink will print logging information for several of its operations. This is very useful for debugging.

<logging-options>

Options for different levels of TopLink logging.

For more information, see the toplink-was-ejb-jar_903.dtd.

Map the entities to the database

This section describes the steps required to create the Account project using the Mapping Workbench.

For more information about creating projects using the Mapping Workbench, consult the Oracle9iAS TopLink Mapping Workbench Reference Guide.

This section assumes you have already read and completed the introductory tutorials in Oracle9iAS TopLink Tutorials, which offers an introduction to the fundamental concepts of the Mapping Workbench.

Creating a TopLink project

A TopLink project defines how the entity beans are persisted to the database. The Mapping Workbench enables you to easily build a TopLink project. The project is specified in the toplink-ejb-jar.xml in the <project-class> or <project-xml> element and used at run time to persist the beans.

Note: The complete Account project is available in the was/examples/ejb/cmp11/singlebean/mw directory and can be opened and examined with the Mapping Workbench.

To create a TopLink project:

1. Click File > New Project to start a new project.

2. In the General tab, set the Persistence Type to 1.1 CMP.

3. Optionally, specify an ejb-jar.xml file to use for the project. For EJB 1.1 projects it is not required or even desirable to specify and ejb-jar.xml file here since under the EJB 1.1. specification the ejb-jar.xml file contains no mapping information that is not readily available in the bean classes.

   For the Mapping Workbench to be able to read and update the ejb-jar.xml, it must have the EJB 2.0 DTD its DOCTYPE element. See "Working with the ejb-jar.xml file" in the Mapping Workbench Reference Guide for details on working with the ejb-jar.xml file.

4. In the General tab, specify a project classpath. The project classpath should contain the classes to be added to the project and interfaces associated with those classes. Classes to be added to the project include bean classes and referenced classes. Bean interfaces do not have to be added to the project, but must appear in the project classpath.

5. To add the beans to the project, click Selected > Add/Refresh Classes.

   Note: Bean classes must to be added to the project at this point (for example, the Single Bean example requires the AccountBean class); however, referenced classes are not required.

6. To specify the beans classes as bean descriptors, click Selected > Descriptor Type > EJB Descriptor.

7. Create database tables. The Single Bean example application uses an EJB11_ACCOUNT table to persist the bean. Ensure that the ACCOUNT_ID is the primary key in the EJB_ACCOUNT table.

   The table can either be imported from the database or created in the Mapping Workbench. For more information on working with tables, see "Working with database tables" in the Oracle9iAS TopLink Mapping Workbench Reference Guide.

8. To associate AccountBean with a table, select the AccountBean and set the EJB_ACCOUNT table as the associated table in the Descriptor Info tab.

9. Map the CMP fields. The AccountBean has three CMP fields to be mapped using direct-to-field mappings: accountId, balance, and owner. Map them to their corresponding database fields in the EJB11_ACCOUNT table.

10. Create queries for finders. The AccountHome defines two finders that must be defined: findByOwner and findLargeAccounts. The Queries tab of the AccountBean descriptor is used to define a query for each finder on the AccountHome. Each query requires:
    • The name of the query

    • The Type of query depending on whether the query returns a single bean or a collection of beans

    • The query format (one of SQL, EJBQL, or TopLink's expression framework)

    • The Query String used for SQL or EJBQL query strings. If TopLink's expression framework is used then the query must be defined in a descriptor after-load method

    • Parameters and Options

      Note: The finder findByPrimaryKey is implemented by TopLink and does not require a user implementation.

11. Export a project to be used at runtime. The project can be written out as a Java class which has to be compiled and included with the deployment JAR or an XML file. In the toplink-ejb-jar.xml file, use either the <project-class> or <project-xml> depending on which export method was used.

Generate code for deployment

The Single Bean example is packaged into an EAR file, which itself contains the following:

• A deployable EJB 1.1 JAR file containing the interface and abstract bean classes, the classes (RMI stubs and implementation classes) generated by IBM's deploytool and TopLink's deploytool, and the deployment descriptor XML files.

• A client JAR containing the client code.

The TopLink deployment code generation tool must be used instead of WebSphere's to generate the deployable JAR file. The generated code contains callbacks to the TopLink persistence framework which makes CMP possible. TopLink's deploytool takes a non-deployed EJB 1.1 JAR as input, generates the TopLink-specific CMP code and calls the WebSphere deploytool for code generation.

EJB 1.1 JAR files can be created by any of a combination of the following tools:

• VisualCafe 4.5 with WebSphere 4.0 Integration plugin

• WebSphere Application Assembly Tool

• WebSphere Studio Application Developer (WSAD)

• VisualAge for Java (VAJ)

• JDK packaging tools

TopLink's deploytool can be launched from the TopLink CMP Deployment Tool or from the command line.

In Windows, the deploy tool can be opened from the Start menu by clicking Start > Programs > Oracle9iAS TopLink > Tools > Deploy Tool for WebSphere Server. The deploy tool can be used with WebSphere Application Server or with WebSphere Studio Application Developer.

An Ant-based build script is included with the example application, which disassembles an EAR file, calls TopLink code generation on the JAR file, and reassembles the EAR file. A copy of the deployable JAR is placed in the server's installableApps\ directory.

Deploy the EAR file

You can deploy the EAR file several different ways (see the WebSphere Server documentation for more detailed information on how to deploy a EAR file into the server).

The Single Bean example is configured to run against the local HSQL database. Ensure that the HSQL database server is started before starting the application on the server. Also ensure that the HSQL toplink.examples.datasource is configured in the server before installing the application on the server. See the examples configuration documentation in the examples/ directory for details.

Run the client

Included in the Single Bean directory, is a runClient.cmd which can be used to run the client.