9
The EJB 2.0 Single Bean Example Application

This chapter introduces the basic concepts that are required to build and deploy an entity bean with TopLink. It provides an example of how TopLink CMP is used in a simple application that combines Java server pages (JSPs) and EJBs. A simple entity bean is used to illustrate TopLink's basic direct-to-field mapping capabilities, along with some simple EJBQL queries.

Included in this example are instructions for

• creating bean classes and interfaces

• creating deployment descriptors

• mapping entities to the database using the Mapping Workbench

• generating a deployable JAR file

The example package is examples.ejb.cmp20.singlebean.

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

A note about this example

This chapter guides you through running the example, as well as describing in detail how the example was built. Although the Single Bean example is a relatively simple application, the process and procedures it introduces can be used to build much more complex applications as well.

Running the Single Bean example

To run the Single Bean example, you must

• Start the TopLink domain WebLogic Server. From Windows Start menu, click Programs > Oracle9iAS TopLink > Example Utilities > Start TopLink WebLogic Demo Server.

Configuring the example database

TopLink includes HSQL, as well as a preconfigured database containing all of the tables required to run the example. The SQL commands required to recreate the database are found in the createTables.sql file. Use the provided ResetDatabase.cmd script to reset the database tables if required.

Understanding the Single Bean example

The Single Bean example shows how a single bean can be made persistent using TopLink Container-Managed Persistence CMP support. This example illustrates simple direct-to-field mappings and introduces the basic steps required to deploy a bean.

This is a simple example that demonstrates how to use entity beans when deployed using TopLink CMP. The example consists of an entity bean called Account.

The Single Bean example 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 - query logic for each finder method defined in the home interface is defined using the Mapping Workbench or in an amendment method

• The use of the TopLink "project" class, 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 is an HTML page generated by JSP components. The Single Bean example follows the basic J2EE application architecture, using pure HTML generated by JSPs. The JSPs access the Single Bean entity bean.

The example can be viewed by pointing a web browser at http://localhost:7001/Account/mainPage.jsp. Starting at this main page, you can query for single beans based on the associated balance and owner, and add and delete single beans.

The use of JSPs and EJBs in this example provides a simple example of a J2EE application, and demonstrates one of several different ways to leverage this technology.

Figure 9-1 Structure of the Single Bean Example

Text description of the illustration jspejbex.gif

Single Bean example: packages, classes, and file

The following table lists the packages, classes, and files associated with the Single Bean example in this chapter. All files associated with the example are located in <install>\examples\wlsxx\examples\ejb\cmp20\
 singlebean unless otherwise noted.

Table 9-1 Packages, classes, and files in the Single Bean example  

Component Type	Component Name / Location
Package	examples.ejb.cmp20.singlebean Note: The root directory for the package is <install>\examples\
Server classes/interfaces	Account, AccountHome, AccountBean
JSP source	./jsp/mainPage.jsp, ./jsp/findAccounts.jsp, ./jsp/createAccount.jsp, ./jsp/removeAccount.jsp
HSQL database build script	ResetDatabase.cmd (Windows only)
Table definitions and data population SQL	createTables.sql
Environment settings	<Install>/setenv.cmd (Windows only)
Deployment files	/ejb-jar.xml,weblogic-ejb-jar.xml, toplink-ejb-jar.xml
TopLink Mapping Workbench project	./mw/Account.mwp
Sample build script	build.cmd
Deployable project	Account.xml
Mapping Workbench directory	./mw

.

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.cmp20.singlebean.Account provides the public "local" interface for the bean. It extends the javax.ejb.EJBLocalObject interface, and contains all of the business methods that are accessible to local clients of the entity. This includes getters and setters for the instance data, as well as deposit() and withdraw() methods.

The class examples.ejb.cmp20.singlebean.AccountBean provides the actual bean implementation for the bank single bean. 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 account's fields include AccountId (String), balance (double), and owner (String).

The interface examples.ejb.cmp20.singlebean.AccountHome provides the "local home" interface of the bean. It extends the javax.ejb.EJBLocalHome interface, and defines the required create, remove, and finder methods.

