Tomcat (Apache Tomcat 7.0.96 API Documentation)

org.apache.catalina.startup

## Class Tomcat

- java.lang.Object
- - 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.

  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 webapp contexts, all overloads of the method

      addWebapp

  . These methods create a webapp context, configure it, and then add it to a `Host`. They do not use a global default web.xml; rather, they add a lifecycle listener that adds the standard DefaultServlet, JSP processing, and welcome files.

  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 java.lang.String` | `basedir`
    `protected Connector` | `connector`
    `protected Realm` | `defaultRealm` Deprecated.
    `protected Engine` | `engine`
    `protected Host` | `host`
    `protected java.lang.String` | `hostname`
    `protected int` | `port`
    `protected Server` | `server`
    `protected Service` | `service`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `Tomcat()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `Context` | `addContext(Host host, java.lang.String contextPath, java.lang.String dir)`
    `Context` | `addContext(Host host, java.lang.String contextPath, java.lang.String contextName, java.lang.String dir)`
    `Context` | `addContext(java.lang.String contextPath, java.lang.String docBase)` Add a context - programmatic mode, no default web.xml used.
    `void` | `addRole(java.lang.String user, java.lang.String role)`
    `static Wrapper` | `addServlet(Context ctx, java.lang.String servletName, Servlet servlet)` Static version of `addServlet(String, String, Servlet)`.
    `static Wrapper` | `addServlet(Context ctx, java.lang.String servletName, java.lang.String servletClass)` Static version of `addServlet(String, String, String)`
    `Wrapper` | `addServlet(java.lang.String contextPath, java.lang.String servletName, Servlet servlet)` Add an existing Servlet to the context with no class.forName or initialisation.
    `Wrapper` | `addServlet(java.lang.String contextPath, java.lang.String servletName, java.lang.String servletClass)` Equivalent with .
    `void` | `addUser(java.lang.String user, java.lang.String pass)` Add a user for the in-memory realm.
    `Context` | `addWebapp(Host host, java.lang.String contextPath, java.lang.String docBase)`
    `Context` | `addWebapp(Host host, java.lang.String contextPath, java.lang.String docBase, LifecycleListener config)`
    `Context` | `addWebapp(Host host, java.lang.String contextPath, java.lang.String name, java.lang.String docBase)` Deprecated. Use `addWebapp(Host, String, String)`
    `Context` | `addWebapp(java.lang.String contextPath, java.lang.String docBase)` This is equivalent to adding a web application to Tomcat's webapps directory.
    `Context` | `addWebapp(java.lang.String contextPath, java.net.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 java.net.URL` | `getWebappConfigFile(java.lang.String path, java.lang.String contextName)`
    `void` | `init()` Initialise 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(java.lang.String contextPath)` Provide default configuration for a context.
    `java.lang.String` | `noDefaultWebXmlPath()`
    `void` | `setBaseDir(java.lang.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(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(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 java.lang.String hostname

    - #### basedir

          protected java.lang.String basedir

    - #### defaultRealm

          @Deprecated
          protected Realm defaultRealm

      Deprecated.

  - ### 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
      - $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().

    - #### setHostname

          public void setHostname(java.lang.String s)

      The the hostname of the default host, default is 'localhost'.

    - #### addWebapp

          public Context addWebapp(java.lang.String contextPath,
                          java.lang.String docBase)

      This is equivalent to adding a web application to Tomcat's webapps directory. The equivalent of the default web.xml will be applied to the web application and 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.

    - #### addWebapp

          public Context addWebapp(java.lang.String contextPath,
                          java.net.URL source)
                            throws java.io.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:
        `java.io.IOException` - If an I/O error occurs while copying the WAR file from the specified URL to the appBase

    - #### addContext

          public Context addContext(java.lang.String contextPath,
                           java.lang.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` - "" for root context.
        `docBase` - base dir for the context, for static files. Must exist, relative to the server home

    - #### addServlet

          public Wrapper addServlet(java.lang.String contextPath,
                           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");

      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,
                           java.lang.String servletName,
                           java.lang.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(java.lang.String contextPath,
                           java.lang.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,
                           java.lang.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

      Initialise the server.
      Throws:
        `LifecycleException`

    - #### start

          public void start()
                     throws LifecycleException

      Start the server.
      Throws:
        `LifecycleException`

    - #### stop

          public void stop()
                    throws LifecycleException

      Stop the server.
      Throws:
        `LifecycleException`

    - #### destroy

          public void destroy()
                       throws LifecycleException

      Destroy the server. This object cannot be used once this method has been called.
      Throws:
        `LifecycleException`

    - #### 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(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.

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

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

    - #### getServer

          public Server getServer()

      Get the server object. You can add listeners and few more customizations. JNDI is disabled by default.

    - #### addContext

          public Context addContext(Host host,
                           java.lang.String contextPath,
                           java.lang.String dir)

    - #### addContext

          public Context addContext(Host host,
                           java.lang.String contextPath,
                           java.lang.String contextName,
                           java.lang.String dir)

    - #### addWebapp

          public Context addWebapp(Host host,
                          java.lang.String contextPath,
                          java.lang.String docBase)

    - #### addWebapp

          @Deprecated
          public Context addWebapp(Host host,
                                     java.lang.String contextPath,
                                     java.lang.String name,
                                     java.lang.String docBase)

      Deprecated. Use `addWebapp(Host, String, String)`
      Parameters:
        `name` - Ignored. The contextPath will be used
      See Also:
        `addWebapp(String, String)`

    - #### addWebapp

          public Context addWebapp(Host host,
                          java.lang.String contextPath,
                          java.lang.String docBase,
                          LifecycleListener config)

      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 configurator helper
      Returns:
        the deployed context
      See Also:
        `addWebapp(String, String)`

    - #### 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 java.lang.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.

    - #### 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(java.lang.String contextPath)

      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
      Parameters:
        `contextPath` - 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

    - #### getWebappConfigFile

          protected java.net.URL getWebappConfigFile(java.lang.String path,
                                         java.lang.String contextName)

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