Building, Packaging, Deploying, and Running the Application - The J2EE 1.4 Tutorial

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.

All of the material in The J2EE(TM) 1.4 Tutorial is copyright-protected and may not be published in other works without express written permission from Sun Microsystems.