Building, Packaging, Deploying, and Running the Application

To build the Duke's Bank application, you must have installed the tutorial bundle as described in About the Examples. When you install the bundle, the Duke's Bank application files are located in the <INSTALL>/j2eetutorial14/examples/bank/ directory:

/bank   /provided-jars - packaged J2EE application containing the enterprise beans and web and application clients
  /sql - database scripts
  /src    /com - component classes
      /sun/ebank/appclient       /sun/ebank/ejb       /sun/ebank/util       /sun/ebank/web  /web - JSP pages, images

After you compile the source code, the resulting files will reside in the <INSTALL>/j2eetutorial14/examples/bank/build/ directory.

Setting Up the Servers

Before you can package, deploy, and run the example, you must first set up the Derby database server with customer and account data, and you must add some resources to the Application Server.

Starting the Application Server

Before you can start this tutorial, the Application Server must be running. For information on starting the Application Server, see Starting and Stopping the Application Server.

Creating the Bank Database

You create and enter data into the appropriate tables so that the enterprise beans have something to read from and write to the database.

Note: Application Server 8.2 includes a copy of the open source Derby database server. Application Server 8.0/ 8.1 includes the PointBase database server. If you are using Application Server 8.0/8.1, either follow the instructions in the J2EE Tutorial at http://java.sun.com/j2ee/1.4/docs/tutorial-update6/doc/index.html that works with Application Server 8.0/8.1 or upgrade to Application Server 8.2 (see http://java.sun.com/j2ee/1.4/download.html#appserv to download).

To create and populate the database tables, follow these steps:

In a terminal window or command prompt, go to the <INSTALL>/j2eetutorial14/examples/bank/ directory.

Execute the command asant create-db_common. This asant task executes the SQL commands contained in <INSTALL>/j2eetutorial14/examples/bank/sql/create-table.sql. The SQL commands delete any existing tables, create new tables, and insert data.

Capturing the Database Schema

After you create and populate the tables, you capture the structure of the tables into a schema file used to map the table data to enterprise bean fields and relationships. To capture the schema, follow these steps:

In a terminal window or command prompt, go to the <INSTALL>/j2eetutorial14/examples/bank/ directory.

Execute the following command:

asant capture-db-schema

This task invokes the capture-schema command and saves the resulting schema file in <INSTALL>/j2eetutorial14/examples/bank/build/dukesbank.dbschema.

Creating the JDBC Data Source

The Duke's Bank enterprise beans reference the database having the JNDI name jdbc/BankDB. That JNDI name must be mapped to a JDBC data source in the Application Server. You create the data source using the Admin Console following the procedures described in Creating a Data Source. When you create the JDBC data source, name it jdbc/BankDB and map it to DerbyPool.

Adding Users and Groups to the File Realm

To enable the Application Server to determine which users can access enterprise bean methods and resources in the web client, add users and groups to the server's file security realm using the Admin Console following the procedures described in Managing Users. Add the users and groups listed in Table 36-3.

Table 36-3 Duke's Bank Users and Groups
User	Password	Group
`200`	`j2ee`	`bankCustomer`
`bankadmin`	`j2ee`	`bankAdmin`

Compiling the Duke's Bank Application Code

To compile the enterprise beans, application client, and web client, go to the <INSTALL>/j2eetutorial14/examples/bank/ directory of the tutorial distribution and execute the command asant build.

Packaging and Deploying the Duke's Bank Application

The instructions that follow for packaging and deploying Duke's Bank assume that you are familiar with the deploytool procedures for packaging enterprise beans, application clients, and web applications described in previous chapters of the tutorial. If after following these procedures you have trouble deploying or running the application, you can use the EAR provided in <INSTALL>/j2eetutorial14/examples/bank/provided-jars/ to run the example.

Packaging the Enterprise Beans

Create an EJB JAR module named DukesBankEJBJAR in <INSTALL>/j2eetutorial14/examples/bank/.

Add the ejb and util packages under <INSTALL>/j2eetutorial14/examples/bank/build/com/sun/ebank/, and dukesbank.dbschema in <INSTALL>/j2eetutorial14/examples/bank/build/.

Set up the entity beans:

