Embedding Tomcat Into Java Applications

04/03/2002

In this article, we'll extend our Tomcat discussions to the application level by creating a Java application that manages an embedded version of the Tomcat JSP/servlet container. Tomcat can be broken down into a set of containers, each with their own purpose. These containers are by default configured using the server.xml file. When embedding, you will not be using this file; therefore, you will need to assemble instances of these containers programmatically. The following XML code snippet contains the hierarchy of the Tomcat containers:

<Server>
  <Service>
    <Connector />
    <Engine>
      <Host>
        <Context />
      </Host>
    </Engine>
  </Service>
</Server>

---

Note: Each of the previously listed elements contains attributes to set their appropriate behaviors, but for our purposes, only the element hierarchies and relationships are important.

---

This is the structure that we need to create with our embedded application. The <Server> and <Service> elements of this structure are going to be implicitly created, therefore we do not have to create these objects ourselves. The steps to create the remainder of the container structure are listed below.

These are the same steps that we must perform in order to create our own embedded version of the Tomcat container:

1. Create an instance of an org.apache.catalina.Engine; this object represents the <Engine> element above and acts as a container to the <Host> element.
2. Create an org.apache.catalina.Host object, which represents a virtual host, and add this instance to the Engine object.
3. Now you need to create n-number of org.apache.catalina.Context objects that will represent each Web application in this Host.
4. Once each of your Contexts are created, you then need to add each of the created Contexts to the previously created Host. For our example, we'll create a single Context that will represent our onjava application.
5. The final step is to create an org.apache.catalina.Connector object and associate it with the previously created Engine. The Connector object is the object that actually receives a request from the calling client.

To create this application, we'll leverage some existing Tomcat classes that have been developed to ease this type of integration. The main class we will use is the org.apache.catalina.startup.Embedded class, which can be found in the <CATALINA_HOME>/src/catalina/src/share/org/apache/catalina/startup directory. The following source listing contains our sample application that builds these containers using the org.apache.catalina.startup.Embedded class.

package onjava;

import java.net.URL;
import org.apache.catalina.Connector;
import org.apache.catalina.Context;
import org.apache.catalina.Deployer;
import org.apache.catalina.Engine;
import org.apache.catalina.Host;
import org.apache.catalina.logger.SystemOutLogger;
import org.apache.catalina.startup.Embedded;
import org.apache.catalina.Container;

public class EmbeddedTomcat {

  private String path = null;
  private Embedded embedded = null;
  private Host host = null;
  /**
    * Default Constructor
    *
    */
  public EmbeddedTomcat() {

  }

  /**
    * Basic Accessor setting the value of the context path
    *
    * @param path - the path
    */
  public void setPath(String path) {

    this.path = path;
  }

  /**
    * Basic Accessor returning the value of the context path
    *
    * @return - the context path
    */
  public String getPath() {

    return path;
  }

  /**
    * This method Starts the Tomcat server.
    */
  public void startTomcat() throws Exception {

    Engine engine = null;
    // Set the home directory
    System.setProperty("catalina.home", getPath());

    // Create an embedded server
    embedded = new Embedded();
    // print all log statments to standard error
    embedded.setDebug(0);
    embedded.setLogger(new SystemOutLogger());

    // Create an engine
    engine = embedded.createEngine();
    engine.setDefaultHost("localhost");

    // Create a default virtual host
    host = embedded.createHost("localhost", getPath()
      + "/webapps");
    engine.addChild(host);

    // Create the ROOT context
    Context context = embedded.createContext("",
      getPath() + "/webapps/ROOT");
    host.addChild(context);

    // Install the assembled container hierarchy
    embedded.addEngine(engine);

    // Assemble and install a default HTTP connector
    Connector connector =
      embedded.createConnector(null, 8080, false);
    embedded.addConnector(connector);
    // Start the embedded server
    embedded.start();
  }

  /**
    * This method Stops the Tomcat server.
    */
  public void stopTomcat() throws Exception {
    // Stop the embedded server
    embedded.stop();
  }

  /**
    * Registers a WAR with the container.
    *
    * @param contextPath - the context path under which the
    *               application will be registered
    * @param warFile - the URL of the WAR to be
    * registered.
    */
  public void registerWAR(String contextPath, URL warFile)
    throws Exception {

    if ( contextPath == null ) {

      throw new Exception("Invalid Path : " + contextPath);
    }
    if( contextPath.equals("/") ) {

      contextPath = "";
    }
    if ( warFile == null ) {

      throw new Exception("Invalid WAR : " + warFile);
    }

    Deployer deployer = (Deployer)host;
    Context context = deployer.findDeployedApp(contextPath);

    if (context != null) {

      throw new
        Exception("Context " + contextPath
        + " Already Exists!");
    }
    deployer.install(contextPath, warFile);
  }

  /**
    * Unregisters a WAR from the web server.
    *
    * @param contextPath - the context path to be removed
    */
  public void unregisterWAR(String contextPath)
    throws   Exception {

    Context context = host.map(contextPath);
    if ( context != null ) {

      embedded.removeContext(context);
    }
    else {

      throw new
        Exception("Context does not exist for named path : 
        + contextPath);
    }
  }

  public static void main(String args[]) {

    try {

      EmbeddedTomcat tomcat = new EmbeddedTomcat();
      tomcat.setPath("d:/jakarta-tomcat-4.0.1");
      tomcat.startTomcat();

      URL url =
        new URL("file:D:/jakarta-tomcat-4.0.1"
        + "/webapps/onjava");
      tomcat.registerWAR("/onjava", url);

      Thread.sleep(1000000);

      tomcat.stopTomcat();

      System.exit(0);
    }
    catch( Exception e ) {

      e.printStackTrace();
    }
  }
}

Pages: 1, 2

Next Page