org.apache.catalina.startup
Class Tomcat

java.lang.Object
  extended by org.apache.catalina.startup.Tomcat

public class Tomcat
extends java.lang.Object

Minimal tomcat starter for embedding/unit tests. Tomcat supports multiple styles of configuration and startup - the most common and stable is server.xml-based, implemented in org.apache.catalina.startup.Bootstrap. This class is for use in apps that embed tomcat. Requirements: - all tomcat classes and possibly servlets are in the classpath. ( for example all is in one big jar, or in eclipse CP, or in any other combination ) - we need one temporary directory for work files - no config file is required. This class provides methods to use if you have a webapp with a web.xml file, but it is optional - you can use your own servlets. This class provides a main() and few simple CLI arguments, see setters for doc. It can be used for simple tests and demo.

Author:
Costin Manolache
See Also:
for examples on how to use this

Nested Class Summary
static class Tomcat.DefaultWebXmlListener
          Fix reload - required if reloading and using programmatic configuration.
static class Tomcat.ExistingStandardWrapper
          Helper class for wrapping existing servlets.
static class Tomcat.FixContextListener
          Fix startup sequence - required if you don't use web.xml.
 
Field Summary
protected  java.lang.String basedir
           
protected  Connector connector
           
static java.lang.String[] DEFAULT_MIME_MAPPINGS
          TODO: would a properties resource be better ?
protected  Realm defaultRealm
           
protected  StandardEngine engine
           
protected  StandardHost host
           
protected  java.lang.String hostname
           
protected  int port
           
protected  StandardServer server
           
protected  StandardService service
           
 
Constructor Summary
Tomcat()
           
 
Method Summary
 StandardContext addContext(StandardHost host, java.lang.String contextPath, java.lang.String dir)
           
 StandardContext addContext(java.lang.String contextPath, java.lang.String baseDir)
          Add a context - programmatic mode, no web.xml used.
 void addRole(java.lang.String user, java.lang.String role)
           
static StandardWrapper addServlet(StandardContext ctx, java.lang.String servletName, javax.servlet.Servlet servlet)
          Use an existing servlet, no class.forName or initialization will be performed
static StandardWrapper addServlet(StandardContext ctx, java.lang.String servletName, java.lang.String servletClass)
          Equivalent with .
 StandardWrapper addServlet(java.lang.String contextPath, java.lang.String servletName, java.lang.String servletClass)
           
 void addUser(java.lang.String user, java.lang.String pass)
          Add a user for the in-memory realm.
 StandardContext addWebapp(StandardHost host, java.lang.String url, java.lang.String path)
           
 StandardContext addWebapp(java.lang.String contextPath, java.lang.String baseDir)
          Add a webapp using normal WEB-INF/web.xml if found.
 Connector getConnector()
          Get the default http connector.
 StandardEngine getEngine()
          Access to the engine, for further customization.
 StandardHost getHost()
           
 StandardServer getServer()
          Get the server object.
 StandardService getService()
          Get the service object.
protected  void initBaseDir()
           
protected  void initSimpleAuth()
          Initialize an in-memory realm.
static void initWebappDefaults(StandardContext ctx)
          Provide default configuration for a context.
 void setBaseDir(java.lang.String basedir)
          Tomcat needs a directory for temp files.
 void setConnector(Connector connector)
           
 void setDefaultRealm(Realm realm)
          Set a custom realm for auth.
 void setHost(StandardHost host)
          Sets the current host - all future webapps will be added to this host.
 void setHostname(java.lang.String s)
          The the hostname of the default host, default is 'localhost'.
 void setPort(int port)
          Set the port for the default connector.
 void setSilent()
          Sets the log level to WARN for the loggers that log information on Tomcat start up.
 void start()
          Initialize and start the server.
 void stop()
          Stop the server.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

server

protected StandardServer server

service

protected StandardService service

engine

protected StandardEngine engine

connector

protected Connector connector

host

protected StandardHost host

port

protected int port

hostname

protected java.lang.String hostname

basedir

protected java.lang.String basedir

defaultRealm

protected Realm defaultRealm

DEFAULT_MIME_MAPPINGS

public static final java.lang.String[] DEFAULT_MIME_MAPPINGS
TODO: would a properties resource be better ? Or just parsing /etc/mime.types ? This is needed because we don't use the default web.xml, where this is encoded.

Constructor Detail

Tomcat

public Tomcat()
Method Detail

setBaseDir

