Tomcat 10.1.19 · org.apache.catalina.startup.Tomcat · APIdia, the JavaDoc alternative

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 web application contexts; all overloads of the method addWebapp(). These methods are equivalent to adding a web application to the Host's appBase (normally the webapps directory). These methods create a Context, configure it with the equivalent of the defaults provided by conf/web.xml (see initWebappDefaults(String) for details) and add the Context to a Host. These methods do not use a global default web.xml; rather, they add a LifecycleListener to configure the defaults. Any WEB-INF/web.xml and META-INF/context.xml packaged with the application will be processed normally. Normal web fragment and jakarta.servlet.ServletContainerInitializer processing will be applied.

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

Modifier and Type	Class and Description
public static class	Tomcat.DefaultWebXmlListener Fix reload - required if reloading and using programmatic configuration.
public static class	Tomcat.ExistingStandardWrapper Helper class for wrapping existing servlets.
public static class	Tomcat.FixContextListener Fix startup sequence - required if you don't use web.xml.
private class	Tomcat.SimpleRealm

Modifier and Type	Field and Description
private boolean	addDefaultWebXmlToWebapp
protected String	basedir
protected String	hostname
private final Map<String, Logger>	pinnedLoggers
protected int	port
protected Server	server
pack-priv static final String[]	silences
private boolean	silent
private static final StringManager	sm
private final Map<String, String>	userPass
private final Map<String, Principal>	userPrincipals
private final Map<String, List<String>>	userRoles

Access	Constructor and Description
public	Tomcat()

Method Summary

