Running JAXM on Tomcat 

JAXM, this document gives instructions for downloading and unpacking Tomcat 3.2.3 and Tomcat 4.0.3

This web page contains the following:

NOTE: The following conventions are used in this document.


In order to use JAXM from a servlet engine such as Tomcat, the servlet engine must be able to load the JAXM libraries and also the libraries JAXM depends on. These libraries are loadable if they are present in the appropriate servlet engine directory or if they are on the classpath of the servlet engine. The libraries that JAXM depends on are in <JAXM-HOME>/lib. The JAR files for the JAXM infrastructure itself are in <JAXM-HOME>>/jaxm. Only those libraries that are not present in the servlet engine need to be added to the servlet engine's CLASSPATH. If you copy the files as described in the following directions, you will not need to add anything to the servlet engine's CLASSPATH.

Setting up Tomcat 4

Here is what you need to do to get the JAXM provider and the samples running on Tomcat 4:
 
  1. Copy all the .jar files from <JAXM-HOME>/lib into <TOMCAT-HOME>/common/lib

  2. For example,
        cd <JAXM-HOME>/lib
        cp *.jar <TOMCAT-HOME>/common/lib
    
  3. Copy the all of the .war files from <JAXM-HOME>/samples into <TOMCAT-HOME>/webapps

  4. For example,
        cd <JAXM-HOME>/samples
        cp *.war <TOMCAT-HOME>/webapps
    
  5. Copy the jaxm-runtime.jar and saaj-ri.jar files from <JAXM-HOME>/jaxm into <TOMCAT-HOME>/common/lib

  6. For example,
        cd <JAXM-HOME>/jaxm
        cp jaxm-runtime.jar <TOMCAT-HOME>/common/lib
        cd <JAXM-HOME>/jaxm
        cp saaj-ri.jar <TOMCAT-HOME>/common/lib
    

    Note: If you have used JAXM-1.0, you must delete client.jar from TOMCAT_HOME/common/lib, as the filename for this library has changed in the current release to jaxm-runtime.jar.

    Note: If you have used JAXM-1.0.1-ea(2), you must delete jaxm-client.jar from TOMCAT_HOME/common/lib, as the filename for this library has changed in the current release to jaxm-runtime.jar.

  7. Copy <JAXM-HOME>/jaxm/jaxm-provider.war into <TOMCAT-HOME>/webapps

  8. For example,
        cd <JAXM-HOME>/jaxm
        cp jaxm-provider.war <TOMCAT-HOME>/webapps
    
  9. If you have not already done so, set the environment variables CATALINA_HOME and JAVA_HOME. You will find instructions for setting environment variables in the top level Release Notes for this release.

Starting Tomcat

  1. Type the following at the command line, making the proper substitution for <TOMCAT-HOME>:
        Windows:  <TOMCAT-HOME>\bin\startup
        Unix:  <TOMCAT-HOME>/bin/startup.sh
    
  2. Start your browser and set it to
    	http://localhost:8080/index.html
    
    If Tomcat is running, the Tomcat documentation home page will come up.


Downloading Tomcat 3.2.3

Here are the steps for downloading Tomcat version 3.2.3:
  1. Go to the following web site:
        http://jakarta.apache.org/builds/jakarta-tomcat/release/v3.2.3/bin/
    
  2. Click on jakarta-tomcat-3.2.3.zip and use the window that appears to indicate where you want the download to go.

  3. Go to the directory where you downloaded jakarta-tomcat-3.2.3.zip. At the command line type the following:
        unzip jakarta-tomcat-3.2.3.zip
    
    This will create the directory jakarta-tomcat-3.2.3 containing all the unzipped files. You can delete the zip file once you have unzipped it.

Setting Up Tomcat 3.2.3

  1. Copy all the .jar files from <JAXM-HOME>/lib into <TOMCAT-HOME>/lib

  2. For example:
        cd <JAXM-HOME>/lib
        cp *.jar <TOMCAT-HOME>/lib
    
  3. Copy the jaxm-runtime.jar and saaj-ri.jar files from <JAXM-HOME>/jaxm into <TOMCAT-HOME>/lib

  4. For example:
        cd <JAXM-HOME>/jaxm
        cp jaxm-runtime.jar <TOMCAT-HOME>/lib
        cd <JAXM-HOME>/jaxm
        cp saaj-ri.jar <TOMCAT-HOME>/lib
    

    Note: If you have used JAXM-1.0, you must delete client.jar from TOMCAT_HOME/lib, as the filename for this library has changed in the current release to jaxm-runtime.jar.

    Note: If you have used JAXM-1.0.1-ea(2), you must delete jaxm-client.jar from TOMCAT_HOME/common/lib, as the filename for this library has changed in the current release to jaxm-runtime.jar.

  5. Copy the .war files from <JAXM-HOME>/samples into <TOMCAT-HOME>/webapps

  6. For example:
        cd <JAXM-HOME>/samples
        cp *.war <TOMCAT-HOME>/webapps
    
  7. Edit <TOMCAT-HOME>/conf/server.xml. Add the following XML element anywhere in the file. The order does not matter because this file does not have a DTD, but be sure not to insert it inside another element.
        <RequestInterceptor 
    		 className="org.apache.tomcat.request.Jdk12Interceptor"/>
    
  8. Copy <JAXM-HOME>/jaxm/jaxm-provider.war into <TOMCAT-HOME>/webapps
  9. For example:
        cd <JAXM-HOME>/jaxm
        cp jaxm-provider.war <TOMCAT-HOME>/webapps
    
  10. Set the Environment Variable TOMCAT_HOME.
    TOMCAT_HOME is the full pathname for the directory jakarta-tomcat-3.2.3.
    For example,
        Windows:  set TOMCAT_HOME=C:\happy\jaxm\jakarta-tomcat-3.2.3
        Unix:  setenv TOMCAT_HOME /home/happy/jaxm/jakarta-tomcat-3.2.3
    

  11. If you have not already done so, set the environment variable JAVA_HOME.
    You will find instructions for setting environment variables in the
    top level Release Notes file.

Starting Tomcat 3.2.3

Note that these instructions are identical to those for starting Tomcat 4.
  1. Type the following at the command line, making the proper substitution for TOMCAT_HOME:
        Windows:  <TOMCAT_HOME>\bin\startup
        Unix:  <TOMCAT_HOME>/bin/startup.sh
    
  2. Start your browser and set it to
    	http://localhost:8080/index.html
    
    If Tomcat is running, the Tomcat documentation home page will come up.

Getting the Provider Admin Tool Running

The JAXM RI provides a tool called Provider Admin that lets you set or change properties for the messaging provider implementation that is part of the RI. You can get the Provider Admin tool running on Tomcat by doing the following:
  1. Copy the jaxm-provideradmin.war file from <JAXM-HOME>/tools into <TOMCAT-HOME>/webapps

  2. Point your browser to
        http://localhost:8080/jaxm-provideradmin
    
  3. Set the provider role in the conf/tomcat-users.xml and also add the user name / password for the role specified above.
  4. Use the user name and password created above to login to use the provider admin
When the Provider Admin tool comes up, follow the instructions it provides.