In this example, no additional primary key class is used. In EJB 1.1 and above, additional primary key classes are not required if the primary key consists of one field.

Database schema

The Single Bean data is stored in a single table.

Table 9-2 The EJB_ACCOUNT BEAN table  

Column Name	Column Type	Details
ACCOUNT_ID	Numeric	primary key
BALANCE	DOUBLE	balance in single bean
OWNER	VARCHAR	owner's name

The example also makes use of table-based sequencing through the EJB_ACCOUNT_SEQ table. This table provides primary keys (account numbers) for the EJB_ACCOUNT table.

Table 9-3 The EJB_ACCOUNT_SEQ table  

Name	Type	Details
SEQ_NAME	VARCHAR	Used by TopLink to identify the table that requires sequence data
SEQ_VALUE	DECIMAL	Sequence data

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.

• Deploy the JAR file.

• Deploy the JAR file.

Create the interfaces

Each entity can contain any or all of the following interfaces:

• local home (under EJB 2.0)

• home

• local

• remote

These interfaces dictate how the bean is used by other components of the application. The Account interfaces have been created and are located in the main "single bean" example directory.

Create and implement the bean classes

Define abstract get and set methods to represent the persistent attributes and use the get and set methods when implementing the business logic in the beans. The AccountBean class has been created and is located in the main Single Bean Example directory.

Create the deployment descriptors

Three deployment descriptors are required for each JAR. They are

• ejb-jar.xml

• weblogic-ejb-jar.xml

• toplink-ejb-jar.xml

The ejb-jar.xml descriptor should be created as specified in the EJB 2.0 specification. The weblogic-ejb-jar.xml file should be defined as described in WebLogic Server documentation. The toplink-ejb-jar.xml file should be defined as described in this documentation. These descriptors have been created and are located in the example directory.

The deployment descriptors must be in the META-INF directory in the JAR.

ejb-jar.xml

This is the main deployment descriptor prescribed and specified by the EJB specification. It defines most of the basic properties for the session and entity beans, including

• the bean home and component interfaces

• the bean abstract class

• inter-bean relationships information

• security declarations

• transactional attributes

• references to other beans

• resources used by the bean

The key elements that are particularly relevant to TopLink CMP are:

<ejb-name>

A unique name (across all beans in the JAR) which must match the ejb-name attribute in the weblogic-ejb-jar.xml file.

<cmp-version>

Must be set to 2.x to indicate that EJB 2.0 is being used.

<resource-ref>

Lists the data source used by the entity in which it is declared.

<query>

A group of elements that, when combined, describe a particular bean finder by including the method name, parameter types and query criteria.

Note: Mapping beans in the Mapping Workbench creates or modifies the information in some of the fields in the project. Using the Mapping Workbench to write to the ejb-jar.xml ensures that the ejb-jar.xml and the TopLink project information remain properly synchronized.

The use of all XML elements in the file are described in the EJB 2.0 specification.

weblogic-ejb-jar.xml

This descriptor file is specific to WebLogic Server and offers an opportunity to override some of the configuration settings in the server. Some of the elements that may require modification are:

<persistence-type>

A section that sets the persistence type. Note that this tag is not required by WebLogic 7.0, as its function is included in the <persistence-use> tag.

<persistence-use>

A section that specifies TopLink as the persistence storage mechanism.

For information on configuring the weblogic-ejb-jar.xml file, see "Configuring entity bean deployment descriptors".

toplink-ejb-jar.xml

The TopLink deployment descriptor is included in the JAR in the same META-INF directory as the other two deployment descriptors. This descriptor provides the information that TopLink needs to deploy the entities in the JAR. Because the entities deployed in a 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-class>

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.

Note: You can use a <project-xml> rather than a <project-class> if you choose. The <project-xml> element specifies a project deployment XML file that can be stored either in the deployable JAR file or left on the file system. For more information, see "Configuring entity bean deployment descriptors".

<connection-pool>

A sub-element of login, the fully-specified connection pool specifies the connection pool URL of the data source.

For more information on the options available for the <connection-pool> element, refer to the DTD in <install>\wls_cmp\toplink-wls-ejb-jar_903.dtd.

