ch.rasc.embeddedtc

Class EmbeddedTomcat

java.lang.Object

ch.rasc.embeddedtc.EmbeddedTomcat

public class EmbeddedTomcat
extends Object

Helper class to simplify setting up a Embedded Tomcat in a IDE and with a Maven web project.

Author:

Ralph Schaer

Constructor Summary

Constructors

Constructor and Description
EmbeddedTomcat() Creates an embedded Tomcat with context path "" and port 8080.
EmbeddedTomcat(int port) Creates an embedded Tomcat with context path "" and specified port.
EmbeddedTomcat(String contextPath) Creates an embedded Tomcat with the specified context path and port 8080 Context directory points to current directory + /src/main/webapp Change context directory with the method setContextDirectory(String)
EmbeddedTomcat(String contextPath, int port) Creates an embedded Tomcat with specified context path and specified port.

Method Summary

Methods

Modifier and Type	Method and Description
EmbeddedTomcat	addContextEnvironment(org.apache.catalina.deploy.ContextEnvironment env) Adds a ContextEnvironment object to embedded Tomcat.
EmbeddedTomcat	addContextEnvironment(String name, String value, String type) Convenient method for adding a context environment to the embedded Tomcat.
EmbeddedTomcat	addContextEnvironmentAndResourceFromFile(File contextFile) Deprecated. use setContextFile(URL)
EmbeddedTomcat	addContextEnvironmentAndResourceFromFile(String contextFile) Deprecated. use setContextFile(String)
EmbeddedTomcat	addContextEnvironmentString(String name, String value) Convenient method for adding a context environment with type java.lang.String to the embedded Tomcat.
EmbeddedTomcat	addContextInitializationParameter(String name, String value)
EmbeddedTomcat	addContextResource(org.apache.catalina.deploy.ContextResource res) Adds a ContextResource object to the list of resources in the embedded Tomcat.
EmbeddedTomcat	addDefaultListeners() Installs the default listeners AprLifecycleListener, JasperListener, JreMemoryLeakPreventionListener, GlobalResourcesLifecycleListener and ThreadLocalLeakPreventionListener during startup.
static EmbeddedTomcat	create() Convenient method to create a embedded Tomcat that listens on port 8080 and with a context path of ""
EmbeddedTomcat	dontAddShutdownHook() The EmbeddedTomcat opens as default a shutdown port on port + 1000 with the shutdown command EMBEDDED_TC_SHUTDOWN Calling this method disables adding the shutdown hook.
EmbeddedTomcat	enableNaming() Enables JNDI naming which is disabled by default.
static void	main(String[] args) Starts a embedded Tomcat on port 8080 with context path "" and context directory current directory + /src/main/webapp
EmbeddedTomcat	setContextDirectory(String contextDirectory) Sets the context directory.
EmbeddedTomcat	setContextFile(String contextFile) Sets the location of the context file that configures this web application
EmbeddedTomcat	setContextFile(URL contextFileURL) Sets the location of the context file that configures this web application
EmbeddedTomcat	setContextPath(String contextPath) Sets the contextPath for the webapplication
EmbeddedTomcat	setPort(int port) Sets the port the server is listening for http requests
EmbeddedTomcat	setPrivileged(boolean privileged) Set the privileged flag for this web application.
EmbeddedTomcat	setSecondsToWaitBeforePortBecomesAvailable(int seconds) Before starting the embedded Tomcat the programm tries to stop a previous process by sendig the shutdown command to the shutdown port.
EmbeddedTomcat	setShutdownPort(int shutdownPort) Specifies the port the server is listen for the shutdown command.
EmbeddedTomcat	setSilent(boolean silent) Set the silent flag of Tomcat.
EmbeddedTomcat	setTempDirectory(File tempDirectory) Sets the location of the temporary directory.
EmbeddedTomcat	setTempDirectoryName(String name) Sets the temporary directory to a directory beneath the target directory The directory does not have to exists, Tomcat will create it automatically if necessary.
EmbeddedTomcat	skipJarsContextConfig(String skipJars) Additional JARs (over and above the default JARs set with skipJarsDefaultJarScanner(String)) to skip when scanning for Servlet 3.0 pluggability features.
EmbeddedTomcat	skipJarsDefaultJarScanner(String skipJars) List of JAR files that should not be scanned using the JarScanner functionality.
EmbeddedTomcat	skipJarsTldConfig(String skipJars) Additional JARs (over and above the default JARs set with skipJarsDefaultJarScanner(String)) to skip when scanning for TLDs.
void	start() Starts the embedded Tomcat and do not wait for incoming requests.
void	startAndWait() Starts the embedded Tomcat and waits for incoming requests.
void	stop() Stops the embedded tomcat.
EmbeddedTomcat	useNio() Instructs the embedded tomcat to use the Non Blocking Connector (org.apache.coyote.http11.Http11NioProtocol) instead of the Blocking Connector (org.apache.coyote.http11.Http11Protocol)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

