Tomcat (Apache Tomcat 7.0.109 API Documentation)

java.lang.Object
- org.apache.catalina.startup.Tomcat

```
public class Tomcat
extends 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.
There are a variety of 'add' methods to configure servlets and webapps. These methods, by default, create a simple in-memory security realm and apply it. If you need more complex security processing, you can define a subclass of this class.
This class provides a set of convenience methods for configuring web application contexts; all overloads of the method addWebapp(). These methods are equivalent to adding a web application to the Host's appBase (normally the webapps directory). These methods create a Context, configure it with the equivalent of the defaults provided by conf/web.xml (see initWebappDefaults(String) for details) and add the Context to a Host. These methods do not use a global default web.xml; rather, they add a LifecycleListener to configure the defaults. Any WEB-INF/web.xml and META-INF/context.xml packaged with the application will be processed normally. Normal web fragment and ServletContainerInitializer processing will be applied.
In complex cases, you may prefer to use the ordinary Tomcat API to create webapp contexts; for example, you might need to install a custom Loader before the call to Container.addChild(Container). To replicate the basic behavior of the addWebapp methods, you may want to call two methods of this class: noDefaultWebXmlPath() and getDefaultWebXmlListener().
getDefaultRealm() returns the simple security realm.
getDefaultWebXmlListener() returns a LifecycleListener that adds the standard DefaultServlet, JSP processing, and welcome files. If you add this listener, you must prevent Tomcat from applying any standard global web.xml with ...
noDefaultWebXmlPath() returns a dummy pathname to configure to prevent ContextConfig from trying to apply a global web.xml file.
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:
TestTomcat

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`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

Fields
Modifier and Type	Field and Description
`protected String`	`basedir`
`protected Connector`	`connector`
`protected Realm`	`defaultRealm` Deprecated.
`protected Engine`	`engine`
`protected Host`	`host`
`protected String`	`hostname`
`protected int`	`port`
`protected Server`	`server`
`protected Service`	`service`

Constructor Summary

Constructors
Constructor and Description

Tomcat()

Constructors
Constructor and Description
`Tomcat()`

Method Summary

Methods
Modifier and Type	Method and Description
`Context`	`addContext(Host host, String contextPath, String dir)`
`Context`	`addContext(Host host, String contextPath, String contextName, String dir)`
`Context`	`addContext(String contextPath, String docBase)` Add a context - programmatic mode, no default web.xml used.
`static void`	`addDefaultMimeTypeMappings(Context context)` Add the default MIME type mappings to the provide Context.
`void`	`addRole(String user, String role)` Add a role to a user.
`static Wrapper`	`addServlet(Context ctx, String servletName, Servlet servlet)` Static version of `addServlet(String, String, Servlet)`.
`static Wrapper`	`addServlet(Context ctx, String servletName, String servletClass)` Static version of `addServlet(String, String, String)`
`Wrapper`	`addServlet(String contextPath, String servletName, Servlet servlet)` Add an existing Servlet to the context with no class.forName or initialisation.
`Wrapper`	`addServlet(String contextPath, String servletName, String servletClass)` Equivalent to <servlet><servlet-name><servlet-class>.
`void`	`addUser(String user, String pass)` Add a user for the in-memory realm.
`Context`	`addWebapp(Host host, String contextPath, String docBase)` This is equivalent to adding a web application to a Host's appBase (usually Tomcat's webapps directory).
`Context`	`addWebapp(Host host, String contextPath, String docBase, LifecycleListener config)` This is equivalent to adding a web application to a Host's appBase (usually Tomcat's webapps directory).
`Context`	`addWebapp(Host host, String contextPath, String name, String docBase)` Deprecated. Use `addWebapp(Host, String, String)`
`Context`	`addWebapp(String contextPath, String docBase)` This is equivalent to adding a web application to a Host's appBase (usually Tomcat's webapps directory).
`Context`	`addWebapp(String contextPath, URL source)` Copy the specified WAR file to the Host's appBase and then call `addWebapp(String, String)` with the newly copied WAR.
`void`	`destroy()` Destroy the server.
`void`	`enableNaming()` Enables JNDI naming which is disabled by default.
`Connector`	`getConnector()` Get the default http connector.
`Realm`	`getDefaultRealm()` Deprecated. Will be removed in Tomcat 8.0.x
`LifecycleListener`	`getDefaultWebXmlListener()` Return a listener that provides the required configuration items for JSP processing.
`Engine`	`getEngine()` Access to the engine, for further customization.
`Host`	`getHost()`
`Server`	`getServer()` Get the server object.
`Service`	`getService()` Get the service object.
`protected URL`	`getWebappConfigFile(String path, String contextName)`
`void`	`init()` Initialize the server.
`protected void`	`initBaseDir()`
`protected void`	`initSimpleAuth()` Deprecated. Will be removed in Tomcat 8.0.x
`static void`	`initWebappDefaults(Context ctx)` Static version of `initWebappDefaults(String)`.
`void`	`initWebappDefaults(String contextPath)` Provide default configuration for a context.
`String`	`noDefaultWebXmlPath()`
`void`	`setAddDefaultWebXmlToWebapp(boolean addDefaultWebXmlToWebapp)` By default, when calling addWebapp() to create a Context, the settings from from the default web.xml are added to the context.
`void`	`setBaseDir(String basedir)` Tomcat needs a directory for temp files.
`void`	`setConnector(Connector connector)`
`void`	`setDefaultRealm(Realm realm)` Deprecated. Will be removed in Tomcat 8.0.x.
`void`	`setHost(Host host)` Sets the current host - all future webapps will be added to this host.
`void`	`setHostname(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(boolean silent)` Controls if the loggers will be silenced or not.
`void`	`start()` 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 Server server
```
  - service
```
protected Service service
```
  - engine
```
protected Engine engine
```
  - connector
```
protected Connector connector
```
  - host
```
protected Host host
```
  - port
```
protected int port
```
  - hostname
```
protected String hostname
```
  - basedir
```
protected String basedir
```
  - defaultRealm
```
@Deprecated
protected Realm defaultRealm
```
    Deprecated.
- Constructor Detail
  - Tomcat
```
public Tomcat()
```
- Method Detail
  - setBaseDir
```
public void setBaseDir(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
    - $PWD/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().
    
    Parameters:
    port - The port number
  - setHostname
```
public void setHostname(String s)
```
    The the hostname of the default host, default is 'localhost'.
    
    Parameters:
    s - The default host name
  - addWebapp
```
public Context addWebapp(String contextPath,
                String docBase)
```
    This is equivalent to adding a web application to a Host's appBase (usually Tomcat's webapps directory). By default, the equivalent of the default web.xml will be applied to the web application (see initWebappDefaults(String)). This may be prevented by calling setAddDefaultWebXmlToWebapp(boolean) with false. Any WEB-INF/web.xml and META-INF/context.xml packaged with the application will always be processed and normal web fragment and ServletContainerInitializer processing will always be applied.
    
    Parameters:
    contextPath - The context mapping to use, "" for root context.
    docBase - Base directory for the context, for static files. Must exist, relative to the server home
    
    Returns:
    the deployed context
  - addWebapp
