Novell Home

AppNote: How to Deploy exteNd Director 4.1 Enterprise On JBoss/Jetty 3.2.1

Novell Cool Solutions: Feature
By Ulrich Romahn

Digg This - Slashdot This

Posted: 14 Jan 2004
 

Ulrich Romahn is a Novell Senior Technical Manager. You may contact him at Ulrich.Romahn@novell.com

Contents

Overview

JBoss bundled with Jetty as the JSP/Servlet engine has become one of the most popular free and open source J2EE application servers. Although JBoss 3.x is not fully J2EE1.3 compliant, it is believed to be almost 99.9% J2EE1.3 compliant. Also, due to its flexible modular architecture, it is possible to replace certain components with other third party components without having to write complex integration code. As an example of this, the most recent production-quality version of JBoss 3.2.1 is also available as a bundle with Tomcat 4.1.24.

This paper describes in detail the setup and deployment of a Director 4.1 Enterprise project onto a JBoss 3.2.1 application server bundled with Jetty. It is anticipated that the procedures described herein will also be valid for future versions of JBoss 3.X but most likely not for JBoss 4.x.

In summary, this document gives details about:

  • Acquiring and installing the corresponding version of JBoss 3.2.1


  • Generating a Director WAR and EAR project with XWB 4.1.1 and configuration for deployment


  • Configuration of JBoss for a Director (WAR and EAR) deployment


Install and Setup JBoss 3.2.1

Pre-Requisites

The installation this document is based on the following configuration. However, it is expected that it should also work on different environments:

Hardware: Dell C640 Laptop, 2 GHz P4, 1GB RAM, 40GB HD

Operating System: Windows XP Professional SP1

Before attempting to install JBoss, it is recommended to have a RDBMS and a current JDK (preferably J2SDK1.4.1) installed on this machine. Since Director 4.1 does not yet support MySQL, the only options on a Windows platform would be ASA, MS SQL Server, Oracle 8 or 9i, and DB2.

For this document, JBoss was running on J2SDK1.4.1_02 and accessing a local Oracle 9i DB server.

One final pre-requisite is the assumption that Novell exteNd Workbench 4.1.1 and Director 4.1 Enterprise has been successfully installed on this machine.

Downloading and Installing JBoss 3.2.1

JBoss 3.2.1 can be easily downloaded from http://www.jboss.org/products/jbossas/downloads

Or alternatively from http://sourceforge.net/projects/jboss

Make sure to download the appropriate format for your platform.

NOTE: for installation on a UNIX/Linux platform, it is recommended to download the tar.gz file. The Windows Zip file contains script files with the Windows line-terminators (CR+LF) instead of the Unix version (CR only). Shell-scripts with this line-terminator won't run on Unix/Linux machines and have to be converted.

After the download, unpack the package to a location of your choice.

You will end up with a similar folder structure (in my case, I unpacked it into C:\Java).


Configuring JBoss 3.2.1

Configuring JBoss 3.2.1 bundled with Jetty is pretty easy and straight forward.

For the purpose of this document, we will use the term JBOSS_HOME for the path where JBoss has been installed (in this example, JBoss_HOME=C:\Java\jboss-3.2.1).

Basic Configuration

By default, JBoss comes with three basic configurations: 'all', 'default', and 'minimal'.

The 'minimal' configuration contains almost no service at all and is only used in case someone wants to create its own server and just wants to use the JBoss framework to provide some basic infrastructure.

The 'default' configuration contains the most commonly used J2EE services, such as JSP/Servlet, EJB, JNDI, JXA, and other basic infrastructure services.

The 'all' configuration includes all pre-packaged services that come with JBoss, such as JMS provider, clustering, WebServices, etc.

In this example, we will use the 'all configuration, and hence all configuration changes will apply to the JBOSS_HOME/server/all directory.

Right after installation, JBosst is configured to work on port 8080 for HTTP and 8443 for HTTPS. It also requires port 8009 for an AJP 1.3 port (servlet redirect from Apache HTTP server or MS IIS). If your machine has no other service already running on these ports, you are just fine and can leave everything as is.