Set up each CMP 2.0 entity bean listed in the following tables using the Enterprise Bean wizard:

Table 36-4 Settings for AccountBean
Setting	Value
Local Home Interface	`LocalAccountHome`
Local Interface	`LocalAccount`
Persistent Fields	`accountId`, `balance`, `beginBalance`, `beginBalanceTimeStamp`, `creditLine`, `description`, `type`
Abstract Schema Name	`AccountBean`
Primary Key Class	Existing field `accountId`

Table 36-5 Settings for CustomerBean
Setting	Value
Local Home Interface	`LocalCustomerHome`
Local Interface	`LocalCustomer`
Persistent Fields	`city`, `customerId`, `email`, `firstName`, `lastName`, `middleInitial`, `phone`, `state`, `street`, `zip`
Abstract Schema Name	`CustomerBean`
Primary Key Class	Existing field `customerId`

Table 36-6 Settings for TxBean
Setting	Value
Local Home Interface	`LocalTxHome`
Local Interface	`LocalTx`
Persistent Fields	`amount`, `balance`, `description`, `timeStamp`, `txId`
Abstract Schema Name	`TxBean`
Primary Key Class	Existing field `txId`

Table 36-7 Settings for NextIdBean
Setting	Value
Local Home Interface	`LocalNextIdHome`
Local Interface	`LocalNextId`
Persistent Fields	`beanName`, `id`
Abstract Schema Name	`NextIdBean`
Primary Key Class	Existing field `beanName`

Set up the entity bean relationships according to Table 36-8:

Table 36-8 OrderApp Bean Relationships
Multi-plicity	Bean A	Field Referencing Bean B and Field Type	Bean B	Field Referencing Bean A and Field Type
:	`AccountBean`	`customers, java.util.Collection`	`CustomerBean`	`accounts`, `java.util. Collection`
1:*	`AccountBean`	none	`TxBean`	`account`

In the Sun-specific Settings->CMP Database dialog:

Set the JNDI name to jdbc/BankDB.

Click Create Database Mappings and select dukesbank.dbschema under Map to Tables in Database Schema File.

Confirm the fields and relationships were properly mapped by selecting each enterprise bean under Persistent Field Mappings.

Set the EJB-QL finder queries according to Table 36-9. To set the finder queries, select the bean in the tree, select the Entity tab, then select Find/Select Queries.

Table 36-9 Finder Queries in Duke's Bank
Enterprise Bean	Method	EJB QL Query
`AccountBean`	`findByCustomerId`	`select distinct object(a) from AccountBean a, in (a.customers) as c where c.customerId = ?1`
`CustomerBean`	`findByAccountId`	`select distinct object(c) from CustomerBean c, in (c.accounts) as a where a.accountId = ?1`
`CustomerBean`	`findByLastName`	`select object(c) from CustomerBean c where c.lastName = ?1`
TxBean	findByAccountId	select object(t) from TxBean t where t.account.accountId = ?3 and (t.timeStamp >= ?1 and t.timeStamp <= ?2)

Set the Transaction Attributes for the NextIdBean.getNextId method to Requires New. To do this, select the NextIdBean in the tree, select the Transactions page, and then change the Transaction Attribute for the getNextId method.

Invoke the Enterprise Bean Wizard for each of the stateful session beans in Table 36-10.

Table 36-10 Stateful Session Beans
Session Bean	Remote Home Interface	Remote Interface	Implementation Class
`Account ControllerBean`	`Account ControllerHome`	`Account Controller`	`AccountControllerBean`
`Customer ControllerBean`	`Customer ControllerHome`	`Customer Controller`	`CustomerControllerBean`
`TxControllerBean`	`TxControllerHome`	`TxController`	`TxBean`

Add EJB references from the session beans to the local entity beans listed in the following tables.

Table 36-11 EJB References in AccountControllerBean
Coded Name	EJB Type	Interfaces	Home Interface	Local/Remote Interface	Enterprise Bean Name
`ejb/account`	Entity	Local	`Local AccountHome`	`LocalAccount`	`AccountBean`
`ejb/ customer`	Entity	Local	`Local CustomerHome`	`LocalCustomer`	`CustomerBean`
`ejb/nextId`	Entity	Local	`Local NextIdHome`	`LocalNextId`	`NextIdBean`