public void setBaseDir(java.lang.String basedir)
Tomcat needs a directory for temp files. This should be the first method called. By default, if this method is not called, we use: - system properties - catalina.base, catalina.home - $HOME/tomcat.$PORT ( /tmp doesn't seem a good choice for security ). TODO: better default ? Maybe current dir ? TODO: disable work dir if not needed ( no jsp, etc ).


setPort

public void setPort(int port)
Set the port for the default connector. Must be called before start().


setHostname

public void setHostname(java.lang.String s)
The the hostname of the default host, default is 'localhost'.


addWebapp

public StandardContext addWebapp(java.lang.String contextPath,
                                 java.lang.String baseDir)
                          throws javax.servlet.ServletException
Add a webapp using normal WEB-INF/web.xml if found.

Parameters:
contextPath -
baseDir -
Returns:
Throws:
javax.servlet.ServletException

addContext

public StandardContext addContext(java.lang.String contextPath,
                                  java.lang.String baseDir)
Add a context - programmatic mode, no web.xml used. API calls equivalent with web.xml: context-param ctx.addParameter("name", "value"); error-page ErrorPage ep = new ErrorPage(); ep.setErrorCode(500); ep.setLocation("/error.html"); ctx.addErrorPage(ep); ctx.addMimeMapping("ext", "type"); Note: If you reload the Context, all your configuration will be lost. If you need reload support, consider using a LifecycleListener to provide your configuration. TODO: add the rest

Parameters:
host - NULL for the 'default' host
contextPath - "/" for root context.
dir - base dir for the context, for static files. Must exist, relative to the server home

addServlet

public StandardWrapper addServlet(java.lang.String contextPath,
                                  java.lang.String servletName,
                                  java.lang.String servletClass)

addServlet

public static StandardWrapper addServlet(StandardContext ctx,
                                         java.lang.String servletName,
                                         java.lang.String servletClass)
Equivalent with . In general it is better/faster to use the method that takes a Servlet as param - this one can be used if the servlet is not commonly used, and want to avoid loading all deps. ( for example: jsp servlet ) You can customize the returned servlet, ex: wrapper.addInitParameter("name", "value");


addServlet

public static StandardWrapper addServlet(StandardContext ctx,
                                         java.lang.String servletName,
                                         javax.servlet.Servlet servlet)
Use an existing servlet, no class.forName or initialization will be performed


start

public void start()
           throws java.lang.Exception
Initialize and start the server.

Throws:
java.lang.Exception

stop

public void stop()
          throws java.lang.Exception
Stop the server.

Throws:
java.lang.Exception

addUser

public void addUser(java.lang.String user,
                    java.lang.String pass)
Add a user for the in-memory realm. All created apps use this by default, can be replaced using setRealm().


addRole

public void addRole(java.lang.String user,
                    java.lang.String role)
See Also:
addUser

getConnector

public Connector getConnector()
                       throws java.lang.Exception
Get the default http connector. You can set more parameters - the port is already initialized. Alternatively, you can construct a Connector and set any params, then call addConnector(Connector)

Returns:
A connector object that can be customized
Throws:
java.lang.Exception

setConnector

public void setConnector(Connector connector)

getService

public StandardService getService()
Get the service object. Can be used to add more connectors and few other global settings.


setHost

public void setHost(StandardHost host)
Sets the current host - all future webapps will be added to this host. When tomcat starts, the host will be the default host.

Parameters:
host -

getHost

public StandardHost getHost()

setDefaultRealm

public void setDefaultRealm(Realm realm)
Set a custom realm for auth. If not called, a simple default will be used, using an internal map. Must be called before adding a context.


getEngine

public StandardEngine getEngine()
Access to the engine, for further customization.


getServer

public StandardServer getServer()
Get the server object. You can add listeners and few more customizations.


addContext

public StandardContext addContext(StandardHost host,
                                  java.lang.String contextPath,
                                  java.lang.String dir)

addWebapp

public StandardContext addWebapp(StandardHost host,
                                 java.lang.String url,
                                 java.lang.String path)
                          throws javax.servlet.ServletException
Throws:
javax.servlet.ServletException

initSimpleAuth

protected void initSimpleAuth()
Initialize an in-memory realm. You can replace it for contexts with a real one.


initBaseDir

protected void initBaseDir()

setSilent

public void setSilent()
Sets the log level to WARN for the loggers that log information on Tomcat start up. This prevents the usual startup information being logged to the console.


initWebappDefaults

public static void initWebappDefaults(StandardContext ctx)
Provide default configuration for a context. This is the programmatic equivalent of the default web.xml. TODO: in normal tomcat, if default-web.xml is not found, use this method



Copyright © 2000-2009 Apache Software Foundation. All Rights Reserved.