Modifier and Type	Method and Description
public Context	Returns: the deployed context addContext(String The context mapping to use, "" for root context. contextPath, String Base directory for the context, for static files. Must exist, relative to the server home docBase) Add a context - programmatic mode, no default web.xml used.
public Context	Returns: the deployed context addContext(Host The host in which the context will be deployed host, String The context mapping to use, "" for root context. contextPath, String Base directory for the context, for static files. Must exist, relative to the server home dir)
public Context	Returns: the deployed context addContext(Host The host in which the context will be deployed host, String The context mapping to use, "" for root context. contextPath, String The context name contextName, String Base directory for the context, for static files. Must exist, relative to the server home dir)
public static void	addDefaultMimeTypeMappings(Context The web application to which the default MIME type mappings should be added. context) Add the default MIME type mappings to the provide Context.
public void	addRole(String The user name user, String The role name role) Add a role to a user.
public Wrapper	Returns: The wrapper for the servlet addServlet(String Context to add Servlet to contextPath, String Servlet name (used in mappings) servletName, String The class to be used for the Servlet servletClass) Equivalent to <servlet><servlet-name><servlet-class>.
public static Wrapper	Returns: The wrapper for the servlet addServlet(Context Context to add Servlet to ctx, String Servlet name (used in mappings) servletName, String The class to be used for the Servlet servletClass) Static version of `addServlet(String, String, String)`
public Wrapper	Returns: The wrapper for the servlet addServlet(String Context to add Servlet to contextPath, String Servlet name (used in mappings) servletName, Servlet The Servlet to add servlet) Add an existing Servlet to the context with no class.forName or initialisation.
public static Wrapper	Returns: The wrapper for the servlet addServlet(Context Context to add Servlet to ctx, String Servlet name (used in mappings) servletName, Servlet The Servlet to add servlet) Static version of `addServlet(String, String, Servlet)`.
public void	addUser(String The user name user, String The password pass) Add a user for the in-memory realm.
public Context	Returns: the deployed context addWebapp(String The context mapping to use, "" for root context. contextPath, String Base directory for the context, for static files. Must exist and be an absolute path. docBase) This is equivalent to adding a web application to a Host's appBase (usually Tomcat's webapps directory).
public Context	Returns: The deployed Context addWebapp(String The context mapping to use, "" for root context. contextPath, URL The location from which the WAR should be copied source) Copy the specified WAR file to the Host's appBase and then call `addWebapp(String, String)` with the newly copied WAR.
public Context	Returns: the deployed context addWebapp(Host The host in which the context will be deployed host, String The context mapping to use, "" for root context. contextPath, String Base directory for the context, for static files. Must exist and be an absolute path. docBase) This is equivalent to adding a web application to a Host's appBase (usually Tomcat's webapps directory).
public Context	Returns: the deployed context addWebapp(Host The host in which the context will be deployed host, String The context mapping to use, "" for root context. contextPath, String Base directory for the context, for static files. Must exist and be an absolute path. docBase, LifecycleListener Custom context configuration helper. Any configuration will be in addition to equivalent of the default web.xml configuration described above. config) This is equivalent to adding a web application to a Host's appBase (usually Tomcat's webapps directory).
private Context	Returns: newly created `Context` createContext(Host host for which the `Context` should be created, or `null` if default host should be used host, String path of the webapp which should get the `Context` url) Create the configured `Context` for the given `host`.
protected Realm	Returns: a realm instance createDefaultRealm() Create an in-memory realm.
public void	destroy() Destroy the server.
public void	enableNaming() Enables JNDI naming which is disabled by default.
public Connector	Returns: The connector object getConnector() Get the default HTTP connector that is used by the embedded Tomcat.
public LifecycleListener	Returns: a listener object that configures default JSP processing. getDefaultWebXmlListener() Return a listener that provides the required configuration items for JSP processing.
public Engine	Returns: The engine getEngine() Access to the engine, for further customization.
public Host	getHost()
private String	getLoggerName(Host host, String contextName)
public Server	Returns: The Server getServer() Get the server object.
public Service	Returns: The service getService() Get the service object.
protected URL	getWebappConfigFile(String path, String contextName)
private URL	getWebappConfigFileFromDirectory(File docBase, String contextName)
private URL	getWebappConfigFileFromWar(File docBase, String contextName)
public void	init(ConfigurationSource The configuration source source) Initialize the server given the specified configuration source.
public void	init(ConfigurationSource The configuration source source, String[] The arguments that should be passed to Catalina catalinaArguments) Initialize the server given the specified configuration source.
public void	init() Initialize the server.
protected void	initBaseDir()
public void	initWebappDefaults(String The path of the context to set the defaults for contextPath) Provide default configuration for a context.
public static void	initWebappDefaults(Context The context to set the defaults for ctx) Static version of `initWebappDefaults(String)`.
public static void	main(String[] the command line arguments args) Main executable method for use with a Maven packager.
public String	Returns: a pathname to pass to `ContextConfig#setDefaultWebXml(String)` when using `getDefaultWebXmlListener()`. noDefaultWebXmlPath()
public void	setAddDefaultWebXmlToWebapp(boolean `false` will prevent the class from automatically adding the default settings when calling addWebapp(). `true` will add the default settings and is the default behavior. addDefaultWebXmlToWebapp) By default, when calling addWebapp() to create a Context, the settings from from the default web.xml are added to the context.
public void	setBaseDir(String The Tomcat base folder on which all others will be derived basedir) Tomcat requires that the base directory is set because the defaults for a number of other locations, such as the work directory, are derived from the base directory.
public void	setConnector(Connector The connector instance to add connector) Set the specified connector in the service, if it is not already present.
public void	setHost(Host The current host host) Sets the current host - all future webapps will be added to this host.
public void	setHostname(String The default host name s) The the hostname of the default host, default is 'localhost'.
public void	setPort(int The port number port) Set the port for the default connector.
public void	setSilent(boolean `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. silent) Controls if the loggers will be silenced or not.
private void	silence(Host host, String contextPath)
public void	start() Start the server.
public void	stop() Stop the server.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

public Class Tomcat

Nested and Inner Type Summary

Field Summary

Constructor Summary

Method Summary