EmbeddedTomcat

public EmbeddedTomcat()

Creates an embedded Tomcat with context path "" and port 8080. Context directory points to current directory + /src/main/webapp Change context directory with the method setContextDirectory(String)

See Also:

setContextDirectory(String)

EmbeddedTomcat

public EmbeddedTomcat(int port)

Creates an embedded Tomcat with context path "" and specified port. Context directory points to current directory + /src/main/webapp Change context directory with the method setContextDirectory(String)

Parameters:

port - ip port the server is listening

See Also:

setContextDirectory(String)

EmbeddedTomcat

public EmbeddedTomcat(String contextPath)

Creates an embedded Tomcat with the specified context path and port 8080 Context directory points to current directory + /src/main/webapp Change context directory with the method setContextDirectory(String)

Parameters:

contextPath - The context path has to start with /

See Also:

setContextDirectory(String)

EmbeddedTomcat

public EmbeddedTomcat(String contextPath,
              int port)

Creates an embedded Tomcat with specified context path and specified port. Context directory points to current directory + /src/main/webapp Change context directory with the method setContextDirectory(String)

Parameters:

contextPath - has to start with /

port - ip port the server is listening

See Also:

setContextDirectory(String)

Method Detail

main

public static void main(String[] args)

Starts a embedded Tomcat on port 8080 with context path "" and context directory current directory + /src/main/webapp

Parameters:

args - program arguments

create

public static EmbeddedTomcat create()

Convenient method to create a embedded Tomcat that listens on port 8080 and with a context path of ""

Returns:

EmbeddedTomcat the embedded tomcat

setPort

public EmbeddedTomcat setPort(int port)

Sets the port the server is listening for http requests

Parameters:

port - The new port

Returns:

The embedded Tomcat

setContextPath

public EmbeddedTomcat setContextPath(String contextPath)

Sets the contextPath for the webapplication

Parameters:

contextPath - The new contextPath. Has to start with / or is the empty "" string

Returns:

The embedded Tomcat

setContextDirectory

public EmbeddedTomcat setContextDirectory(String contextDirectory)

Sets the context directory. Normally this point to the directory that hosts the WEB-INF directory. Default value is: current directory + /src/main/webapp This is the normal location of the webapplication directory in a Maven web app project.

Parameters:

contextDirectory - Path name to the directory that contains the web application.

Returns:

The embedded Tomcat

skipJarsDefaultJarScanner

public EmbeddedTomcat skipJarsDefaultJarScanner(String skipJars)

List of JAR files that should not be scanned using the JarScanner functionality. This is typically used to scan JARs for configuration information. JARs that do not contain such information may be excluded from the scan to speed up the scanning process. JARs on this list are excluded from all scans.

Scan specific lists (to exclude JARs from individual scans) see skipJarsContextConfig(String) and skipJarsTldConfig(String).

The list must be a comma separated list of JAR file names. Example: spring*.jar,cglib*.jar.

This list is appended to the default list. The default list is located in the file CATALINA_HOME\conf\catalina.properties under the key tomcat.util.scan.DefaultJarScanner.jarsToSkip

Parameters:

skipJars - list of jars, comma separated

Returns:

The embedded Tomcat

skipJarsContextConfig

public EmbeddedTomcat skipJarsContextConfig(String skipJars)

Additional JARs (over and above the default JARs set with skipJarsDefaultJarScanner(String)) to skip when scanning for Servlet 3.0 pluggability features. These features include web fragments, annotations, SCIs and classes that match @HandlesTypes. The list must be a comma separated list of JAR file names.