```
public Context addWebapp(String contextPath,
                URL source)
                  throws IOException
```
    Copy the specified WAR file to the Host's appBase and then call addWebapp(String, String) with the newly copied WAR. The WAR will NOT be removed from the Host's appBase when the Tomcat instance stops. Note that ExpandWar provides utility methods that may be used to delete the WAR and/or expanded directory if required.
    
    Parameters:
    contextPath - The context mapping to use, "" for root context.
    source - The location from which the WAR should be copied
    
    Returns:
    The deployed Context
    
    Throws:
    
    IOException - If an I/O error occurs while copying the WAR file from the specified URL to the appBase
  - addContext
```
public Context addContext(String contextPath,
                 String docBase)
```
    Add a context - programmatic mode, no default 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:
    contextPath - The context mapping to use, "" for root context.
    docBase - Base directory for the context, for static files. Must exist, relative to the server home
    
    Returns:
    the deployed context
  - addServlet
```
public Wrapper addServlet(String contextPath,
                 String servletName,
                 String servletClass)
```
    Equivalent to <servlet><servlet-name><servlet-class>.
    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");
  
```
    Parameters:
    contextPath - Context to add Servlet to
    servletName - Servlet name (used in mappings)
    servletClass - The class to be used for the Servlet
    
    Returns:
    The wrapper for the servlet
  - addServlet
```
public static Wrapper addServlet(Context ctx,
                 String servletName,
                 String servletClass)
```
    Static version of addServlet(String, String, String)
    
    Parameters:
    ctx - Context to add Servlet to
    servletName - Servlet name (used in mappings)
    servletClass - The class to be used for the Servlet
    
    Returns:
    The wrapper for the servlet
  - addServlet
```
public Wrapper addServlet(String contextPath,
                 String servletName,
                 Servlet servlet)
```
    Add an existing Servlet to the context with no class.forName or initialisation.
    
    Parameters:
    contextPath - Context to add Servlet to
    servletName - Servlet name (used in mappings)
    servlet - The Servlet to add
    
    Returns:
    The wrapper for the servlet
  - addServlet
```
public static Wrapper addServlet(Context ctx,
                 String servletName,
                 Servlet servlet)
