The J2EETM Tutorial

Building, Packaging, Deploying, and Running the Application

To build the Duke's Bank application, you must have downloaded and unzipped the tutorial bundle as described in Downloading the Examples. When you install the bundle, the Duke's Bank application files are placed in the following directory structure of the j2eetutorial directory:

   /dd - deployment descriptors	
      /com - component classes	
      /web - JSP pages, images	
   /sql - database scripts	

To simplify building, packaging, and deploying the Duke's Bank application, the tutorial bundle includes deployment descriptors, source code, and a build.xml file that contains the automated ant tasks. If you haven't run ant yet, please see How to Build and Run the Examples.

After you compile the source code, the resulting class files will reside in the j2eetutorial/bank/build subdirectory. When you package the components and the application, the resulting archive files are placed in the j2eetutorial/bank/jar subdirectory.

Adding Groups and Users to the Realm

To run the J2EE application and Web clients, you must add groups and users to the default security realm. To create the Customer and Admin groups, add the user 200 to the Customer group, and add the user admin to the Admin group in deploytool:

  1. Select ToolsServer Configuration
  2. In the tree, select the Users node.
  3. Make sure that Default is selected in the Realm combo box.
  4. Click Add User.
  5. Click Edit Groups.
  6. Click Add.
  7. Enter Customer.
  8. Click Add.
  9. Enter Admin.
  10. Click OK.
  11. Enter 200 for User Name: and j2ee for Password:
  12. Select the Customer group from the Available Groups list.
  13. Click Add.
  14. Click Apply.
  15. Enter admin for User Name and j2ee for Password.
  16. Select the Admin Group from the Available Groups list.
  17. Click Add.
  18. Click OK.

You can perform the same tasks with the realmtool command-line utility:

  1. realmtool -addGroup Customer
  2. realmtool -add 200 j2ee Customer
  3. realmtool -addGroup Admin
  4. realmtool -add admin j2ee Admin

Starting the J2EE Server, deploytool, and Database

J2EE Server

Start the J2EE server:

j2ee -verbose


After the J2EE server reports startup complete, run deploytool:

  1. If the deploytool utility is not running, launch it from the command line:
  2. If deploytool is already running, reconnect to the J2EE server:
    1. Select FileAdd Server
    2. In the Add Server dialog box, enter localhost in the Server Name field.
    3. Click OK.


Start the Cloudscape database server:

cloudscape -start

Compiling the Enterprise Beans

In a different window, go to the j2eetutorial/bank subdirectory of the tutorial distribution and type this command:

ant compile-ejb

Packaging the Enterprise Beans

To package the enterprise beans, type the following:

ant package-ejb

The preceding command packages the class files and the deployment descriptors into the following EJB JAR files, which reside in the j2eetutorial/bank/jar subdirectory.


When packaging a component in this chapter, ant may report that it cannot find a file (such as account-ejb.jar) to delete. You may ignore these messages.

Compiling the Web Client

To compile the Web client, go to the j2eetutorial/bank directory of the tutorial distribution and execute the following:

ant compile-web

Packaging the Web Client

The Web client uses the Struts tag library discussed in The Example JSP Pages. Before you can package the Web client, you must download and install Struts version 1.0 from

Copy struts-logic.tld and struts.jar from jakarta-struts-1.0/lib to j2eetutorial/bank/jar. Then change to the j2eetutorial/bank directory and type the following:

ant package-web 

This command packages the servlet class, JSP pages, JavaBeans component classes, tag libraries, and the Web application deployment descriptor into web-client.war and puts this file in j2eetutorial/bank/jar.

Compiling the J2EE Application Client

To compile the application client, go to the j2eetutorial/bank subdirectory and run this command:

ant compile-ac

Packaging the J2EE Application Client

  1. Go to the j2eetutorial/bank directory and run this command:
    ant package-ac
    This command creates the app-client.jar file in the j2eetutorial/bank/jar directory.
  2. From the same directory, type the following:
    ant setruntime-ac 
    This command adds a runtime deployment descriptor (j2eetutorial/bank/dd/runtime-ac.xml) to app-client.jar.

Packaging the Enterprise Archive File

  1. To create the Duke's Bank enterprise archive file, go to the j2eetutorial/bank directory and run this command:
    ant assemble-app
    This command creates the DukesBankApp.ear file in the j2eetutorial/bank/jar directory.
  2. From the same directory, type the following:
    ant setruntime-app
    This command adds a runtime deployment descriptor (j2eetutorial/bank/dd/runtime-app.xml) to DukesBankApp.ear.

