|Deploying The ATM Application To JBoss Application Server|
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:
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:
These two projects are both organized in the follow structure:
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.Configuring the JBoss Application Server
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).
Listing 1: Default mail-service.xml File
<?xml version="1.0" encoding="UTF-8"?>
<!-- Change to the user who will receive mail -->
<!-- Change to the mail server -->
<!-- Change to the SMTP gateway server -->
<!-- Change to the address mail will be from -->
<!-- Enable debugging output from the javamail classes
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.
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.
Listing 2: The jndi.properties File
# Do NOT uncomment this line as it causes in VM calls to go over
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.Deploying and running the ATM application
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:
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:
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.Deploying And Running The HelloWorld Application
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.Changes
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.
In other words, do as I say, not as I do.
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 firstname.lastname@example.org. Thank you for purchasing Enterprise JavaBeans For Dummies!