Table 36-12 EJB References in CustomerControllerBean
Coded Name	EJB Type	Interfaces	Home Interface	Local/Remote Interface	Enterprise Bean Name
`ejb/ customer`	Entity	Local	`Local CustomerHome`	`Local Customer`	`CustomerBean`
`ejb/nextId`	Entity	Local	`Local NextIdHome`	`Local NextId`	`NextIdBean`

Table 36-13 EJB References in TxControllerBean
Coded Name	EJB Type	Interfaces	Home Interface	Local/Remote Interface	Enterprise Bean Name
`ejb/account`	Entity	Local	`Local AccountHome`	`Local Account`	`AccountBean`
`ejb/ tx`	Entity	Local	`Local TxHome`	`LocalTx`	`TxBean`
`ejb/nextId`	Entity	Local	`Local NextIdHome`	`Local NextId`	`NextIdBean`

Set the Transaction Management of the session beans to Container-Managed.

Save the module.

Packaging the Application Client

Invoke the Application Client wizard.

Create an application client module named DukesBankACJAR in <INSTALL>/j2eetutorial14/examples/bank/.

Add the appclient, util, and ejb/exception packages and the ejb/*/*Controller* home and remote interfaces (AccountController, AccountControllerHome, CustomerController, CustomerControllerHome, TxController, TxControllerHome) under <INSTALL>/j2eetutorial14/examples/bank/build/com/sun/ebank/ to the JAR.

Select appclient.BankAdmin as the application client main class.

Add EJB references to the session beans listed in Table 36-14.

Table 36-14 EJB References to Session Beans


Coded Name	EJB Type	Interfaces	Home Interface	Local/Remote Interface	JNDI Name of Session Bean
`ejb/account Controller`	Session	Remote	`Account ControllertHome`	`Account Controller`	`Account ControllerBean`
`ejb/customer Controller`	Session	Remote	`Customer ControllerHome`	`Customer Controller`	`Customer ControllerBean`

Save the module.

Packaging the Web Client

Create a new web component using the Web Component wizard. On the first page of the wizad, create a new web module named DukesBankWAR in <INSTALL>/j2eetutorial14/examples/bank/.

Add the Dispatcher servlet web component in <INSTALL>/j2eetutorial14/examples/bank/build/com/sun/ebank/web/.

On the Choose Component Type page, select Servlet.

On the Component General Properties page, select the Dispatcher servlet class.

Select Finish to close the wizard.

With DukesBankWar selected, add content to the web module.

Add the web, util, and ejb/exception packages and the ejb/*/*Controller* home and remote interfaces (AccountController, AccountControllerHome, CustomerController, CustomerControllerHome, TxController, TxControllerHome) under <INSTALL>/j2eetutorial14/examples/bank/build/com/sun/ebank to the module.

Add the template directory, all the JSP pages, the WebMessages*.properties files and tutorial-template.tld under <INSTALL>/j2eetutorial14/examples/bank/build/ to the module.

In the web module contents editor, drag the files WebMessages*.properties from the context root to WEB-INF/classes.

Set the context root to /bank.

Add the /accountHist, /accountList, /atm, /atmAck, /main, /transferAck, /transferFunds, and /logoff aliases to the Dispatcher component.

Add EJB references to the session beans listed in Table 36-15.

Table 36-15 EJB References to Session Beans
Coded Name	JNDI Name of Session Bean
`ejb/accountController`	`AccountControllerBean`
`ejb/customerController`	`CustomerControllerBean`
`ejb/txController`	`TxControllerBean`

Select the JSP tab to add a JSP property group named bank. The property group applies to the URL pattern *.jsp. Add the include prelude /template/prelude.jspf.

Select the Context tab to add a context parameter named javax.servlet.jsp.jstl.fmt.localizationContext and value WebMessages.

Select the Security tab to add a security constraint.

Select Form Based as the user authentication method. Select the Settings button to set the authentication settings as follows: file for the realm name, /logon.jsp for the login page, and /logonError.jsp for the error page.

Add a security constraint and a web resource collection. Use the default names provided by deploytool.

