<?xml version="1.0"?>
<!--
  Licensed to the Apache Software Foundation (ASF) under one or more
  contributor license agreements.  See the NOTICE file distributed with
  this work for additional information regarding copyright ownership.
  The ASF licenses this file to You under the Apache License, Version 2.0
  (the "License"); you may not use this file except in compliance with
  the License.  You may obtain a copy of the License at

      http://www.apache.org/licenses/LICENSE-2.0

  Unless required by applicable law or agreed to in writing, software
  distributed under the License is distributed on an "AS IS" BASIS,
  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  See the License for the specific language governing permissions and
  limitations under the License.
-->
<!DOCTYPE document [
  <!ENTITY project SYSTEM "project.xml">
]>
<document url="listeners.html">

  &project;

  <properties>
    <title>The LifeCycle Listener Component</title>
  </properties>

<body>


<section name="Introduction">

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

  <p>Listeners may be nested inside a <a href="server.html">Server</a>, 
  <a href="engine.html">Engine</a>, <a href="host.html">Host</a> or
  <a href="context.html">Context</a>. Some Listeners are only intended to be
  nested inside specific elements. These constraints are noted in the
  documentation below.</p>

</section>

<section name="Attributes">

  <subsection name="Common Attributes">

    <p>All implementations of <strong>Listener</strong>
    support the following attributes:</p>

    <attributes>

      <attribute name="className" required="true">
        <p>Java class name of the implementation to use. This class must
        implement the <code>org.apache.catalina.LifecycleListener</code>
        interface.</p>
      </attribute>

    </attributes>

  </subsection>

  <subsection name="Standard Implementation">

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

    <h3>APR Lifecycle Listener (org.apache.catalina.core.AprLifecycleListener)</h3>

    <p>The <strong>APR Lifecycle Listener</strong> checks for the presence of
    the APR/native library and loads the library if it is present. For more
    information see the <a href="../apr.html">APR/native guide</a>.</p>

    <p>This listener must only be nested within <a href="server.html">Server</a>
    elements.</p>

    <p>The following additional attributes are supported by the <strong>APR
    Lifecycle Listener</strong>:</p>

    <attributes>

      <attribute name="SSLEngine" required="false">
        <p>Name of the SSLEngine to use. off: Do not use SSL, on: Use SSL but no
        specific ENGINE. The default value is <b>on</b>. This initializes the
        native SSL engine, which must be enabled in the APR/native connector by
        the use of the <code>SSLEnabled</code> attribute.</p>
        <p>See the <a href="http://www.openssl.org">Official OpenSSL website</a>
        for more details on supported SSL hardware engines and manufacturers.
        </p>
      </attribute>

      <attribute name="SSLRandomSeed" required="false">
        <p>Entropy source used to seed the SSLEngine's PRNG. The default value
        is <code>builtin</code>. On development systems, you may want to set
        this to <code>/dev/urandom</code> to allow quicker start times.</p>
      </attribute>

    </attributes>

    <h3>Jasper Listener (org.apache.catalina.core.JasperListener)</h3>

    <p>The <strong>Jasper Listener</strong> initializes the Jasper 2 JSP engine
    before any web applications that may use it are loaded. For more
    information on the Jasper 2 JSP engine see the
    <a href="../jasper-howto.html">Jasper How To</a>.</p>

    <p>This listener must only be nested within <a href="server.html">Server</a>
    elements.</p>

    <p>No additional attributes are supported by the <strong>Jasper Listener
    </strong>.</p>

    <h3>Server Lifecycle Listener
    (org.apache.catalina.mbeans.ServerLifecycleListener)</h3>

    <p>The <strong>Server Lifecycle Listener</strong> initializes the
    MBeanServer for the MBeans that may be used to manager Tomcat via JMX.
    Without this listener, none of the Tomcat MBeans will be available.</p>

    <p>This listener must only be nested within <a href="server.html">Server</a>
    elements.</p>

    <p>No additional attributes are supported by the <strong>Server Lifecycle
    Listener</strong>.</p>

    <h3>Global Resources Lifecycle Listener
    (org.apache.catalina.mbeans.GlobalResourcesLifecycleListener)</h3>

    <p>The <strong>Global Resources Lifecycle Listener</strong> initializes the
    Global JNDI resources defined in server.xml as part of the <a
    href="globalresources.html">Global Resources</a> element. Without this
    listener, none of the Global Resources will be available.</p>

    <p>This listener must only be nested within <a href="server.html">Server</a>
    elements.</p>

    <p>No additional attributes are supported by the <strong>Global Resources
    Lifecycle Listener</strong>.</p>

    <h3>JMX Remote Lifecycle Listener
    (org.apache.catalina.mbeans.JmxRemoteLifecycleListener)</h3>

    <p>This listener requires <code>catalina-jmx-remote.jar</code> to be placed
    in <code>$CATALINA_HOME/lib</code>. This jar may be found in the extras
    directory of the binary download area.</p>

    <p>The <strong>JMX Remote Lifecycle Listener</strong> fixes the ports used by
    the JMX/RMI Server making things much simpler if you need to connect
    jconsole or a similar tool to a remote Tomcat instance that is running
    behind a firewall. Only these ports are configured via the listener. The
    remainder of the configuration is via the standard system properties for
    configuring JMX. For further information on configuring JMX see
    <a href="http://java.sun.com/javase/6/docs/technotes/guides/management/agent.html">
    Monitoring and Management Using JMX</a> included with the Java SDK
    documentation.</p>

    <p>If this listener was configured in server.xml as:
