Enterprise JavaBeans For Dummies

• Getting Started
• Exploring the sample projects
• Configuring the JBoss Application Server
• Deploying and running the ATM application
• Deploying and running the Hello World Application
• Changes
• Known Issues
• Feedback and Support

The Enterprise JavaBeans For Dummies book comes with two sample applications that illustrate the fundamental principles of developing EJB applications according to the EJB 2.0 specification. In this file you'll discover a little more about the structure of these applications, and how to deploy them to JBoss application server. The applications are already set up to be deployed to JBoss. However, with minimal additional configuration, they can be deployed to any J2EE application server that provides the following services:

• Java Messaging Service

• JavaMail

• Full support for EJB 2.0 applications

• Support for JSP applications (optional)

[back to contents]

To get started, download the ZIP file (located on the Download tab) containing the ATM application and source code that ship with Enterprise Javabeans For Dummies. To unpack the archive, you'll need an unzipping tool, such as Winzip. The root directory for this package is \code. Under this directory, you'll find two different directories:

• ATMProject — This is the project folder for the ATM application (referred to throughout the book).

• HelloWorldProject — This is the project folder for the HelloWorld application.

These two projects are both organized in the follow structure:

• application — This directory contains the materials for building a Enterprise ARchive File (EAR). EAR files are standard deployment files for Java enterprise applications. They're very easy to build, and make deployment a dream. Take some time to review the application.xml file, located in the code\<project>\application\META-INF directory. You can read more about creating EAR files in the J2EE 1.3 specification available from Sun Microsystems.

• clientCode — This directory contains the information and files you need to connect to the EJB application from a client. Both clientCode directories contain Web client and console applications for their respective sample applications.

• docs — The docs directory contains a JavaDoc that describes the classes for each project. The JavaDoc root — index.html — is located in the docs directory for each project. Before deploying the ATM application, I recommend viewing the JavaDoc and familiarizing yourself with the structure and classes contained in the project.

• out - This directory contains the compiled source code, deployment descriptors, and deployment jar files for use with both sample projects.

• source — This directory contains all the Java source code for the sample projects.

Both the ATM application and the HelloWorld application have been completely developed, compiled, deployed and tested using JBoss application server and Jetty Web Server. JBoss Application Server is bundled with Jetty by default and is available from JBoss Group, LLC. You can also get JBoss Application Server from sourceforge.net in the JBoss project area. Check both locations and get the latest version available. Installation instructions for JBoss Application Server are available at the JBoss Group website, on the page http://www.jbossgroup.com/doco.jsp. You should be able to find the information you need in the free user documentation. If you have deployment problems, visit JBoss Group's Installation & Configuration forum.

Before deploying either project provided with Enterprise JavaBeans For Dummies, I strongly recommend deploying the sample HelloWorld application supplied with JBoss. You can discover more about the JBoss HelloWorld application in the free JBoss documentation (www.jbossgroup.com/doco.jsp). If you have difficulties deploying any application provided with Enterprise JavaBeans For Dummies, read the JBoss deployment documentation and deploy the JBoss HelloWorld application before doing anything else. That will help you to verify that JBoss is setup and running properly.

[back to contents]

The first step to deploying the ATM project is performing some minor configuration to the JBoss Application Server. You have two important configuration steps. You must identify your mail service properties to JBoss's JavaMail API, and you must identify the jndi.properties to your JBoss client applications.

Setting Up The JavaMail Service

The ATM application makes use of JBoss's JavaMail services to deliver an e-mail message containing a "prototype" bank statement. To make use of this feature you must first provide JBoss with information about your e-mail provider. If you are configuring this information from inside a corporate network, you should be able to obtain the required information from a system administrator. If you are performing this configuration from home, you should be able to obtain the required information from your Internet Service Provider (ISP).

