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
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
|
<?xml version="1.0" encoding="UTF-8"?>
<!--
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="manager.html">
&project;
<properties>
<title>The Manager Component</title>
</properties>
<body>
<section name="Table of Contents">
<toc/>
</section>
<section name="Introduction">
<p>The <strong>Manager</strong> element represents the <em>session
manager</em> that will be used to create and maintain HTTP sessions
as requested by the associated web application.</p>
<p>A Manager element MAY be nested inside a
<a href="context.html">Context</a> component. If it is not included,
a default Manager configuration will be created automatically, which
is sufficient for most requirements, — see
<em>Standard Manager Implementation</em> below for the details
of this configuration.</p>
</section>
<section name="Attributes">
<subsection name="Common Attributes">
<p>All implementations of <strong>Manager</strong>
support the following attributes:</p>
<attributes>
<attribute name="className" required="false">
<p>Java class name of the implementation to use. This class must
implement the <code>org.apache.catalina.Manager</code> interface.
If not specified, the standard value (defined below) will be used.</p>
</attribute>
<attribute name="maxActiveSessions" required="false">
<p>The maximum number of active sessions that will be created by
this Manager, or <code>-1</code> (the default) for no limit.</p>
<p>When the limit is reached, any attempt to create a new session
(e.g. with <code>HttpServletRequest.getSession()</code> call)
will fail with an <code>IllegalStateException</code>.</p>
</attribute>
<attribute name="notifyAttributeListenerOnUnchangedValue" required="false">
<p>If an attribute is added to the session and that attribute is already
present in the session under the same name will any
<code>HttpSessionAttributeListener</code> be notified that the attribute
has been replaced. If not specified, the default value of
<code>true</code> will be used.</p>
</attribute>
<attribute name="notifyBindingListenerOnUnchangedValue" required="false">
<p>If an attribute is added to the session, that attribute is already
present in the session under the same name and the attribute implements
<code>HttpSessionBindingListener</code>, will the listener be notified
that the attribute has been unbound and bound again. If not specified,
the default value of <code>false</code> will be used.</p>
</attribute>
<attribute name="sessionActivityCheck" required="false">
<p>If this is <code>true</code>, Tomcat will track the number of active
requests for each session. When determining if a session is valid, any
session with at least one active request will always be considered valid.</p>
<p>If <code>org.apache.catalina.STRICT_SERVLET_COMPLIANCE</code> is set to
<code>true</code>, the default of this setting will be <code>true</code>,
else the default value will be <code>false</code>.</p>
</attribute>
<attribute name="sessionLastAccessAtStart" required="false">
<p>If this is <code>true</code>, the last accessed time for sessions will
be calculated from the beginning of the previous request. If
<code>false</code>, the last accessed time for sessions will be calculated
from the end of the previous request. This also affects how the idle time
is calculated.</p>
<p>If <code>org.apache.catalina.STRICT_SERVLET_COMPLIANCE</code> is set to
<code>true</code>, the default of this setting will be <code>true</code>,
else the default value will be <code>false</code>.</p>
</attribute>
</attributes>
</subsection>
<subsection name="Standard Implementation">
<p>Tomcat provides two standard implementations of <strong>Manager</strong>
for use — the default one stores active sessions, while the optional one
stores active sessions that have been swapped out (in addition to saving
sessions across a restart of Tomcat) in a storage location that is selected
via the use of an appropriate <strong>Store</strong> nested element.</p>
<h3>Standard Manager Implementation</h3>
<p>The standard implementation of <strong>Manager</strong> is
<strong>org.apache.catalina.session.StandardManager</strong>.
It supports the following additional attributes (in addition to the
common attributes listed above):</p>
<attributes>
<attribute name="pathname" required="false">
<p>Absolute or relative (to the work directory for this Context)
pathname of the file in which session state will be preserved
across application restarts, if possible. The default is
null.<br />See
<a href="#Persistence_Across_Restarts">Persistence Across Restarts</a>
for more information. This persistence may be
enabled by setting this attribute to a non empty string.</p>
</attribute>
<attribute name="persistAuthentication" required="false">
<p>Should authentication information be included when session state is
preserved across application restarts? If <code>true</code>, the session's
authentication is preserved so that the session remains authenticated
after the application has been restarted. If not specified, the default
value of <code>false</code> will be used.<br />See
<a href="#Persistence_Across_Restarts">Persistence Across Restarts</a>
for more information.</p>
<p>Please note that the session's <code>Principal</code> class as well
as its descendant classes are all subject to the
<strong>sessionAttributeValueClassNameFilter</strong>. If such a filter
is specified the names of the <code>Principal</code> class and
descendant classes must match that filter pattern in order to be
restored.</p>
</attribute>
<attribute name="processExpiresFrequency" required="false">
<p>Frequency of the session expiration, and related manager operations.
Manager operations will be done once for the specified amount of
backgroundProcess calls (i.e., the lower the amount, the more often the
checks will occur). The minimum value is 1, and the default value is 6.
</p>
</attribute>
<attribute name="secureRandomClass" required="false">
<p>Name of the Java class that extends
<code>java.security.SecureRandom</code> to use to generate session IDs.
If not specified, the default value is
<code>java.security.SecureRandom</code>.</p>
</attribute>
<attribute name="secureRandomProvider" required="false">
<p>Name of the provider to use to create the
<code>java.security.SecureRandom</code> instances that generate session
IDs. If an invalid algorithm and/or provider is specified, the Manager
will use the platform default provider and the default algorithm. If not
specified, the platform default provider will be used.</p>
</attribute>
<attribute name="secureRandomAlgorithm" required="false">
<p>Name of the algorithm to use to create the
<code>java.security.SecureRandom</code> instances that generate session
IDs. If an invalid algorithm and/or provider is specified, the Manager
will use the platform default provider and the default algorithm. If not
specified, the default algorithm of SHA1PRNG will be used. If the
default algorithm is not supported, the platform default will be used.
To specify that the platform default should be used, do not set the
secureRandomProvider attribute and set this attribute to the empty
string.</p>
</attribute>
<attribute name="sessionAttributeNameFilter" required="false">
<p>A regular expression used to filter which session attributes will be
serialized for clustering/replication, or storage to any persistent store.
An attribute will only be serialized if its name matches
this pattern. If the pattern is zero length or <code>null</code>, all
attributes are eligible for distribution. The pattern is anchored so the
session attribute name must fully match the pattern. As an example, the
value <code>(userName|sessionHistory)</code> will only distribute the
two session attributes named <code>userName</code> and
<code>sessionHistory</code>. If not specified, the default value of
<code>null</code> will be used.</p>
</attribute>
<attribute name="sessionAttributeValueClassNameFilter" required="false">
<p>A regular expression used to filter which session attributes will be
serialized for clustering/replication, or storage to any persistent store.
An attribute will only be serialized if the implementation
class name of the value matches this pattern. If the pattern is zero
length or <code>null</code>, all attributes are eligible for
distribution. The pattern is anchored so the fully qualified class name
must fully match the pattern. If not specified, the default value of
<code>null</code> will be used.</p>
</attribute>
<attribute name="warnOnSessionAttributeFilterFailure" required="false">
<p>If <strong>sessionAttributeNameFilter</strong> or
<strong>sessionAttributeValueClassNameFilter</strong> blocks an
attribute, should this be logged at <code>WARN</code> level? If
<code>WARN</code> level logging is disabled then it will be logged at
<code>DEBUG</code>. The default value of this attribute is
<code>false</code>.</p>
</attribute>
</attributes>
<h3>Persistent Manager Implementation</h3>
<p><strong>NOTE:</strong> You must set either the
<code>org.apache.catalina.session.StandardSession.ACTIVITY_CHECK</code> or
<code>org.apache.catalina.STRICT_SERVLET_COMPLIANCE</code>
<a href="systemprops.html">system properties</a> to <code>true</code> for
the persistent manager to work correctly.</p>
<p>The persistent implementation of <strong>Manager</strong> is
<strong>org.apache.catalina.session.PersistentManager</strong>. In
addition to the usual operations of creating and deleting sessions, a
<code>PersistentManager</code> has the capability to swap active (but
idle) sessions out to a persistent storage mechanism, as well as to save
all sessions across a normal restart of Tomcat. The actual persistent
storage mechanism used is selected by your choice of a
<strong>Store</strong> element nested inside the <strong>Manager</strong>
element - this is required for use of <code>PersistentManager</code>.</p>
<p>This implementation of Manager supports the following attributes in
addition to the <a href="#Common_Attributes">Common Attributes</a>
described earlier.</p>
<attributes>
<attribute name="className" required="true">
<p>It has the same meaning as described in the
<a href="#Common_Attributes">Common Attributes</a> above.
You <strong>must</strong> specify
<code>org.apache.catalina.session.PersistentManager</code> to use
this manager implementation.</p>
</attribute>
<attribute name="maxIdleBackup" required="false">
<p>The time interval (in seconds) since the last access to a session
before it is eligible for being persisted to the session store, or
<code>-1</code> to disable this feature. By default, this feature is
disabled.</p>
</attribute>
<attribute name="maxIdleSwap" required="false">
<p>The maximum time a session may be idle before it is eligible to be
swapped to disk due to inactivity. Setting this to <code>-1</code> means
sessions should not be swapped out just because of inactivity. If this
feature is enabled, the time interval specified here should be equal to
or longer than the value specified for <code>maxIdleBackup</code>. By
default, this feature is disabled.</p>
</attribute>
<attribute name="minIdleSwap" required="false">
<p>The minimum time in seconds a session must be idle before it is
eligible to be swapped to disk to keep the active session count below
maxActiveSessions. Setting to <code>-1</code> means sessions will not be
swapped out to keep the active session count down. If specified, this
value should be less than that specified by <code>maxIdleSwap</code>.
By default, this value is set to <code>-1</code>.</p>
</attribute>
<attribute name="persistAuthentication" required="false">
<p>Should authentication information be included when sessions are
swapped out to persistent storage? If <code>true</code>, the session's
authentication is preserved so that the session remains authenticated
after being reloaded (swapped in) from persistent storage. If not
specified, the default value of <code>false</code> will be used.</p>
<p>Please note that the session's <code>Principal</code> class as well
as its descendant classes are all subject to the
<strong>sessionAttributeValueClassNameFilter</strong>. If such a filter
is specified the names of the <code>Principal</code> class and
descendant classes must match that filter pattern in order to be
restored.</p>
</attribute>
<attribute name="processExpiresFrequency" required="false">
<p>It is the same as described above for the
<code>org.apache.catalina.session.StandardManager</code> class.
</p>
</attribute>
<attribute name="saveOnRestart" required="false">
<p>Should all sessions be persisted and reloaded when Tomcat is shut
down and restarted (or when this application is reloaded)? By default,
this attribute is set to <code>true</code>.</p>
</attribute>
<attribute name="secureRandomClass" required="false">
<p>It is the same as described above for the
<code>org.apache.catalina.session.StandardManager</code> class.
</p>
</attribute>
<attribute name="secureRandomProvider" required="false">
<p>It is the same as described above for the
<code>org.apache.catalina.session.StandardManager</code> class.
</p>
</attribute>
<attribute name="secureRandomAlgorithm" required="false">
<p>It is the same as described above for the
<code>org.apache.catalina.session.StandardManager</code> class.
</p>
</attribute>
<attribute name="sessionAttributeNameFilter" required="false">
<p>A regular expression used to filter which session attributes will be
serialized for clustering/replication, or storage to any persistent store.
An attribute will only be serialized if its name matches
this pattern. If the pattern is zero length or <code>null</code>, all
attributes are eligible for distribution. The pattern is anchored so the
session attribute name must fully match the pattern. As an example, the
value <code>(userName|sessionHistory)</code> will only distribute the
two session attributes named <code>userName</code> and
<code>sessionHistory</code>. If not specified, the default value of
<code>null</code> will be used.</p>
</attribute>
<attribute name="sessionAttributeValueClassNameFilter" required="false">
<p>A regular expression used to filter which session attributes will be
serialized for clustering/replication, or storage to any persistent store.
An attribute will only be serialized if the implementation
class name of the value matches this pattern. If the pattern is zero
length or <code>null</code>, all attributes are eligible for
distribution. The pattern is anchored so the fully qualified class name
must fully match the pattern. If not specified, the default value of
<code>null</code> will be used.</p>
</attribute>
<attribute name="warnOnSessionAttributeFilterFailure" required="false">
<p>If <strong>sessionAttributeNameFilter</strong> or
<strong>sessionAttributeValueClassNameFilter</strong> blocks an
attribute, should this be logged at <code>WARN</code> level? If
<code>WARN</code> level logging is disabled then it will be logged at
<code>DEBUG</code>. The default value of this attribute is
<code>false</code>.</p>
</attribute>
</attributes>
<p>In order to successfully use a PersistentManager, you must nest inside
it a <strong><Store></strong> element, as described below.</p>
</subsection>
</section>
<section name="Nested Components">
<h3>All Manager Implementations</h3>
<p>All Manager implementations allow nesting of a
<strong><SessionIdGenerator></strong> element. It defines
the behavior of session id generation. All implementations
of the <a href="sessionidgenerator.html">SessionIdGenerator</a> allow the
following attributes:
</p>
<attributes>
<attribute name="sessionIdLength" required="false">
<p>The length of the session ID may be changed with the
<strong>sessionIdLength</strong> attribute.
</p>
</attribute>
</attributes>
<h3>Persistent Manager Implementation</h3>
<p>If you are using the <em>Persistent Manager Implementation</em>
as described above, you <strong>MUST</strong> nest a
<strong><Store></strong> element inside, which defines the
characteristics of the persistent data storage. Two implementations
of the <code><Store></code> element are currently available,
with different characteristics, as described below.</p>
<h5>File Based Store</h5>
<p>The <em>File Based Store</em> implementation saves swapped out
sessions in individual files (named based on the session identifier)
in a configurable directory. Therefore, you are likely to encounter
scalability problems as the number of active sessions increases, and
this should primarily be considered a means to easily experiment.</p>
<p>To configure this, add a <code><Store></code> nested inside
your <code><Manager></code> element with 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.Store</code> interface. You
<strong>must</strong> specify
<code>org.apache.catalina.session.FileStore</code>
to use this implementation.</p>
</attribute>
<attribute name="directory" required="false">
<p>Absolute or relative (to the temporary work directory for this web
application) pathname of the directory into which individual session
files are written. If not specified, the temporary work directory
assigned by the container is utilized.</p>
</attribute>
</attributes>
<h5>Data source Based Store</h5>
<p>The <em>Data source Based Store</em> implementation saves swapped out
sessions in individual rows of a preconfigured table in a database
that is accessed via a data sourcer. With large numbers of swapped out
sessions, this implementation will exhibit improved performance over
the File Based Store described above.</p>
<p>To configure this, add a <code><Store></code> nested inside
your <code><Manager></code> element with 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.Store</code> interface. You
<strong>must</strong> specify
<code>org.apache.catalina.session.DataSourceStore</code>
to use this implementation.</p>
</attribute>
<attribute name="dataSourceName" required="false">
<p>Name of the JNDI resource for a JDBC DataSource-factory. Since this
code uses prepared statements, you might want to configure pooled
prepared statements as shown in
<a href="../jndi-resources-howto.html">the JNDI resources
How-To</a>.</p>
</attribute>
<attribute name="localDataSource" required="false">
<p>This allows the Store to use a DataSource defined for the Context
rather than a global DataSource. If not specified, the default is
<code>false</code>: use a global DataSource.</p>
</attribute>
<attribute name="sessionAppCol" required="false">
<p>Name of the database column, contained in the specified session table,
that contains the Engine, Host, and Web Application Context name in the
format <code>/Engine/Host/Context</code>. If not specified the default
value of <code>app</code> will be used.</p>
</attribute>
<attribute name="sessionDataCol" required="false">
<p>Name of the database column, contained in the specified session table,
that contains the serialized form of all session attributes for a swapped
out session. The column type must accept a binary object (typically called
a BLOB). If not specified the default value of <code>data</code> will be
used.</p>
</attribute>
<attribute name="sessionIdCol" required="false">
<p>Name of the database column, contained in the specified session table,
that contains the session identifier of the swapped out session. The
column type must accept character string data of at least as many
characters as are contained in session identifiers created by Tomcat
(typically 32). If not specified the default value of <code>id</code> will
be used.</p>
</attribute>
<attribute name="sessionLastAccessedCol" required="false">
<p>Name of the database column, contained in the specified session table,
that contains the <code>lastAccessedTime</code> property of this session.
The column type must accept a Java <code>long</code> (64 bits). If not
specified the default value of <code>maxinactive</code> will be used.</p>
</attribute>
<attribute name="sessionMaxInactiveCol" required="false">
<p>Name of the database column, contained in the specified session table,
that contains the <code>maxInactiveInterval</code> property of this
session. The column type must accept a Java <code>integer</code> (32
bits). If not specified, the default value of <code>maxinactive</code>
will be used.</p>
</attribute>
<attribute name="sessionTable" required="false">
<p>Name of the database table to be used for storing swapped out sessions.
This table must contain (at least) the database columns that are
configured by the other attributes of this element. If not specified the
default value of <code>tomcat$sessions</code> will be used.</p>
</attribute>
<attribute name="sessionValidCol" required="false">
<p>Name of the database column, contained in the specified session table,
that contains a flag indicating whether this swapped out session is still
valid or not. The column type must accept a single character. If not
specified the default value of <code>valid</code> will be used.</p>
</attribute>
</attributes>
<p>Before attempting to use the data source Store for the first time,
you must create the table that will be used to store swapped out sessions.
Detailed SQL commands vary depending on the database you are using, but
a script like this will generally be required:</p>
<source>create table tomcat_sessions (
session_id varchar(100) not null primary key,
valid_session char(1) not null,
max_inactive int not null,
last_access bigint not null,
app_name varchar(255),
session_data mediumblob,
KEY kapp_name(app_name)
);</source>
<p>Note: The SQL command above does not use the default names for either the
table or the columns so the data source Store would need to be configured
to reflect this.</p>
</section>
<section name="Special Features">
<subsection name="Persistence Across Restarts">
<p>Whenever Apache Tomcat is shut down normally and restarted, or when an
application reload is triggered, the standard Manager implementation
will attempt to serialize all currently active sessions to a disk
file located via the <code>pathname</code> attribute. All such saved
sessions will then be deserialized and activated (assuming they have
not expired in the mean time) when the application reload is completed.</p>
<p>In order to successfully restore the state of session attributes,
all such attributes MUST implement the <code>java.io.Serializable</code>
interface. You MAY cause the Manager to enforce this restriction by
including the <code><distributable></code> element in your web
application deployment descriptor (<code>/WEB-INF/web.xml</code>).</p>
<p>Note that, if <strong>persistAuthentication</strong> is also set to
<code>true</code>, the <code>Principal</code> class present in the session
MUST also implement the <code>java.io.Serializable</code> interface in order
to make authentication persistence work properly. The actual type of that
<code>Principal</code> class is determined by the <a href="realm.html">
Realm</a> implementation used with the application. Tomcat's standard
<code>Principal</code> class instantiated by most of the Realms (except
<code>JAASRealm</code>) implements <code>java.io.Serializable</code>.</p>
<p>The persistence across restarts provided by the
<strong>StandardManager</strong> is a simpler implementation than that
provided by the <strong>PersistentManager</strong>. If robust, production
quality persistence across restarts is required then the
<strong>PersistentManager</strong> should be used with an appropriate
configuration.</p>
</subsection>
<subsection name="Enable Session Persistence">
<p>As documented above, every web application by default has
standard manager implementation configured, which can perform session
persistence across restarts. To enable this persistence feature, create
a <a href="context.html">Context</a> configuration file for your web
application and add the following element there (in this example,
it will save sessions to files named <code>SESSIONS.ser</code>):</p>
<source><![CDATA[<Manager pathname="SESSIONS.ser" />]]></source>
</subsection>
</section>
</body>
</document>
|