<source>
&lt;Listener className="org.apache.catalina.mbeans.JmxRemoteLifecycleListener"
          rmiRegistryPortPlatform="10001" rmiServerPortPlatform="10002" /&gt;
</source>
    with the following system properties set (e.g. in setenv.sh):
<source>
-Dcom.sun.management.jmxremote.password.file=$CATALINA_BASE/conf/jmxremote.password
-Dcom.sun.management.jmxremote.access.file=$CATALINA_BASE/conf/jmxremote.access
-Dcom.sun.management.jmxremote.ssl=false
</source>
    $CATALINA_BASE/conf/jmxremote.password containing:
<source>
admin letmein
</source>
    $CATALINA_BASE/conf/jmxremote.access containing:
<source>
admin readwrite
</source>
    then opening ports 10001 (RMI Registry) and 10002 (JMX/RMI Server) in your
    firewall would enable jconsole to connect to a Tomcat instance running
    behind a firewall using a connection string of the form:
<source>
service:jmx:rmi://&lt;hostname&gt;:10002/jndi/rmi://&lt;hostname&gt;:10001/jmxrmi
</source>
    with a user name of <code>admin</code> and a password of
    <code>letmein</code>.
    </p>
    
    <p><strong>Note that the example above does not use SSL. JMX access should
    be considered equivalent to administrative access and secured accordingly.
    </strong></p>

    <p>This listener must only be nested within a <a href="server.html">Server</a>
    element.</p>

    <p>The following additional attributes are supported by the <strong>JMX Remote
    Lifecycle Listener</strong>:</p>

    <attributes>

      <attribute name="rmiRegistryPortPlatform" required="true">
        <p>The port to be used by the JMX/RMI registry for the Platform MBeans.
        The replaces the use of the
        <code>com.sun.management.jmxremote.port</code> system property that
        should not be set when using this valve.</p>
      </attribute>

      <attribute name="rmiServerPortPlatform" required="true">
        <p>The port to be used by the Platform JMX/RMI server.</p>
      </attribute>

      <attribute name="useLocalPorts" required="false">
        <p>Should any clients using these ports be forced to use local ports to
        connect to the the JMX/RMI server. This is useful when tunnelling
        connections over SSH or similar. Defaults to <code>false</code>.</p>
      </attribute>

    </attributes>

    <h3>JRE Memory Leak Prevention Listener
        (org.apache.catalina.core.JreMemoryLeakPreventionListener)</h3>

    <p>The <strong>JRE Memory Leak Prevention Listener</strong> 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.</p>
    
    <p>This listener must only be nested within <a href="server.html">Server</a>
    elements.</p>

    <p>The following additional attributes are supported by the <strong>JRE
    Memory Leak Prevention Listener</strong>:</p>

    <attributes>

      <attribute name="appContextProtection" required="false">
        <p>Enables protection so that calls to
        <code>sun.awt.AppContext.getAppContext()</code> triggered by a web
        application do not result in a memory leak. Note that a call to this
        method will be triggered as part of the web application stop process so
        it is strongly recommended that this protection is enabled. The default
        is <code>true</code></p>
      </attribute>

      <attribute name="gcDaemonProtection" required="false">
        <p>Enables protection so that calls to
        <code>sun.misc.GC.requestLatency(long)</code> triggered by a web
        application do not result in a memory leak. Use of RMI is likely to
        trigger a call to this method. A side effect of enabling this protection
        is the creation of a thread named "GC Daemon". The protection is uses
        reflection to access internal Sun classes and may generate errors on
        startup on non-Sun JVMs. The default is <code>true</code>.</p>
      </attribute>

      <attribute name="urlCacheProtection" required="false">
        <p>Enables protection so that reading resources from JAR files using
        <code>java.net.URLConnection</code>s does not result in the JAR file
        being locked. Note that enabling this protection disables caching by
        default for all resources obtained via
        <code>java.net.URLConnection</code>s. Caching may be re-enabled on a
        case by case basis as required. Defaults to <code>true</code>.</p>
      </attribute>

      <attribute name="xmlParsingProtection" required="false">
        <p>Enables protection so that parsing XML files within a web application
        does not result in a memory leak. Note that memory profilers may not
        display the GC root associated with this leak making it particularly
        hard to diagnose. Defaults to <code>true</code>.</p>
      </attribute>

    </attributes>

  </subsection>

</section>

<section name="Nested Components">

  <p>No element may be nested inside a <strong>Listener</strong>.</p>

</section>

</body>

</document>