Parameters:

skipJars - list of jars, comma separated

Returns:

The embedded Tomcat

skipJarsTldConfig

public EmbeddedTomcat skipJarsTldConfig(String skipJars)

Additional JARs (over and above the default JARs set with skipJarsDefaultJarScanner(String)) to skip when scanning for TLDs. The list must be a comma separated list of JAR file names.

Parameters:

skipJars - list of jars, comma separated

Returns:

The embedded Tomcat

setTempDirectory

public EmbeddedTomcat setTempDirectory(File tempDirectory)

Sets the location of the temporary directory. Tomcat needs this for storing temporary files like compiled jsp files. Default value is

target/tomcat. + port

Parameters:

tempDirectory - File object that represents the location of the temp directory

Returns:

The embedded Tomcat

setTempDirectoryName

public EmbeddedTomcat setTempDirectoryName(String name)

Sets the temporary directory to a directory beneath the target directory
The directory does not have to exists, Tomcat will create it automatically if necessary.

Parameters:

name - directory name

Returns:

The embedded Tomcat

See Also:

setTempDirectory(File)

dontAddShutdownHook

public EmbeddedTomcat dontAddShutdownHook()

The EmbeddedTomcat opens as default a shutdown port on port + 1000 with the shutdown command EMBEDDED_TC_SHUTDOWN Calling this method disables adding the shutdown hook.

Returns:

The embedded Tomcat

setSecondsToWaitBeforePortBecomesAvailable

public EmbeddedTomcat setSecondsToWaitBeforePortBecomesAvailable(int seconds)

Before starting the embedded Tomcat the programm tries to stop a previous process by sendig the shutdown command to the shutdown port. It then waits for the port to become available. It checks this every second for the specified number of seconds

Parameters:

seconds - number of seconds

Returns:

The embedded Tomcat

setShutdownPort

public EmbeddedTomcat setShutdownPort(int shutdownPort)

Specifies the port the server is listen for the shutdown command. Default is port + 1000

Parameters:

shutdownPort - the shutdown port

Returns:

The embedded Tomcat *

See Also:

dontAddShutdownHook()

setPrivileged

public EmbeddedTomcat setPrivileged(boolean privileged)

Set the privileged flag for this web application.

Parameters:

privileged - The new privileged flag

Returns:

The embedded Tomcat

useNio

public EmbeddedTomcat useNio()

Instructs the embedded tomcat to use the Non Blocking Connector (org.apache.coyote.http11.Http11NioProtocol) instead of the Blocking Connector (org.apache.coyote.http11.Http11Protocol)

Returns:

The embedded Tomcat

enableNaming

public EmbeddedTomcat enableNaming()

Enables JNDI naming which is disabled by default.

Returns:

The embedded Tomcat

addDefaultListeners

public EmbeddedTomcat addDefaultListeners()

Installs the default listeners AprLifecycleListener, JasperListener, JreMemoryLeakPreventionListener, GlobalResourcesLifecycleListener and ThreadLocalLeakPreventionListener during startup.

Returns:

The embedded Tomcat

setSilent

public EmbeddedTomcat setSilent(boolean silent)

Set the silent flag of Tomcat. If true Tomcat no longer prints any log messages

Parameters:

silent - The new silent flag

Returns:

The embedded Tomcat

addContextEnvironment

public EmbeddedTomcat addContextEnvironment(org.apache.catalina.deploy.ContextEnvironment env)

Adds a ContextEnvironment object to embedded Tomcat.

Example:
Tomcat context xml file

    <Environment name="aparam" 
                 value="test" 
                 type="java.lang.String" 
                 override="false"/>
 

A programmatic way to add this environment to the embedded Tomcat is by calling this method

 ContextEnvironment env = new ContextEnvironment();
 env.setType("java.lang.String");
 env.setName("aparam");
 env.setValue("test");
 embeddedTomcat.addContextEnvironment(env);
 

Parameters:

env - context environment variable

Returns:

The embedded Tomcat

See Also:

ContextEnvironment, NamingResources.addEnvironment(ContextEnvironment), addContextEnvironment(String, String, String), addContextEnvironmentString(String, String)

addContextResource