Opening the Enterprise Archive File

In deploytool, open the EAR as follows:

  1. Select File Open.
  2. Go to the j2eetutorial/bank/jar subdirectory.
  3. Select DukesBankApp.ear.
  4. Click Open Object.

You should see the screen shown in Figure 18-8 in deploytool:

Figure 18-8 Duke's Bank Application Archives and Components

Reviewing JNDI Names

With DukesBankApp selected, click the JNDI Names tab. The JNDI Name column is shown in Figure 18-9. The order may be a little different on your own display.

Figure 18-9 JNDI Names

A JNDI name is the name the J2EE 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. The actual 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:

try {	
   customerControllerHome =	
   customer = customerControllerHome.create();	
} catch (Exception NamingException) { 	
public static CustomerHome getCustomerHome() throws 
NamingException {	
   InitialContext initial = new InitialContext();	
   Object objref = initial.lookup(	

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 J2EE server uses it to look up the CustomerControllerEJB bean. In Figure 18-9 you see that CustomerControllerEJB 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 MyCustomerController, and the J2EE server uses the MyCustomerController JNDI name to find the corresponding CustomerControllerEJB object.

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

The JNDI name for the database driver is jdbc/Cloudscape. This name is the default coded name supplied in a configuration file of your J2EE SDK installation. For more information, see the Configuration Guide of the J2EE SDK.

Mapping the Security Roles to Groups

To map the BankAdmin role to the Admin group and the BankCustomer role to the Customer group:

  1. In deploytool, select DukesBankApp.
  2. In the Security tab, select the BankAdmin role from the Role Name list.
  3. Click Add.
  4. In the User Groups dialog box, select the Admin group in the Group Name list.
  5. Click OK.
  6. In the Security tab, select the BankCustomer role from the Role Name list.
  7. Click Add.
  8. In the User Groups dialog box, select the Customer group in the Group Name list.
  9. Click OK.
  10. From the main menu, select FileSave.

Figure 18-10 shows the BankCustomer role selected and the Customer group to which it is mapped.

Figure 18-10 BankCustomer Role Mapped to Customer Group

Deploying the Duke's Bank Application

To deploy the application:

  1. Select the DukesBankApp application.
  2. Select ToolsDeploy.
  3. Select the checkbox labeled Return Client Jar. By default, the directory for the returned JAR file is the same as where the EAR file is stored. The default name of the client JAR file is the application name with Client.jar appended, in this case, DukesBankAppClient.jar.
  4. Click Finish.

Creating the Bank Database

You have to create and enter data into the appropriate tables so that the enterprise beans have something to read from and write to the database. To create and populate the database tables, in a terminal window go to the j2eetutorial/bank directory and type the following commands:

  1. ant db-create-table
  2. ant db-insert

Running the J2EE Application Client

To run the J2EE application client:

  1. In a terminal window, go to j2eetutorial/bank/jar.
  2. Set the APPCPATH environment variable to DukesBankAppClient.jar.
  3. To run the English version of the client, execute the following command:
    runclient -client DukesBankApp.ear -name BankAdmin 
  4. To run the Spanish version, include the es language code:
    runclient -client DukesBankApp.ear -name BankAdmin es
    The DukesBankApp.ear parameter is the name of the J2EE application EAR file, and the BankAdmin parameter is the display name of the application client.
  5. At the login prompts, type in admin for the user name and j2ee for the password. The next thing you should see is the application shown in Figure 18-11.

Figure 18-11 BankAdmin J2EE Application Client

Running the Web Client

To run the Web client:

  1. Open the bank URL, http://<host>:8000/bank/main, in a Web browser. If your J2EE server is running on the same host as your Web browser, replace <host> with localhost. To see the Spanish version of the application, set your browser language preference to any Spanish dialect.
  2. The application will display the login page. Enter 200 for the customer ID and j2ee for the password. Click Submit.
  3. Select an application function: Account List, Transfer Funds, ATM, or Logoff. Once you have a list of accounts, you can get an account history by selecting an account link.

Note: The first time you select a new page, particularly a complicated page like an account history, it takes some time to display because the J2EE server must translate the page into a servlet class and compile and load the class.

If you select Account List, you will see the screen shown in Figure 18-12.

Figure 18-12 Account List