org.apache.catalina.startup

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

### Method Summary

Methods
`Context` `addContext(Host host, String contextPath, String dir)`
`Context` `addContext(Host host, String contextPath, String contextName, String dir)`
`Context` `addContext(String contextPath, String baseDir)` Add a context - programmatic mode, no web.xml used.
`void` `addRole(String user, String role)`
`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 with <servlet>.
`void` `addUser(String user, String pass)` Add a user for the in-memory realm.
`Context` `addWebapp(Host host, String url, String path)`
`Context` `addWebapp(Host host, String url, String name, String path)`
`Context` `addWebapp(String contextPath, String baseDir)` This is equivalent to adding a web application to Tomcat's webapps directory.
`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 url)`
`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(String contextPath)` Provide default configuration for a context.
`String` `noDefaultWebXmlPath()`
`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 - $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(String s)

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

#### addWebapp

    public Context addWebapp(String contextPath,
                    String baseDir)
                      throws ServletException

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.

Throws:
  `ServletException`

#### addContext

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

#### addServlet

    public Wrapper addServlet(String contextPath,
                     String servletName,
                     String servletClass)

Equivalent with <servlet>. 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

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(String user,
               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(String user,
               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,
                     String contextPath,
                     String dir)

#### addContext

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

#### addWebapp

    public Context addWebapp(Host host,
                    String url,
                    String path)

#### addWebapp

    public Context addWebapp(Host host,
                    String url,
                    String name,
                    String path)

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

#### 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 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 URL getWebappConfigFile(String path,
                          String url)