Configuring the Build Environment for JBoss

The rental enterprise application is part of the JDO Learning Tools. Its build target is rental-servlet-ejb. Chapters 8 and 10 describe how to configure the build environment and execute builds. If you have followed the instructions presented in these chapters successfully, you are ready to perform the additional configuration steps presented here. If you did not perform the configuration described in Chapters 8 and 10, you must perform the seven configuration steps described in Chapter 8 and the three configuration steps described in Chapter 10. Thereafter, continue with the following six configuration steps, which allow you to build the rental enterprise application. These configuration steps also allow you to build the five quote server EJBs.

Step Eleven: Install JBoss

In this step, you install the JBoss EJB container. JBoss is a full J2EE container that can be obtained with either a built-in Tomcat servlet container or a built-in Jetty servlet container. The JDO Learning Tools were developed using JBoss 3.0.4 with the Jetty servlet container. Any later version of JBoss should work equally well. If you don't have a suitable version of JBoss installed, go to the following URL: http://www.jboss.org. Follow the links to a download of JBoss with Jetty. Then unzip JBoss to install it. Follow the instructions that come with JBoss to start it up. If JBoss is properly installed and running, the URL http://localhost:8080/ jmx-console displays the JBoss service manager page.

The directory where you installed JBoss is referred to as the jboss-home directory in this book.

Estimated time for this step, excluding download: 30 minutes

Step Twelve: Configure JBoss and Tomcat to Work Together

In this step, you perform some configuration of JBoss that is required in order to be able to use JBoss with a stand-alone Tomcat installation configured as described in Chapter 10. The default JBoss configuration with Jetty uses some of the same ports as the default stand-alone Tomcat installation. There are a number of ways to resolve the port conflicts. You could use the built-in Jetty servlet container instead of the stand-alone Tomcat servlet container. Changing to the Jetty servlet container would require some modification of the build scripts. On the other hand, instead of using JBoss with Jetty, you could install JBoss with Tomcat. This change may also require some modification of the build scripts. The solution used in this book is to tweak the configurations of Tomcat and JBoss so that both can run together on the same machine as stand-alone services. In this fashion, those who are not interested in the EJB examples do not have to wrestle with an EJB container.

To run stand-alone Tomcat on the same machine as JBoss with Jetty, you make one modification to a JBoss configuration file and one modification to a Tomcat configuration file. First, edit the jboss-service.xml file found in the following directory under the jboss-home directory:

 server/default/deploy/jbossweb.sar/meta-inf 

Within this file, find the place where an AJP13 listener is added on port 8009. Comment out the portion of the XML defined by the Call tag. This prevents both Tomcat and JBoss from attempting to listen on the same port for proxy calls from a Web server.

Next, edit the server.xml file in the config directory under the tomcat-home directory. Find the place where the "Coyote HTTP/1.1 Connector on port 8080" is configured. Alter the port to another port, say 8000. This change reconfigures Tomcat to listen for HTTP connections on port 8000. Jetty within JBoss will continue to listen for HTTP connections on port 8080. The change is made in the Tomcat file because it can be changed in one place. Several JBoss configuration files specifically mention port 8080. After restarting Tomcat, you should be able to connect to Tomcat's documentation page by going to the following URL in your Web browser:

http://localhost:8000

After making the change, you would now use the new port number rather than the default port number of 8080 when following the examples in Chapter 10.

Estimated time for this step: 10 minutes

Step Thirteen: Configure Build Properties

In this step, you configure the build environment for JBoss. Edit the default.properties file in the bookants directory under your bookcode-home directory. Set the jboss.home property to point to your jboss-home directory.

Estimated time for this step: 5 minutes

Step Fourteen: Replace JDO Reference Implementation

If you have been using the JDO reference implementation for the examples up until this point, then in this step, you must switch to another implementation. You can skip this step if you have not been using the reference implementation of JDO.

