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(). 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 String	basedir
protected Connector	connector
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

Modifier and Type	Method and Description
Context	addContext(Host host, String contextPath, String dir)
Context	addContext(Host host, String contextPath, String contextName, String dir)
Context	addContext(String contextPath, String docBase) Add a context - programmatic mode, no default web.xml used.
void	addRole(String user, String role) Add a role to a user.
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 to <servlet><servlet-name><servlet-class>.
void	addUser(String user, String pass) Add a user for the in-memory realm.
Context	addWebapp(Host host, String contextPath, String docBase)
Context	addWebapp(Host host, String contextPath, String docBase, ContextConfig config)
Context	addWebapp(String contextPath, String docBase) This is equivalent to adding a web application to 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.
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 contextName)
void	init() Initialize the server.
protected void	initBaseDir()
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	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

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 - $PWD/tomcat.$PORT (/tmp doesn't seem a good choice for security). 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. Must be called before start().

Parameters:

port - The port number

setHostname

public void setHostname(String s)

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

Parameters:

s - The default host name

addWebapp

public Context addWebapp(String contextPath,
                         String docBase)
                  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.

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

Throws:

ServletException - if a deployment error occurs

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()
          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 user name

pass - The password

addRole

public void addRole(String user,
                    String role)

Add a role to a user.

Parameters:

user - The user name

role - The role name

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.

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

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)

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)

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)

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

Returns:

the deployed context

See Also:

addWebapp(String, String)

addWebapp

public Context addWebapp(Host host,
                         String contextPath,
                         String docBase,
                         ContextConfig 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 String noDefaultWebXmlPath()

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

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 contextName)