Embedding Tomcat Into Java Applications
Pages: 1, 2

You should begin your examination of the EmbeddedTomcat application source with the main() method. This method first creates an instance of the EmbeddedTomcat class. It then sets the path of the Tomcat installation that will be hosting our Tomcat instance. This path is equivalent to the <CATALINA_HOME> environment variable. The next action performed by the main() method is to invoke the startTomcat() method. This is the method that implements the container-construction steps described earlier. The steps performed by this method are listed below.

1. The main() method begins by setting the system property to the value of the path attribute:

     // Set the home directory
     System.setProperty("catalina.home", getPath());

   ---

   Note:

   Make sure you use the value of <CATALINA_HOME> as the directory value passed to the setPath() method.

   ---

2. The next step performed by this method is to create an instance of the Embedded object and set the debug level and current logger.

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

   ---

   Note:

   The debug level should be 0, when deploying a production Web application. Setting the debug level to 0 reduces the amount of logging performed by Tomcat, which will improve performance significantly.

   ---

3. After the application has an instance of the Embedded object, it creates an instance of an org.apache.catalina.Engine and sets the name of the default host. The Engine object represents the entire Catalina servlet container.

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

4. After an Engine has been instantiated, we create an org.apache.catalina.Host object, named localhost, with a path pointing to the <CATALINA_HOME>/webapps/ directory, and add it the Engine object. The Host object defines the virtual hosts that are contained in each instance of a Catalina Engine.

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

5. The next step performed by the startTomcat() method is to create an org.apache.catalina.Context object, which represents the ROOT Web application packaged with Tomcat, and add it the to the previously created Host. The ROOT Web application is the only application that will be installed by default.

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

6. The next step adds the Engine containing the created Host and Context to the Embedded object.

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

7. After the engine is added to the Embedded object, the startTomcat() method creates an org.apache.catalina.Connector object and associates it with the previously created Engine. The <Connector> element defines the class that does the actual handling of requests and responses to and from a calling client application. In the following snippet, an HTTP connector that listens to port 8080 is created and added to the Embedded object.

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

8. The final step performed by the startTomcat() method starts the Tomcat container.

     embedded.start();

When startTomcat() returns, the main method calls the registerWAR() method, which installs the previously deployed onjava application to the Embedded object. The URL used in this example can point to any Webapp directory that follows the specification for Java Servlet 2.2 and later.

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

The main application is then put to sleep to allow the embedded server time to service requests. When the application awakes, the embedded server is stopped and the application exits.

To test this application, you must complete the following steps:

1. Compile the EmbeddedTomcat.java class.
2. Make sure all other instances of Tomcat are shut down.
3. Add the following jar files, all of which can be found in the Tomcat installation, to your application classpath.
   • <CATALINA_HOME>/bin/bootstrap.jar
   • <CATALINA_HOME>/server/lib/catalina.jar
   • <CATALINA_HOME>/server/lib/servlet-cgi.jar
   • <CATALINA_HOME>/server/lib/servlets-common.jar
   • <CATALINA_HOME>/server/lib/servlets-default.jar
   • <CATALINA_HOME>/server/lib/servlets-invoker.jar
   • <CATALINA_HOME>/server/lib/servlets-manager.jar
   • <CATALINA_HOME>/server/lib/servlets-snoop.jar
   • <CATALINA_HOME>/server/lib/servlets-ssi.jar
   • <CATALINA_HOME>/server/lib/servlets-webdav.jar
   • <CATALINA_HOME>/server/lib/jakarta-regexp-1.2.jar
   • <CATALINA_HOME>/lib/naming-factory.jar
   • <CATALINA_HOME>/common/lib/crimson.jar
   • <CATALINA_HOME>/common/lib/jasper-compiler.jar
   • <CATALINA_HOME>/common/lib/jasper-runtime.jar
   • <CATALINA_HOME>/common/lib/jaxp.jar
   • <CATALINA_HOME>/common/lib/jndi.jar
   • <CATALINA_HOME>/common/lib/naming-common.jar
   • <CATALINA_HOME>/common/lib/naming-resources.jar
   • <CATALINA_HOME>/common/lib/servlet.jar
   • <CATALINA_HOME>/common/lib/tools.jar
4. Make sure that your classpath includes the directory containing the compiled EmbeddedTomcat class.
5. Execute the following command:

  java onjava.EmbeddedTomcat

If everything went according to plan, you should see some log statements in the console window:

  HttpProcessor[8080][0] Starting background thread
  HttpProcessor[8080][0]  Background thread has been started
  HttpProcessor[8080][1] Starting background thread
  HttpProcessor[8080][1]  Background thread has been started
  HttpProcessor[8080][2] Starting background thread
  HttpProcessor[8080][2]  Background thread has been started
  HttpProcessor[8080][3] Starting background thread
  HttpProcessor[8080][3]  Background thread has been started
  HttpProcessor[8080][4] Starting background thread
  HttpProcessor[8080][4]  Background thread has been started

Once you see the previous text, you will be able to access the ROOT and /onjava Web applications using the following URLs:

• http://localhost:8080/
• http://localhost:8080/onjava/

---

Note: The onjava application that we are using throughout this article is the Web application from my previous Tomcat articles.

---

Up next: in the next Tomcat article, we will continue our embedded discussions by debugging a Web application that is running in our embedded container.

James Goodwill is the co-Founder of Virtuas Solutions, LLC, a Colorado-based software consultancy.

---

Return to ONJava.com.