Although it is possible to configure the JDO reference implementation for use with an EJB, the 1.0 reference implementation when used in this way is quite buggy. It is possible that later versions of the reference implementation will work better with EJBs. Until then, you should switch to one of the commercial implementations of JDO that offer free time-limited licenses.

If the vendor offers multiple versions of the JDO implementation, be sure to download the version that supports deployment to EJB containers. This is usually the more expensive product.

The commercial implementations have licensing schemes that require a license file or license key. You may have to request the trial license file or key, or the vendor may send it to you automatically as a result of downloading the trial version. Consult the vendor's documentation for more information about the license deployment issues.

The 1.0 version of the JDO Learning Tools contains builds for the Kodo, Lido, and IntelliBO commercial implementations. Later releases of the JDO Learning Tools may have builds for other commercial or open source implementations. To make the switch, go to Chapter 8 and follow the instructions for steps five through seven. The end of Chapter 8 also has a few comments about how the build scripts differ between the different JDO implementations.

Next, you need to deploy the datastore driver that the JDO implementation will use. You will have to determine what database you are using, and you may have to consult the vendor's documentation, to determine the JDBC driver to deploy. Once you determine the driver, copy its Jar or zip file to the server/default/lib directory under your jboss-home directory. When JBoss is started, you should see this file mentioned in the console log.

The builds in the JDO Learning Tools version 1.0 were tested with trial versions of the following commercial products:

• Kodo 2.4.1

• Lido 1.4.1

• IntelliBO 3.1.0

Later versions should work equally well.

Estimated time for this step, not including download: 1 hour

Step Fifteen: Configure the JDO Connection Factory

In this step, you create the configuration file for a JDO connection factory. JBoss accepts a pair of connection factory files, an xxx.rar file and a matching xxx-service.xml file, where xxx is an informative name such as kodo, lido, or intellibo. Some JDO vendors provide the RAR file prebuilt, and others require that it be built by the application developer.

The service XML file configures the JDO connection factory. The configuration properties generally correspond to the configurable properties of a PersistenceManagerFactory, except that the properties are expressed in XML rather than in a Java properties file. The builds supplied with the JDO Learning Tools will build the RAR files if necessary, and they come with the corresponding service XML file that worked in the test environment.

The following three build targets use a connection factory:

• sayings-stateless-cmt

• sayings-entity

• rental-servlet-ejb

The corresponding service XML files are contained in tool directories found under the com/ysoft/jdo/book/sayings/persistent directory and under the com/ysoft/jdo/ book/rental/ejb directory. The tool directories have the obvious names kodo, lido, and intellibo.

Since the service XML file is vendor dependent, the vendors of JDO implementations may modify this file in later versions of their product. To ensure that the service files that you are using are the latest ones available, rename the service files for your selected JDO implementation, which you can find in the JDO Learning Tools. Next, find the sample service XML file provided by the vendor and copy it to the JDO Learning Tools source, placing it beside the files that you renamed. Then edit the new service XML files, making sure that the settings are compatible with your runtime environment and compatible with the settings found in the original files that you renamed.

The remaining three build targets, listed here, use a persistence manager factory:

• sayings-stateless-bmt

• sayings-stateful-bmt

• sayings-stateful-cmt

These builds use a properties file to configure the persistence manager factory. Nevertheless, they also require that the RAR files be deployed. Deploying the RAR files makes the JDO implementation files available to any EJB, even to those EJBs that use a persistence manager factory instead of a connection factory.

Estimated time for this step: 30 minutes

Step Sixteen: Configure JNDI

In this step, you verify that the JNDI configuration for JDO Learning Tools is appropriate. The tools assume that the EJB container will be deployed on your machine. Consequently, the JNDI configuration refers to the localhost as the host machine for a JNDI lookup. If you have JBoss deployed on a remote machine, you will have to edit this configuration. It is found in the jndi.properties file in the resources directory under the bookcode-home directory.

Estimated time for this step: 5 minutes

You are now ready to build the rental enterprise application and the quote server examples.