public EmbeddedTomcat addContextResource(org.apache.catalina.deploy.ContextResource res)

Adds a ContextResource object to the list of resources in the embedded Tomcat.

Example:
Tomcat context xml file

  <Resource name="jdbc/ds" auth="Container"
     type="javax.sql.DataSource" username="sa" password=""
     driverClassName="org.h2.Driver"
     url="jdbc:h2:~/mydb"
     maxActive="20" maxIdle="4" maxWait="10000"
     defaultAutoCommit="false"/>
 

Programmatic way:

 ContextResource res = new ContextResource();
 res.setName("jdbc/ds");
 res.setType("javax.sql.DataSource");
 res.setAuth("Container");
 res.setProperty("username", "sa");
 res.setProperty("password", "");
 res.setProperty("driverClassName", "org.h2.Driver");
 res.setProperty("url", "jdbc:h2:˜/mydb");
 res.setProperty("maxActive", "20");
 res.setProperty("maxIdle", "4");
 res.setProperty("maxWait", "10000");
 res.setProperty("defaultAutoCommit", "false");
 
 embeddedTomcat.addContextResource(res);
 

Parameters:

res - resource object

Returns:

The embedded Tomcat

See Also:

ContextResource, NamingResources.addResource(ContextResource)

addContextInitializationParameter

public EmbeddedTomcat addContextInitializationParameter(String name,
                                               String value)

addContextEnvironment

public EmbeddedTomcat addContextEnvironment(String name,
                                   String value,
                                   String type)

Convenient method for adding a context environment to the embedded Tomcat. Creates a ContextEnvironment object and adds it to the list of the context environments.

Example:
Tomcat context xml file

    <Environment name="aparam" 
                 value="test" 
                 type="java.lang.String" 
                 override="false"/>
 

Programmatic way:

 embeddedTomcat.addContextEnvironment("aparam", "test", "java.lang.String");
 

Parameters:

name - name of the context environment

value - value of the context environment

type - type of the context environment

Returns:

The embedded Tomcat

See Also:

ContextEnvironment, NamingResources.addEnvironment(ContextEnvironment), addContextEnvironment(ContextEnvironment), addContextEnvironmentString(String, String)

addContextEnvironmentString

public EmbeddedTomcat addContextEnvironmentString(String name,
                                         String value)

Convenient method for adding a context environment with type java.lang.String to the embedded Tomcat.

 embeddedTomcat.addContextEnvironment("aparam", "test");
 

Parameters:

name - name of the context environment

value - value of the context environment

Returns:

The embedded Tomcat

See Also:

ContextEnvironment, NamingResources.addEnvironment(ContextEnvironment), addContextEnvironment(ContextEnvironment), addContextEnvironment(String, String, String)

addContextEnvironmentAndResourceFromFile

@Deprecated
public EmbeddedTomcat addContextEnvironmentAndResourceFromFile(File contextFile)

Deprecated. use setContextFile(URL)

Read ContextEnvironment and ContextResource definition from a text file.

Parameters:

contextFile - Location of the context file

Returns:

The embedded Tomcat

setContextFile

public EmbeddedTomcat setContextFile(URL contextFileURL)

Sets the location of the context file that configures this web application

Parameters:

contextFileURL - Location of the context file

Returns:

The embedded Tomcat instance

setContextFile

public EmbeddedTomcat setContextFile(String contextFile)

Sets the location of the context file that configures this web application

Parameters:

contextFile - Location of the context file

Returns:

The embedded Tomcat instance

addContextEnvironmentAndResourceFromFile

@Deprecated
public EmbeddedTomcat addContextEnvironmentAndResourceFromFile(String contextFile)

Deprecated. use setContextFile(String)

Read ContextEnvironment and ContextResource definition from a text file.

Parameters:

contextFile - Location to a context file

Returns:

The embedded Tomcat

start

public void start()

Starts the embedded Tomcat and do not wait for incoming requests. Returns immediately if the configured port is in use.

See Also:

startAndWait()

startAndWait

public void startAndWait()

Starts the embedded Tomcat and waits for incoming requests. Returns immediately if the configured port is in use.

See Also:

start()

stop

public void stop()

Stops the embedded tomcat. Does nothing if it's not started