1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
|
<?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="Table of Contents">
<toc/>
</section>
<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>
</section>
<section name="Nested Components">
<p>No element may be nested inside a <strong>Listener</strong>.</p>
</section>
<section 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>
<subsection name="APR Lifecycle Listener - org.apache.catalina.core.AprLifecycleListener">
<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. <code>off</code>: do not use SSL,
<code>on</code>: use SSL but no specific ENGINE.</p>
<p>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>
<attribute name="FIPSMode" required="false">
<p>Set to <code>on</code> to request that OpenSSL be in FIPS mode
(if OpenSSL is already in FIPS mode, it will remain in FIPS mode).
Set to <code>enter</code> to force OpenSSL to enter FIPS mode (an error
will occur if OpenSSL is already in FIPS mode).
Set to <code>require</code> to require that OpenSSL <i>already</i> be
in FIPS mode (an error will occur if OpenSSL is not already in FIPS
mode).</p>
<p>FIPS mode <em>requires you to have a FIPS-capable OpenSSL library which
you must build yourself</em>.
If this attribute is set to any of the above values, the <b>SSLEngine</b>
must be enabled as well.</p>
<p>The default value is <code>off</code>.</p>
</attribute>
</attributes>
</subsection>
<subsection name="Jasper Listener - org.apache.catalina.core.JasperListener">
<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>
</subsection>
<subsection name="Server Lifecycle Listener - org.apache.catalina.mbeans.ServerLifecycleListener">
<p>The <strong>Server Lifecycle Listener</strong> initializes the
MBeanServer for the MBeans that may be used to manage 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>
</subsection>
<subsection name="Global Resources Lifecycle Listener - org.apache.catalina.mbeans.GlobalResourcesLifecycleListener">
<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>
</subsection>
<subsection name="JMX Remote Lifecycle Listener - org.apache.catalina.mbeans.JmxRemoteLifecycleListener">
<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://docs.oracle.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>
<Listener className="org.apache.catalina.mbeans.JmxRemoteLifecycleListener"
rmiRegistryPortPlatform="10001" rmiServerPortPlatform="10002" />
</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://<hostname>:10002/jndi/rmi://<hostname>: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>
</subsection>
<subsection name="JRE Memory Leak Prevention Listener - org.apache.catalina.core.JreMemoryLeakPreventionListener">
<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="AWTThreadProtection" required="false">
<p>Enables protection so that calls to
<code>java.awt.Toolkit.getDefaultToolkit()</code> triggered by a web
application do not result in a memory leak.
Defaults to <code>false</code> because an AWT thread is launched.</p>
</attribute>
<attribute name="classesToInitialize" required="false">
<p>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
<code>oracle.jdbc.driver.OracleTimeoutThreadPerVM</code>.
The default value is empty, but specific JRE classes are loaded by other leak
protection features managed by other attributes of this Listener.</p>
</attribute>
<attribute name="driverManagerProtection" required="false">
<p>The first use of <code>java.sql.DriverManager</code> will trigger the
loading of JDBC Driver in the the current class loader. The web
application level memory leak protection can take care of this in most
cases but triggering the loading here has fewer side-effects. 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 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="ldapPoolProtection" required="false">
<p>Enables protection so that the PoolCleaner thread started by
<code>com.sun.jndi.ldap.LdapPoolManager</code> does not result in a
memory leak. The thread is started the first time the
<code>LdapPoolManager</code> class is used if the system property
<code>com.sun.jndi.ldap.connect.pool.timeout</code> is set to a value
greater than 0. Without this protection, if a web application uses this
class the PoolCleaner thread will be configured with the thread's
context class loader set to the web application class loader which in
turn will trigger a memory leak on reload. Defaults to
<code>true</code>.</p>
</attribute>
<attribute name="securityLoginConfigurationProtection" required="false">
<p>Enables protection so that usage of the
<code>javax.security.auth.login.Configuration</code> class by a web
application does not provoke a memory leak. The first access of this
class will trigger the initializer that will retain a static reference
to the context class loader. The protection loads the class with the
system class loader to ensure that the static initializer is not
triggered by a web application. Defaults to <code>true</code>.</p>
</attribute>
<attribute name="securityPolicyProtection" required="false">
<p>Enables protection so that usage of the deprecated
<code>javax.security.auth.Policy</code> class by a web application does not
result in a memory leak. The first access of this class will trigger the
static initializer that will retain a static reference to the context
class loader. The protection calls the <code>getPolicy()</code> method
of this class to ensure that the static initializer is not triggered by
a web application. Defaults to <code>true</code>.</p>
</attribute>
<attribute name="tokenPollerProtection" required="false">
<p>Enables protection so that any token poller thread initialized by
<code>sun.security.pkcs11.SunPKCS11.initToken()</code> does not
result in a memory leak. The thread is started depending on various
conditions as part of the initialization of the Java Cryptography
Architecture. Without the protection this can happen during Webapp
deployment when the MessageDigest for generating session IDs is
initialized. As a result the thread has the Webapp class loader as its
thread context class loader. Enabling the protection initializes JCA
early during Tomcat startup. Defaults to <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>
<subsection name="UserConfig - org.apache.catalina.startup.UserConfig">
<p>The <strong>UserConfig</strong> provides feature of User Web Applications.
User Web Applications map a request URI starting with a tilde character ("~")
and a username to a directory (commonly named public_html) in that user's
home directory on the server.</p>
<p>See the <a href="host.html#User_Web_Applications">User Web Applications</a>
special feature on the <strong>Host</strong> element for more information.</p>
<p>The following additional attributes are supported by the
<strong>UserConfig</strong>:</p>
<attributes>
<attribute name="directoryName" required="false">
<p>The directory name to be searched for within each user home directory.
The default is <code>public_html</code>.</p>
</attribute>
<attribute name="userClass" required="false">
<p>The class name of the user database class.
There are currently two user database, the
<code>org.apache.catalina.startup.PasswdUserDatabase</code> is used on a
Unix system that uses the /etc/passwd file to identify valid users.
The <code>org.apache.catalina.startup.HomesUserDatabase</code> is used on
a server where /etc/passwd is not in use. HomesUserDatabase deploy all
directories found in a specified base directory.</p>
</attribute>
<attribute name="homeBase" required="false">
<p>The base directory containing user home directories.This is effective
only when <code>org.apache.catalina.startup.HomesUserDatabase</code> is
used.</p>
</attribute>
</attributes>
</subsection>
</section>
</body>
</document>
|