In case you do have already other services using one or the other of these ports, it is better to change them. Before you start JBoss the first time, it is better to start a browser and check if there is a response on one of these ports, e.g. http://localhost:8080.

To adjust one or the other of these settings, it is necessary to change the file 'jboss-service.xml' located in the JBOSS_HOME/server/all/deploy/jbossweb-jetty.sar/META-INF directory.

Below is an excerpt of the XML code with the port specifications:

 <!-- =============================================================== -->
       <!-- Configure the Request Listeners                                 -->
       <!-- =============================================================== -->


       <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
       <!-- Add and configure a HTTP listener to port 8080                  -->
       <!-- The default port can be changed using: java -Djetty.port=80     -->
       <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
       <Call name="addListener">
         <Arg>
          <New class="org.mortbay.http.SocketListener">
            <Set name="Port"><SystemProperty 
		name="jetty.port" default="9080"/></Set>
            <Set name="MinThreads">10</Set>
            <Set name="MaxThreads">100</Set>
            <Set name="MaxIdleTimeMs">30000</Set>
            <Set name="LowResourcePersistTimeMs">5000</Set>
          </New>
         </Arg>
       </Call>


       <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
       <!-- Add a HTTPS SSL listener on port 8843                           -->
       <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
       <!-- UNCOMMENT TO ACTIVATE
       <Call name="addListener">
         <Arg>
           <New class="org.mortbay.http.SunJsseListener">
            <Set name="Port">9443</Set>
            <Set name="MinThreads">5</Set>
            <Set name="MaxThreads">100</Set>
            <Set name="MaxIdleTimeMs">30000</Set>
            <Set name="LowResourcePersistTimeMs">2000</Set>
            <Set name="Keystore"><SystemProperty
		name="jboss.server.home.dir"/>/conf/demokeystore</Set>
            <Set name="Password">OBF:1vny1zlo1x8e1vnw1vn61x8g1zlu1vn4</Set>
            <Set name="KeyPassword">OBF:1u2u1wml1z7s1z7a1wnl1u2g</Set>
           </New>
	   </Arg>
	   </Call>
	   -->


       <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
       <!-- Add a AJP13 listener on port 8009                               -->
       <!-- This protocol can be used with mod_jk in apache, IIS etc.       -->
       <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
       <Call name="addListener">
         <Arg>
           <New class="org.mortbay.http.ajp.AJP13Listener">
            <Set name="Port">9009</Set>
            <Set name="MinThreads">5</Set>
            <Set name="MaxThreads">20</Set>
            <Set name="MaxIdleTimeMs">0</Set>
            <Set name="confidentialPort">443</Set>
           </New>
         </Arg>
       </Call>
	

Change the ports in the file (highlighted in bold/italic above) to values that are not likely being used. On Windows, one way to see which ports are being used, open a command prompt windows and enter the command 'netstat -a'. You will get a list of all active ports on this system. (NOTE: on Linux, there is a similar command for this).

If you have to change the ports, it is recommended to change all of the consistently. In my example, I change them to HTTP=9080, HTTPS=9443, AJP13=9009.

This should be enough for the basic configuration of JBoss/Jetty.

Director-specific Configuration

Configuring JBoss for Director is actually a "snap". Below are the few steps necessary:

  1. Copying the RDBMS JDBC drivers to JBoss
    The first task is to locate the libraries for your RDBMS' JDBC drivers. In this example (Oracle 9i) they can be downloaded from Oracle's OTN website (login required but registration is free). After installation, copy the files ojdbc14.jar and nls_charset12.jar to the folder JBOSS_HOME/server/all/lib (this is the place where all libraries go that need to be accessed from all applications running in the 'all' configration).


  2. Configuring the datasource in JBoss
    With JBoss' MBean architecture, it is rather easy to configure and deploy a new datasource.

From the JBOSS_HOME/docs/examples/jca copy the corresponding datasource descriptor for your RDBMS to JBOSS_HOME/server/all/deploy. In case of this example, I used the file oracle-ds.xml. In the 'deploy' folder, rename the file to for example director-ds.xml (IMPORTANT NOTE: in order to correctly discover and deploy the descriptor, the file has to have a name with -ds.xml!). Open the file for editing and change the necessary parameters according to your environment. The descriptor used in this examples environment is shown below:

?xml version="1.0" encoding="UTF-8"?>

<!-- ===================================================================== -->
<!--                                                                       -->
<!--  JBoss Server Configuration                                           -->
<!--                                                                       -->
<!-- ===================================================================== -->

<!-- $Id: oracle-ds.xml,v 1.1.2.2 2003/04/01 04:51:12 d_jencks Exp $ -->
<!-- ==================================================================== -->
<!--  Datasource config for Oracle originally from Steven Coy             -->
<!-- ==================================================================== -->


<datasources>
  <local-tx-datasource>
    <jndi-name>Director</jndi-name>
    <connection-url>jdbc:oracle:thin:@localhost:1521:ORCL</connection-url>
    <driver-class>oracle.jdbc.driver.OracleDriver</driver-class>
    <user-name>JBOSSDIRECTOR</user-name>
    <password>password</password>
    <exception-sorter-class-name>
      org.jboss.resource.adapter.jdbc.vendor.OracleExceptionSorter
    </exception-sorter-class-name>
  </local-tx-datasource>

</datasources>

That's it already - pretty easy, isn't it?

Create & Deploy Your Director Project

Create & Deploy a WAR

Generate your Director WAR

This section assumes that you have a working installation of exteNd Workbench 4.1.1 (XWB) and Director 4.1 Enterprise on your machine (see pre-requisites).

Start your XWB and create a new Director project:


Select the default template and let XWB generate the project. Fill in the following project information:


After next, you might want to select a 'Custom' Type. Proceed with 'Next>' until you reach the 'Directory Information' form and select 'PersistManager' from the drop-down.

(NOTE: you can also select and configure the 'Ldap' realm, but for reason of simplicity, this option has not be selected here)

Click 'Next>' until the Summary dialog and then 'Finish'. Let XWB generate the Director project for you. By accepting all the default settings, you are generating a Director project with all available subsystems.


After this step, you have to create a server profile for JBoss. Go to 'Edit ' Profiles?' create a new profile and name it 'JBoss' (or whatever you feel comfortable). Since XWB4.1.1 does not provide a template for a JBoss server profile, I recommend creating one for the J2EE 1.3 reference implementation. Enter the following information:


Of course, JBOSS_HOME has to be replaced with whatever path you have (e.g. 'C:\Java\jboss-3.2.1').

Configuring the Director WAR to Deploy on JBoss

The first step will be to adjust the default JNDI name of the datasource in the resource-set. For this, open the file config.xml in the WEB-INF/lib/FrameworkService.jar/FrameworkService-conf directory.


Change the entry of 'com.sssw.fw.datasource.jndi-name' to 'java:/Director'.instead of the default value (see screen-shot above). Close the file and save it back.

NOTE: although the JNDI name in your director-ds.xml file has been entered as 'Director', JBoss actually puts all deployed datasources into the 'java:' domain of the JNDI tree. Hence, in this place we have to prepend our JNDI name with 'java:/'.

As a last step, we have to enter a reference to the datasource resource into the deployment descriptor web.xml. Open it in XWB and scroll down to the end of the web.xml.

It should look something like this:


Make a right mouse-click on the entry 'ResourceReferences' and select 'Add' from the popup menu. Right mouse-click on the new entry called 'UntitledResourceReference' and edit the properties as follows:


It seems that sometimes there is a conflict with the WebDAV servlet mapping while deploying to Tomcat. To avoid this, it is recommended to change the default mapping.

Look for the servlet mapping in your web.xml:


Open the properties (right mouse-click),


and change the default URL pattern to '/webdav/*'.

Close the properties window and save your web.xml file and 'Build and Archive (Ctrl+F7)'. Before we actually deploy Director, we want to start JBoss. Open a Windows command prompts and go to the JBOSS_HOME\bin director. Enter the command:

>run -c all

After JBoss successfully started (no exception showing up during boot), we can manually deploy Director by copying the WAR file (JBossExample.war) into the JBOSS_HOME/server/all/deploy directory.

Thanks to JBoss' deployment demon, the WAR file automatically gets deployed and you should see the boot messages of Director in the command prompt window.