1. The first order of business in setting up the e-mail service is gathering some information that you'll need to use further on in the process. To get the JBoss mail service running, you'll need to know the following information:
   • The username and password for your e-mail account. You generally have to supply this information when you log on to your ISP to access the Web.
   • The POP Server name and SMTP Server name for your ISP. These names are supplied by your ISP, and you can get them out of the program that you use for sending e-mails. Both are usually in the form of servername.domain.com.
   • Your e-mail address. The JavaMail service will automatically put the e-mail address you specify here in the from line of messages that it sends. This must be a properly formatted e-mail address, such as [email protected].

2. After you have the information from Step 1, you need to store that information in the mail-service.xml file, located in the deploy directory of your the JBoss installation. The contents of the mail-service.xml file should look like the source in Listing 1. The bold lines in Listing 1 need to be updated with the information you collected in Step 1.
   • Replace nobody in the User attribute with your username.
   • Replace password in the Password attribute with your password.
   • Replace the nobody in the property named mail.user with your username.
   • Replace the value of the property named mail.pop3.host with your mail server name.
   • Replace the value of the property named mail.smtp.host with your SMTP server name.
   • Replace the value of the property named mail.from with your e-mail address.

3. Directly above the User attribute, where you put your username, there's a line that has an attribute called JNDIName. The default JNDI name should be java:/Mail. That's the name that the ATM application will use to look up a reference to the JavaMail service. I've configured that application to use the name java:/Mail. If your JNDIName value has a different value, change it so that it says java:/Mail.

From the perspective of EJB applications, services like JBoss's JavaMail are referred to as eternal resources. You can mail references to external resources by defining a <resource-ref> element in the deployment descriptor for the JavaBean that uses the resource. To discover more about creating <resource-ref> tags, refer to Enterprise JavaBeans For Dummies.

A <resource-ref> tag gets mapped — or connected — to a service in the vendor specific deployment descriptor. For JBoss, that descriptor is called jboss.xml, and it's located in the META-INF directory of the ATM application, along with the ejb-jar.xml file. There is no standard for the format of vendor specific deployment descriptors. To discover the format for referring to the JavaMail service, in JBoss, you can open and review the jboss.xml file, shipped with the ATM application.

[back to contents]

Exposing the jndi.properties file to your client application

The jndi.properties file contains information necessary for client applications to make use of the JBoss application server. In JBoss, the jndi.properties file is located in the directory JBOSS_DIST/server/default/conf. To expose the jndi.properties file to remote client applications, first copy the file to the JBOSS_DIST/client directory. Next, edit the jndi.properties file in your default text editor. When you open the jndi.properties file, the content should look something like the code in Listing 2.

