The LifeCycle Listener Component

Table of Contents

Introduction

A Listener element defines a component that performs actions when specific events occur, usually Tomcat starting or Tomcat stopping.

Listeners may be nested inside a Server, Engine, Host or Context. Some Listeners are only intended to be nested inside specific elements. These constraints are noted in the documentation below.

Attributes

Common Attributes

All implementations of Listener support the following attributes:

Attribute Description
className

Java class name of the implementation to use. This class must implement the org.apache.catalina.LifecycleListener interface.

Nested Components

No element may be nested inside a Listener.

Standard Implementations

Unlike most Catalina components, there are several standard Listener implementations available. As a result, the className attribute MUST be used to select the implementation you wish to use.

APR Lifecycle Listener - org.apache.catalina.core.AprLifecycleListener

The APR Lifecycle Listener checks for the presence of the APR/native library and loads the library if it is present. For more information see the APR/native guide.

This listener must only be nested within Server elements.

The following additional attributes are supported by the APR Lifecycle Listener:

Attribute Description
SSLEngine

Name of the SSLEngine to use. off: do not use SSL, on: use SSL but no specific ENGINE.

The default value is on. This initializes the native SSL engine, which must be enabled in the APR/native connector by the use of the SSLEnabled attribute.

See the Official OpenSSL website for more details on supported SSL hardware engines and manufacturers.

SSLRandomSeed

Entropy source used to seed the SSLEngine's PRNG. The default value is builtin. On development systems, you may want to set this to /dev/urandom to allow quicker start times.

FIPSMode

Set to on to request that OpenSSL be in FIPS mode (if OpenSSL is already in FIPS mode, it will remain in FIPS mode). Set to enter to force OpenSSL to enter FIPS mode (an error will occur if OpenSSL is already in FIPS mode). Set to require to require that OpenSSL already be in FIPS mode (an error will occur if OpenSSL is not already in FIPS mode).

FIPS mode requires you to have a FIPS-capable OpenSSL library which you must build yourself. If this attribute is set to any of the above values, the SSLEngine must be enabled as well.

The default value is off.

useAprConnector

This attribute controls the auto-selection of the connector implementation. When the protocol is specified as HTTP/1.1 or AJP/1.3 then if this attribute is true the APR/native connector will be used but if this attribute is false the NIO connector will be used.

useOpenSSL

This attribute controls the auto-selection of the OpenSSL JSSE implementation. The default is true which will use OpenSSL if the native library is available and a NIO or NIO2 connector is used.

Global Resources Lifecycle Listener - org.apache.catalina.mbeans.GlobalResourcesLifecycleListener

The Global Resources Lifecycle Listener initializes the Global JNDI resources defined in server.xml as part of the Global Resources element. Without this listener, none of the Global Resources will be available.

This listener must only be nested within Server elements.

No additional attributes are supported by the Global Resources Lifecycle Listener.

JNI Library Loading Listener - org.apache.catalina.core.JniLifecycleListener

The JNI Library Loading Listener makes it possible for multiple Webapps to use a native library, by loading the native library using a shared class loader (typically the Common class loader but may vary in some configurations)

The listener supports two mutually exclusive attributes, so one of them must be used, but you can not use both together:

Attribute Description
libraryName

The name of the native library, as defined in java.lang.System.loadLibrary()

libraryPath

The absolute path of the native library, as defined in java.lang.System.load()

JRE Memory Leak Prevention Listener - org.apache.catalina.core.JreMemoryLeakPreventionListener

The JRE Memory Leak Prevention Listener provides work-arounds for known places where the Java Runtime environment uses the context class loader to load a singleton as this will cause a memory leak if a web application class loader happens to be the context class loader at the time. The work-around is to initialise these singletons when this listener starts as Tomcat's common class loader is the context class loader at that time. It also provides work-arounds for known issues that can result in locked JAR files.

This listener must only be nested within Server elements.

The following additional attributes are supported by the JRE Memory Leak Prevention Listener:

Attribute Description
appContextProtection

Enables protection so that calls to sun.awt.AppContext.getAppContext() triggered by a web application do not result in a memory leak. Note that enabling this protection will trigger a requirement for a graphical environment unless Java is started in head-less mode. The default is false. This protection is disabled if running on Java 8 onwards since the leak has been fixed for Java 8 onwards.

AWTThreadProtection

Enables protection so that calls to java.awt.Toolkit.getDefaultToolkit() triggered by a web application do not result in a memory leak. Defaults to false because an AWT thread is launched. This protection is disabled if running on Java 9 onwards since the leak has been fixed for Java 9 onwards.

classesToInitialize

List of comma-separated fully qualified class names to load and initialize during the startup of this Listener. This allows to pre-load classes that are known to provoke classloader leaks if they are loaded during a request processing. Non-JRE classes may be referenced, like oracle.jdbc.driver.OracleTimeoutThreadPerVM. The default value is empty, but specific JRE classes are loaded by other