CONGRATULATIONS! You successfully installed, configured, and deployed exteNd Director 4.1 Enterprise WAR on JBoss/Jetty 3.2.1.

Here are the URLs to each subsystem: (JBossExample is the context name of this document)

Main Page

http://localhost:9080/JBossExample/main

PMC

http://localhost:9080/JBossExample/main/pages/PmcFolders.html

PAC

http://localhost:9080/JBossExample/main/pages/PacPortalDetails.html

myPortal

http://localhost:9080/JBossExample/main/myportal

Personalize

http://localhost:9080/JBossExample/main/component/PortalPersonalizer

WebDAV

http://localhost:9080/JBossExample/webdav

Create & Deploy an EAR

Generate your Director EAR

This section assumes that you have a working installation of exteNd Workbench 4.1.1 (XWB) and Director 4.1 Enterprise on your machine (see pre-requisites).

Start your XWB and create a new Director project:


Select the default template and let XWB generate the project. Fill in the following project information:


After next, you might want to select a 'Custom' Type. Proceed with 'Next>' until you reach the 'Directory Information' form and select 'PersistManager' from the drop-down.

(NOTE: you can also select and configure the 'Ldap' realm, but for reason of simplicity, this option has not be selected here)

Click 'Next>' until the 'WebDAV Configuration' form. Change the Servlet Path to 'webdav' to avoid any potential conflict.


Click 'Next>' until the Summary dialog and then 'Finish'. Let XWB generate the Director project for you. By accepting all the default settings, you are generating a Director project with all available subsystems.


After this step, you have to create a server profile for JBoss. Go to 'Edit ' Profiles?' create a new profile and name it 'JBoss' (or whatever you feel comfortable). Since XWB4.1.1 does not provide a template for a JBoss server profile, I recommend creating one for the J2EE 1.3 reference implementation. Enter the following information:


Of course, JBOSS_HOME has to be replaced with whatever path you have (e.g. 'C:\Java\jboss-3.2.1').

Configuring the Director EAR to Deploy on JBoss

The first step will be to adjust the default JNDI name of the datasource in the resource-set. For this, open the file config.xml in the library/FrameworkService.jar/FrameworkService-conf directory.


Change the entry of 'com.sssw.fw.datasource.jndi-name' to 'java:/Director'.instead of the default value (see screen-shot above). Close the file and save it back.

NOTE: although the JNDI name in your director-ds.xml file has been entered as 'Director', JBoss actually puts all deployed datasources into the 'java:' domain of the JNDI tree. Hence, in this place we have to prepend our JNDI name with 'java:/'.

As a last step, we have to enter a reference to the datasource resource into the deployment descriptor web.xml files of all WARs contained in our EAR. The web.xml files are in the WEB-INF folder contained in each WAR. Open the web.xml it in XWB and scroll down to the end of the web.xml.

For the example of the Portal.war It should look something like this:


Make a right mouse-click on the entry 'ResourceReferences' and select 'Add' from the popup menu. Right mouse-click on the new entry called 'UntitledResourceReference' and edit the properties as follows:


Repeat this step for each web.xml in each WAR.

NOTE: this might not be actually necessary for all WARs, because not all susbsytems might have to have access to the database, but to keep it simple, I didn't investigate which subsystem actually needs this.

Close the properties window and save all your web.xml files and 'Build and Archive (Ctrl+F7)'. Before we actually deploy Director, we want to start JBoss. Open a Windows command prompt and go to the JBOSS_HOME\bin director. Enter the command:

>run -c all

After JBoss successfully started (no exception showing up during boot), we can manually deploy Director by copying the EAR file (DirectorJBoss.ear) into the JBOSS_HOME/server/all/deploy directory.

Thanks to JBoss' deployment demon, the EAR file automatically gets deployed and you should see the boot messages of Director in the command prompt window

CONGRATULATIONS! You successfully installed, configured, and deployed exteNd Director 4.1 Enterprise EAR on JBoss/Jetty 3.2.1.


Novell Cool Solutions (corporate web communities) are produced by WebWise Solutions. www.webwiseone.com

© 2014 Novell