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