Tomcat (Apache Tomcat 9.0.120 API Documentation)
Description: declaration: package: org.apache.catalina.startup, class: Tomcat

# Class Tomcat

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()`.

`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.

See Also:
  - TestTomcat

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  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
  Description
  `protected String`
  `basedir`
  The base directory for the embedded server.
  `protected String`
  `hostname`
  The default hostname.
  `protected int`
  `port`
  The HTTP connector port.
  `protected Server`
  `server`
  The embedded Server instance.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `Tomcat()`
  Constructs a new embedded Tomcat instance with default settings.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `Context`
  `addContext(String contextPath, String docBase)`
  Add a context - programmatic mode, no default web.xml used.
  `Context`
  `addContext(Host host, String contextPath, String dir)`
  Adds a new context to the specified host.
  `Context`
  `addContext(Host host, String contextPath, String contextName, String dir)`
  Adds a new context to the specified host with the given context name.
  `static void`
  `addDefaultMimeTypeMappings(Context context)`
  Add the default MIME type mappings to the provided Context.
  `void`
  `addRole(String user, String role)`
  Add a role to a user.
  `Wrapper`
  `addServlet(String contextPath, String servletName, String servletClass)`
  Equivalent to <servlet><servlet-name><servlet-class>.
  `Wrapper`
  `addServlet(String contextPath, String servletName, Servlet servlet)`
  Add an existing Servlet to the context with no class.forName or initialisation.
  `static Wrapper`
  `addServlet(Context ctx, String servletName, String servletClass)`
  Static version of `addServlet(String, String, String)`
  `static Wrapper`
  `addServlet(Context ctx, String servletName, Servlet servlet)`
  Static version of `addServlet(String, String, Servlet)`.
  `void`
  `addUser(String user, String pass)`
  Add a user for the in-memory realm.
  `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.
  `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).
  `protected Realm`
  `createDefaultRealm()`
  Create an in-memory realm.
  `void`
  `destroy()`
  Destroy the server.
  `void`
  `enableNaming()`
  Enables JNDI naming which is disabled by default.
  `Connector`
  `getConnector()`
  Get the default HTTP connector that is used by the embedded Tomcat.
  `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()`
  Returns the default Host for this embedded Tomcat instance.
  `Server`
  `getServer()`
  Get the server object.
  `Service`
  `getService()`
  Get the service object.
  `protected URL`
  `getWebappConfigFile(String path, String contextName)`
  Finds the web application configuration file (web.xml) for the given path.
  `void`
  `init()`
  Initialize the server.
  `void`
  `init(ConfigurationSource source)`
  Initialize the server given the specified configuration source.
  `void`
  `init(ConfigurationSource source, String[] catalinaArguments)`
  Initialize the server given the specified configuration source.
  `protected void`
  `initBaseDir()`
  Initializes the base directory from system properties if not already set.
  `void`
  `initWebappDefaults(String contextPath)`
  Provide default configuration for a context.
  `static void`
  `initWebappDefaults(Context ctx)`
  Static version of `initWebappDefaults(String)`.
  `static void`
  `main(String[] args)`
  Main executable method for use with a Maven packager.
  `String`
  `noDefaultWebXmlPath()`
  Returns a special path that disables the default web.xml.
  `void`
  `setAddDefaultWebXmlToWebapp(boolean addDefaultWebXmlToWebapp)`
  By default, when calling addWebapp() to create a Context, the settings from the default web.xml are added to the context.
  `void`
  `setBaseDir(String basedir)`
  Tomcat requires that the base directory is set because the defaults for a number of other locations, such as the work directory, are derived from the base directory.
  `void`
  `setConnector(Connector connector)`
  Set the specified connector in the service, if it is not already present.
  `void`
  `setHost(Host host)`
  Sets the current host - all future webapps will be added to this host.
  `void`
  `setHostname(String s)`
  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 Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Field Details

  - ### server

    protected Server server
    The embedded Server instance.

  - ### port

    protected int port
    The HTTP connector port.

  - ### hostname

    protected String hostname
    The default hostname.

  - ### basedir

    protected String basedir
    The base directory for the embedded server.