Map the entities to the database

This section describes the steps required to create the Single Bean project using the Mapping Workbench. It also introduces and addresses some issues related to mapping EJB 2.0 beans, such as relationships and reserved finders, which are not encountered in the Single Bean example.

For more information about creating projects using the Mapping Workbench, consult the Oracle91AS 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 to be persisted to the database. The Mapping Workbench can be used 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 runtime to persist the beans.

To create a TopLink project:

1. Create a new project. Click File > New Project.

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

3. Specify an ejb-jar.xml file to use for the project. You can either choose an existing file or create a new one. The ejb-jar.xml file is typically created by another tool, and the mapping information it contains is read and used by the Mapping Workbench (see step 7 below).

   If no ejb-jar.xml file is available, the Mapping Workbench can be used to create one and to populate the file with the information the Mapping Workbench requires. Once the file is created, however, other elements usually need to be added to the ejb-jar.xml file before it can be used with ejbc and in a deployable JAR.

   When the Mapping Workbench project is saved, changes to the ejb-jar.xml file can also be written out. See "Working with the ejb-jar.xml file" in the Oracle9iAS TopLink 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. While bean classes must to be added to the project at this point (for example, the Single Bean example requires the AccountBean class) referenced classes are not required. At this point the cmp and cmr fields do not appear on the AccountBean descriptor.

6. To specify the beans classes as bean descriptors, click Selected > Descriptor Type > Class Descriptor. This causes the Mapping Workbench to read the abstract getters/setters and ejb-jar.xml file for cmp and cmr fields.

   After setting the AccountBean to be an EJB descriptor, the cmp and cmr fields appear and are available for mapping.

7. Update the project from the ejb-jar.xml file by selecting the project and clicking Selected > Update Project from ejb-jar.xml. This is an optional step that is not required if you are generating the ejb-jar.xml file in the Mapping Workbench. However, the the Single Bean example uses an existing ejb-jar.xml file, so using it to update the project brings in two user-defined finders which appear in the AccountBean descriptor's Queries tab.

   The Mapping Workbench reads from and writes to the following elements in the ejb-jar.xml:

   • primkey-field

   • ejb-name

   • local-home

   • local

   • ejb-class

   • prim-key-class

   • abstract-schema-name

   • cmp-field

   • query and its sub-elements

   • relationships

8. Create database tables. The Single Bean example uses an EJB_ACCOUNT table to persist the bean to an EJB_ACCOUNT_SEQ table for sequencing. Ensure that the ACCOUNT_ID is the primary key in the EJB_ACCOUNT table. The tables 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" Oracle9iAS TopLink Mapping Workbench Reference Guide.

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

10. Map the cmp and cmr 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 EJB_ACCOUNT table.

11. Set up sequencing. The AccountBean uses TopLink sequencing for its primary key generation. In the Descriptor Info tab, select the Use Sequencing check-box and specify ACCOUNT_SEQ for the Name, and EJB_ACCOUNT and ACCOUNT_ID for the Table and Field.

12. 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 either the <project-class> or <project-xml> element is used depending on which export method was used.

Generate the deployable JAR file

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

• A WAR file containing contains the JSP code and associated configuration XML files.

• A deployable JAR file containing the interface and abstract bean classes, the classes (RMI stubs and implementation classes) generated by weblogic.ejbc, and the deployment descriptor XML files.

Using the Build Script

A build script is included in the ...\singlebean example directory which compiles the bean classes, runs weblogic.ejbc, and creates the EAR file. Running the build script places a copy of the EAR file in both the Single Bean directory and the server's deployment directory.

Windows users can use the build script as provided. Users of other platforms can use the build script as a template to create their own build script.

The build script can be modified and used to build deployable EAR or JAR files for other applications.

The build.cmd file uses the environment information in the <install>/setenv.cmd file (Under Windows) or the setenv.sh file (non-Windows). To avoid possible errors, ensure that your environment also matches these settings before running the script.

Deploy the JAR file

This can be done a number of different ways. See the WebLogic Server documentation for more detailed information on how to deploy an EJB JAR or an EAR into the server.