Overview | Package | Class | Tree | Deprecated | Index | Help
| Apache Tomcat 7.0.29
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

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

Method Summary
`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 .
`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)` Add a webapp using normal WEB-INF/web.xml if found.
`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.
`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

  Add a webapp using normal WEB-INF/web.xml if found.

  Parameters:
    `contextPath` -
    `baseDir` -
  Returns:
    new Context
  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 . 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

Overview | Package | Class | Tree | Deprecated | Index | Help
| Apache Tomcat 7.0.29
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

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