- ## Constructor Details

  - ### Tomcat

    public Tomcat()
    Constructs a new embedded Tomcat instance with default settings.

- ## Method Details

  - ### setBaseDir

    public void setBaseDir(String basedir)
    Tomcat requires that the base directory is set because the defaults for a number of other locations, such as the work directory, are derived from the base directory. This should be the first method called.

    If this method is not called then Tomcat will attempt to use these locations in the following order:

    1. if set, the catalina.base system property
    2. if set, the catalina.home system property
    3. The user.dir system property (the directory where Java was run from) where a directory named tomcat.$PORT will be created. $PORT is the value configured via `setPort(int)` which defaults to 8080 if not set
    The user should ensure that the file permissions for the base directory are appropriate.

    TODO: disable work dir if not needed ( no jsp, etc ).

    Parameters:
      `basedir` - The Tomcat base folder on which all others will be derived

  - ### setPort

    public void setPort(int port)
    Set the port for the default connector. The default connector will only be created if getConnector is called.
    Parameters:
      `port` - The port number

  - ### setHostname

    public void setHostname(String s)
    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 and be an absolute path.
    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. This means that there is no JSP support (no JSP servlet), no default servlet and no web socket support unless explicitly enabled via the programmatic interface. There is also no `ServletContainerInitializer` processing and no annotation processing. If a `ServletContainerInitializer` is added programmatically, there will still be no scanning for `HandlesTypes` matches.

    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(ConfigurationSource source)
    Initialize the server given the specified configuration source. The server will be loaded according to the Tomcat configuration files contained in the source (server.xml, web.xml, context.xml, SSL certificates, etc). If no configuration source is specified, it will use the default locations for these files.
    Parameters:
      `source` - The configuration source

  - ### init

    public void init(ConfigurationSource source, String[] catalinaArguments)
    Initialize the server given the specified configuration source. The server will be loaded according to the Tomcat configuration files contained in the source (server.xml, web.xml, context.xml, SSL certificates, etc). If no configuration source is specified, it will use the default locations for these files.
    Parameters:
      `source` - The configuration source
      `catalinaArguments` - The arguments that should be passed to Catalina

  - ### 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 username
      `pass` - The password

  - ### addRole

    public void addRole(String user, String role)
    Add a role to a user.
    Parameters:
      `user` - The username
      `role` - The role name
    See Also:
      - `addUser(String, String)`

  - ### getConnector

    public Connector getConnector()
    Get the default HTTP connector that is used by the embedded Tomcat. It is first configured connector in the service. If there's no connector defined, it will create and add a default connector using the port and address specified in this Tomcat instance, and return it for further customization.
    Returns:
      The connector object

  - ### setConnector

    public void setConnector(Connector connector)
    Set the specified connector in the service, if it is not already present.
    Parameters:
      `connector` - The connector instance to add

  - ### 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()
    Returns the default Host for this embedded Tomcat instance.
    Returns:
      the default Host

  - ### 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)
    Adds a new context to the specified host.
    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)
    Adds a new context to the specified host with the given context name.
    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 and be an absolute path.
    Returns:
      the deployed context

  - ### 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 and be an absolute path.
      `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 special path that disables the default web.xml.
    Returns:
      a pathname to pass to `ContextConfig.setDefaultWebXml(String)` when using `getDefaultWebXmlListener()`

  - ### createDefaultRealm

    protected Realm createDefaultRealm()
    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.
    Returns:
      a realm instance

  - ### initBaseDir

    protected void initBaseDir()
    Initializes the base directory from system properties if not already set.

  - ### 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 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
    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 provided Context.
    Parameters:
      `context` - The web application to which the default MIME type mappings should be added.

  - ### getWebappConfigFile

    protected URL getWebappConfigFile(String path, String contextName)
    Finds the web application configuration file (web.xml) for the given path.
    Parameters:
      `path` - the document base path
      `contextName` - the context name
    Returns:
      the configuration file URL, or null if not found

  - ### main

    public static void main(String[] args) throws Exception
    Main executable method for use with a Maven packager.
    Parameters:
      `args` - the command line arguments
    Throws:
      `Exception` - if an error occurs