Select Edit Collections to add the URL Patterns /main, /accountList, /accountHist, /atm, /atmAck, /transferFunds, and /transferAck to the web resource collection. Select the GET and POST HTTP methods.

Select Edit Roles to add the authorized role bankCustomer.

Save the module.

Packaging and Deploying the Application

Create a J2EE application named DukesBankApp in <INSTALL>/j2eetutorial14/examples/bank/.

Select Add to Application from the File menu to add the DukesBankACJAR application client module to DukesBankApp.

Select Add to Application from the File menu to add the DukesBankEJBJAR EJB module to DukesBankApp.

Select Add to Application from the File menu to add the DukesBankWAR web module to DukesBankApp.

Select the Roles tab to add the security roles bankAdmin and bankCustomer.

Add the following security settings for the enterprise beans.

AccountControllerBean: In the Security tab, restrict access to users in the bankAdmin security role for the methods removeCustomerFromAccount, removeAccount, createAccount, and addCustomerToAccount. In the General tab, click the Sun-specific Settings button, and then click the IOR button in the General frame. In the As Context frame, set Required to true, and the realm to file.

CustomerControllerBean: In the Security tab, restrict access to users in the bankAdmin security role for the methods getCustomersOfAccount, createCustomer, getCustomersOfLastName, setName, removeCustomer, and setAddress. In the General tab, click the Sun-specific Settings button, and then click the IOR button in the General frame. In the As Context frame, set Required to true, and the realm to file.

TxControllerBean: In the Security tab, restrict access to users in the bankCustomer security role for the methods getTxsOfAccount, makeCharge, deposit, transferFunds, withdraw, and makePayment.

Start the Application Server.

From the General tab of DukesBankApp, select Sun-specific Settings to map the bankCustomer role to the bankCustomer group and to map the bankAdmin role to the bankAdmin group.

Save the application.

Deploy the application. In the Deploy DukesBankApp dialog box, select the Return Client Jar checkbox.

After you have packaged all the modules, deploytool should look like Figure 36-8.

Figure 36-8 Duke's Bank Modules and Components

Reviewing JNDI Names

With DukesBankApp selected, click theSun-specific Settings button on the General tab to view the JNDI Names. The JNDI Name column is shown in Figure 36-9. The order may be a little different in your own environment.

Figure 36-9 Duke's Bank JNDI Names

A JNDI name is the name the Application Server uses to look up enterprise beans and resources. When you look up an enterprise bean, you supply statements similar to those shown in the following code.

try {
  customerControllerHome =
    EJBGetter.getCustomerControllerHome(); 
  customer = customerControllerHome.create();
} catch (Exception namingException) { 
  namingException.printStackTrace(); 
}

public static CustomerControllerHome
  getCustomerControllerHome() throws   NamingException {
  InitialContext initial = new InitialContext();
  Object objref = initial.lookup(
    CodedNames.CUSTOMER_CONTROLLER_EJBHOME);

The lookup takes place in the third line of code, in which the getCustomerControllerHome method of com.sun.ebank.utilEJBGetter is called. EJBGetter is a utility class that retrieves a coded JNDI name from com.sun.ebank.util.CodedNames.

In this example, the application client is looking up the coded name for the CustomerController remote interface. BankAdmin (the display name for the main class of the application client) references ejb/customerController, which is the coded name defined in CodedNames for the CustomerController remote interface.

The JNDI name is stored in the J2EE application deployment descriptor, and the Application Server uses it to look up the CustomerControllerBean bean. In Figure 36-9 you see that CustomerControllerBean is mapped to the same JNDI name as is ejb/customerController. It does not matter what the JNDI name is, as long as it is the same name for the remote interface lookup as you use for its corresponding bean. So, looking at the table, you can say that the application client (BankAdmin) looks up the CustomerController remote interface, which uses the JNDI name of CustomerControllerBean, and the Application Server uses the CustomerControllerBean JNDI name to find the corresponding CustomerControllerBean object.

The other rows in the table have the mappings for the other enterprise beans. All of these beans are stored in the JAR file you added to the J2EE application during assembly. Their implementations have coded names for looking up either other enterprise beans or the database driver.