For the ATM application to work properly, you must uncomment the last line (yes, the one you're told not to uncomment in the file). Remember that as you made a copy of this file and moved it to JBOSS_DIST/client directory, the changes that you make will have not impact on the performance of the server. To uncomment the last line, simply delete the # symbol located at the beginning of the file. Then save the changes and exit.

If your JBoss installation is not located on your personal computer, you must replace the localhost term at the end of the last line in the jndi.properties file with the URL to the host computer. The URL identifies the computername, domain, and port number of the computer on which JBoss is listening for invocations. The syntax for the url is name.domain.com.

[back to contents]

Deploying the ATM application is very simple. You have performed the minimal configuration steps described in the previous section, your ready to deploy. The deployment file for ATM application is called atmApplication.ear and is located in the code/atmProject/application directory. To deploy the application to JBoss, simply copy this file and paste it into the JBOSS_DIST/server/default/deploy directory. You can deploy the file after you have started JBoss, or before. It makes no difference.

After you have deployed the ATM application, JBoss takes a few seconds to unpack the contents of the application and initialize all the application services. When JBoss is finished deploying the application, it will report that the atmApplication has been successfully deployed in the console window. Once you see that message, you can proceed to running the client application.

Running the Console Client

The ATM application is shipped with a web client and a console client. You must run the console client first, as the console creates default users and accounts that are used by the web client. The console client is executed from a batch file contained in the code/atmProject/clientCode directory. To execute the console client, start by opening a console window (or Dos window if you're using windows). Change directories until you're located in the clientCode directory. In that directory, you see a file called atmSetup.bat. Execute the atmSetup.bat filed by typing atmSetup at the command prompt and pressing enter. The atmSetup program performs the following operations:

• Two users are created - Sam Spade (username: sspade, password: 123), and Jim Dandy (username jdandy, password: 123).

• Accounts and addresses are added to both users.

• Deposit, withdraw and transfer algorithms are tested.

• A third user (Harriet Hightower) is created using Bean Managed Persistence. Harriet is subsequently removed.

Once the atmSetup program is run, the ATM application is initialized and ready to support access from a web client.

Running The Web Client

While writing this book I planned to deploy the web client to Tomcat. However, when I was testing the application a stable bundled version of Tomcat and JBoss 3.0 was not available. Never fear, for JBoss is bundled with a web server called Jetty by default. I was able to test the application using the Jetty web server with no special changes. In fact, when you deploy the atmApplication.ear file, you've already deployed the web application to Jetty. It's that easy! To run the web client, perform the following steps:

1. If you haven't run the console client for the ATM application, run the console application now. Refer to Running The Console Client for more information.
2. Launch your web browser. In the address box, type the address: http://localhost:8080/atm/ATMLogin.jsp. 8080 is the default port number that Jetty listens for request on.
3. Supply the username and password for your prefered banking customer (Jim Dandy or Sam Spade).

If you are not running your JBoss application server from your local computer, you'll have to replace the localhost segment of the web address to the computer that is hosting JBoss application server.

[back to contents]

The HelloWorld application can be deployed in much the same way the ATM Application is deployed. The deployment file is called helloWorld.ear, and is located in the code\HelloWorldProject\application directory. To deploy the file, simply copy it and paste it in the JBOSS_DIST\server\default\deploy directory.

Running The HelloWorld Console client

You can run the HelloWorld application from the console by launching a command prompt and changing directories to the \HelloWorldProject\clientCode directory. In the clientCode directory, you will find a batch file called helloWorld.bat. Type HelloWorld.bat at the command prompt to execute this file. Running The HelloWorld Web Client

The HelloWorld application can also be invoked from a Web Browser. To run the HelloWorld web client, simply launch your favorite Web Browser and in the Address box type: http://localhost:8080/helloWorld. This should return a web page with the Hello World! messaged embedded.

If you are not running your JBoss application server from your local computer, you'll have to replace the localhost segment of the web address to the computer that is hosting JBoss application server.

[back to contents]

In the process of developing an application, the application changes periodically to support changing needs. Unfortunately, book publication schedules have a lifecycle of their own and it is difficult to keep books up to date with the latest material, or to reflect changes of the application in the book. In this section you will find changes that have been implemented in the ATM Application and the HelloWorld application after since the publication date of the book.

• The HelloWorld.jsp page has been modified in the source to correct a minor syntax error.

• Changes to the JBoss application server during beta testing required a modification of the JNDI name for the default Datasource in the jboss.xml file for the ATM Project.

[back to contents]

In other words, do as I say, not as I do.

• You will notice that the balances for accounts encounter what appear to be strange rounding errors after a few changes. This is a result of floating point math, and the use of the float and double types to hold account balances. For our purposes this is a cosmetic issue. But in the real world the preferred method for managing money is to create a Money class that allows only two digits of precision.

[back to contents]

I have done my best to provide sample applications of the highest quality with this book. I care strongly about delivering a quality product, and providing support for that product. I'm interest in your feedback, and assisting with any support issues related to the projects in this book. I am also available to consult on Java Enterprise Application projects. If you need assistance, or simply want to tell me about your experience with the book, please send me an e-mail at [email protected]. Thank you for purchasing Enterprise JavaBeans For Dummies!

[back to contents]