```
    Static version of addServlet(String, String, Servlet).
    
    Parameters:
    ctx - Context to add Servlet to
    servletName - Servlet name (used in mappings)
    servlet - The Servlet to add
    
    Returns:
    The wrapper for the servlet
  - init
```
public void init()
          throws LifecycleException
```
    Initialize the server.
    
    Throws:
    
    LifecycleException - Init error
  - start
```
public void start()
           throws LifecycleException
```
    Start the server.
    
    Throws:
    
    LifecycleException - Start error
  - stop
```
public void stop()
          throws LifecycleException
```
    Stop the server.
    
    Throws:
    
    LifecycleException - Stop error
  - destroy
```
public void destroy()
             throws LifecycleException
```
    Destroy the server. This object cannot be used once this method has been called.
    
    Throws:
    
    LifecycleException - Destroy error
  - addUser
```
public void addUser(String user,
           String pass)
```
    Add a user for the in-memory realm. All created apps use this by default, can be replaced using setRealm().
    
    Parameters:
    user - The user name
    pass - The password
  - addRole
```
public void addRole(String user,
           String role)
```
    Add a role to a user.
    
    Parameters:
    user - The user name
    role - The role name
    See Also:
    addUser(String, String)
  - getConnector
```
public Connector getConnector()
```
    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
  - setConnector
```
public void setConnector(Connector connector)
```
  - getService
```
public Service getService()
```
    Get the service object. Can be used to add more connectors and few other global settings.
    
    Returns:
    The service
  - setHost
```
public void setHost(Host 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 - The current host
  - getHost
```
public Host getHost()
```
  - setDefaultRealm
```
@Deprecated
public void setDefaultRealm(Realm realm)
```
    Deprecated. Will be removed in Tomcat 8.0.x.
    
    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 Engine getEngine()
```
    Access to the engine, for further customization.
    
    Returns:
    The engine
  - getServer
```
public Server getServer()
```
    Get the server object. You can add listeners and few more customizations. JNDI is disabled by default.
    
    Returns:
    The Server
  - addContext
```
public Context addContext(Host host,
                 String contextPath,
                 String dir)
```
    Parameters:
    host - The host in which the context will be deployed
    contextPath - The context mapping to use, "" for root context.
    dir - Base directory for the context, for static files. Must exist, relative to the server home
    
    Returns:
    the deployed context
    See Also:
    addContext(String, String)
  - addContext
```
public Context addContext(Host host,
                 String contextPath,
                 String contextName,
                 String dir)
```
    Parameters:
    host - The host in which the context will be deployed
    contextPath - The context mapping to use, "" for root context.
    contextName - The context name
    dir - Base directory for the context, for static files. Must exist, relative to the server home
    
    Returns:
    the deployed context
    See Also:
    addContext(String, String)
  - addWebapp
```
public Context addWebapp(Host host,
                String contextPath,
                String docBase)
```
    This is equivalent to adding a web application to a Host's appBase (usually Tomcat's webapps directory). By default, the equivalent of the default web.xml will be applied to the web application (see initWebappDefaults(String)). This may be prevented by calling setAddDefaultWebXmlToWebapp(boolean) with false. Any WEB-INF/web.xml and META-INF/context.xml packaged with the application will always be processed and normal web fragment and ServletContainerInitializer processing will always be applied.
    
    Parameters:
    host - The host in which the context will be deployed
    contextPath - The context mapping to use, "" for root context.
    docBase - Base directory for the context, for static files. Must exist, relative to the server home
    
    Returns:
    the deployed context
  - addWebapp
```
@Deprecated
public Context addWebapp(Host host,
                           String contextPath,
                           String name,
                           String docBase)
```
    Deprecated. Use addWebapp(Host, String, String)
    
    Parameters:
    host - The host in which the context will be deployed
    contextPath - The context mapping to use, "" for root context.
    docBase - Base directory for the context, for static files. Must exist, relative to the server home
    name - Ignored. The contextPath will be used
    
    Returns:
    the deployed context
    See Also:
    addWebapp(String, String)
  - addWebapp
```
public Context addWebapp(Host host,
                String contextPath,
                String docBase,
                LifecycleListener config)
```
    This is equivalent to adding a web application to a Host's appBase (usually Tomcat's webapps directory). By default, the equivalent of the default web.xml will be applied to the web application (see initWebappDefaults(String)). This may be prevented by calling setAddDefaultWebXmlToWebapp(boolean) with false. Any WEB-INF/web.xml and META-INF/context.xml packaged with the application will always be processed and normal web fragment and ServletContainerInitializer processing will always be applied.
    
    Parameters:
    host - The host in which the context will be deployed
    contextPath - The context mapping to use, "" for root context.
    docBase - Base directory for the context, for static files. Must exist, relative to the server home
    config - Custom context configuration helper. Any configuration will be in addition to equivalent of the default web.xml configuration described above.
    
    Returns:
    the deployed context
  - getDefaultWebXmlListener
```
public LifecycleListener getDefaultWebXmlListener()
```
    Return a listener that provides the required configuration items for JSP processing. From the standard Tomcat global web.xml. Pass this to Lifecycle.addLifecycleListener(LifecycleListener) and then pass the result of noDefaultWebXmlPath() to ContextConfig.setDefaultWebXml(String).
    
    Returns:
    a listener object that configures default JSP processing.
  - noDefaultWebXmlPath
```
public String noDefaultWebXmlPath()
```
    Returns:
    a pathname to pass to ContextConfig.setDefaultWebXml(String) when using getDefaultWebXmlListener().
  - getDefaultRealm
```
@Deprecated
public Realm getDefaultRealm()
```
    Deprecated. Will be removed in Tomcat 8.0.x
    
    For complex configurations, this accessor allows callers of this class to obtain the simple realm created by default.
    
    Returns:
    the simple in-memory realm created by default.
  - initSimpleAuth
```
@Deprecated
protected void initSimpleAuth()
```
    Deprecated. Will be removed in Tomcat 8.0.x
    
    Create an in-memory realm. You can replace it for contexts with a real one. The Realm created here will be added to the Engine by default and may be replaced at the Engine level or over-ridden (as per normal Tomcat behaviour) at the Host or Context level.
  - initBaseDir
```
protected void initBaseDir()
```
  - setSilent
```
public void setSilent(boolean silent)
```
    Controls if the loggers will be silenced or not.
    
    Parameters:
    silent - true sets the log level to WARN for the loggers that log information on Tomcat start up. This prevents the usual startup information being logged. false sets the log level to the default level of INFO.
  - setAddDefaultWebXmlToWebapp
```
public void setAddDefaultWebXmlToWebapp(boolean addDefaultWebXmlToWebapp)
```
    By default, when calling addWebapp() to create a Context, the settings from from the default web.xml are added to the context. Calling this method with a false value prior to calling addWebapp() allows to opt out of the default settings. In that event you will need to add the configurations yourself, either programmatically or by using web.xml deployment descriptors.
    
    Parameters:
    addDefaultWebXmlToWebapp - false will prevent the class from automatically adding the default settings when calling addWebapp(). true will add the default settings and is the default behavior.
    See Also:
    addWebapp(Host, String, String, LifecycleListener)
  - enableNaming
```
public void enableNaming()
```
    Enables JNDI naming which is disabled by default. Server must implement Lifecycle in order for the NamingContextListener to be used.
  - initWebappDefaults
```
public void initWebappDefaults(String contextPath)
```
    Provide default configuration for a context. This is broadly the programmatic equivalent of the default web.xml and provides the following features:
    - Default servlet mapped to "/"
    - JSP servlet mapped to "*.jsp" and ""*.jspx"
    - Session timeout of 30 minutes
    - MIME mappings (subset of those in conf/web.xml)
    - Welcome files
    TODO: Align the MIME mappings with conf/web.xml - possibly via a common file.
    Parameters:
    contextPath - The path of the context to set the defaults for
  - initWebappDefaults
```
public static void initWebappDefaults(Context ctx)
```
    Static version of initWebappDefaults(String).
    
    Parameters:
    ctx - The context to set the defaults for
  - addDefaultMimeTypeMappings
```
public static void addDefaultMimeTypeMappings(Context context)
```
    Add the default MIME type mappings to the provide Context.
    
    Parameters:
    context - The web application to which the default MIME type mappings should be added.
  - getWebappConfigFile
```
protected URL getWebappConfigFile(String path,
                      String contextName)
```

Class Tomcat

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

server

service

engine

connector

host

port

hostname

basedir

defaultRealm

Constructor Detail

Tomcat

Method Detail

setBaseDir

setPort

setHostname

addWebapp

addWebapp

addContext

addServlet

addServlet

addServlet

addServlet

init

start

stop

destroy

addUser

addRole

getConnector

setConnector

getService

setHost

getHost

setDefaultRealm

getEngine

getServer

addContext

addContext

addWebapp

addWebapp

addWebapp

getDefaultWebXmlListener

noDefaultWebXmlPath

getDefaultRealm

initSimpleAuth

initBaseDir

setSilent

setAddDefaultWebXmlToWebapp

enableNaming

initWebappDefaults

initWebappDefaults

addDefaultMimeTypeMappings

getWebappConfigFile