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
|
<?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="jar-scan-filter.html">
&project;
<properties>
<title>The Jar Scan Filter Component</title>
</properties>
<body>
<section name="Table of Contents">
<toc/>
</section>
<section name="Introduction">
<p>The <strong>Jar Scan Filter</strong> element represents the component that
filters results from the <a href="jar-scanner.html">Jar Scanner</a> before
they are passed back to the application. It is typically used to skip the
scanning of JARs that are known not to be relevant to some or all types of
scan.</p>
<p>A Jar Scan Filter element MAY be nested inside a
<a href="jar-scanner.html">Jar Scanner</a> component.</p>
<p>For example you can specify additional jar files when scanning for pluggable
features:</p>
<source><![CDATA[<Context>
...
<JarScanner>
<JarScanFilter
pluggabilityScan="${tomcat.util.scan.StandardJarScanFilter.jarsToScan},
my_pluggable_feature.jar"/>
</JarScanner>
...
</Context>]]></source>
<p>If a Jar Scan Filter element is not included, a default Jar Scan Filter
configuration will be created automatically, which is sufficient for most
requirements.</p>
</section>
<section name="Attributes">
<subsection name="Common Attributes">
<p>All implementations of <strong>Jar Scan Filter</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.tomcat.JarScanFilter</code> interface.
If not specified, the standard value (defined below) will be used.</p>
</attribute>
</attributes>
</subsection>
<subsection name="Standard Implementation">
<p>The standard implementation of <strong>Jar Scan Filter</strong> is
<strong>org.apache.tomcat.util.scan.StandardJarScanFilter</strong>.
Additional attributes that it supports (in addition to the common attributes
listed above) are listed in the table.</p>
<p>The values for <strong>pluggabilitySkip</strong>,
<strong>pluggabilityScan</strong>, <strong>tldSkip</strong>,
<strong>tldScan</strong> attributes are lists of file name pattern. The
patterns are separated by comma (','). The leading and trailing whitespace
characters in a pattern are ignored. The patterns are matched
case-sensitively. The following two special characters are supported:</p>
<ul>
<li>'*' - means zero or more characters,</li>
<li>'?' - means one and only one character.</li>
</ul>
<p>Note that excluding a JAR from the pluggability scan will prevent a
ServletContainerInitializer from being loaded from a web application JAR
(i.e. one located in <code>/WEB-INF/lib</code>) but it will not prevent
a ServletContainerInitializer from being loaded from the container (Tomcat).
To prevent a ServletContainerInitializer provided by container from being
loaded, use the <code>containerSciFilter</code> property of the
<a href="context.html">Context</a>.</p>
<attributes>
<attribute name="pluggabilitySkip" required="false">
<p>The comma separated list of JAR file name patterns
to skip when scanning for pluggable features introduced by Servlet 3.0
specification. If not specified, the default is obtained from the
<code>tomcat.util.scan.StandardJarScanFilter.jarsToSkip</code> system
property.</p>
</attribute>
<attribute name="pluggabilityScan" required="false">
<p>The comma separated list of JAR file name patterns
to scan when scanning for pluggable features introduced by Servlet 3.0
specification. If not specified, the default is obtained from the
<code>tomcat.util.scan.StandardJarScanFilter.jarsToScan</code> system
property.</p>
</attribute>
<attribute name="defaultPluggabilityScan" required="false">
<p>Controls if JARs are scanned or skipped by default when scanning
for the pluggable features.
If <code>true</code>, a JAR is scanned when its name either matches
none of <strong>pluggabilitySkip</strong> patterns or
any of <strong>pluggabilityScan</strong> patterns.
If <code>false</code>, a JAR is scanned when its name matches
any of <strong>pluggabilityScan</strong> patterns and
none of <strong>pluggabilitySkip</strong> patterns.
If not specified, the default value is <code>true</code>.</p>
</attribute>
<attribute name="tldSkip" required="false">
<p>The comma separated list of JAR file name patterns
to skip when scanning for tag libraries (TLDs).
If not specified, the default is obtained
from the <code>tomcat.util.scan.StandardJarScanFilter.jarsToSkip</code>
system property.</p>
</attribute>
<attribute name="tldScan" required="false">
<p>The comma separated list of JAR file name patterns
to scan when scanning for tag libraries (TLDs).
If not specified, the default is obtained
from the <code>tomcat.util.scan.StandardJarScanFilter.jarsToScan</code>
system property.</p>
</attribute>
<attribute name="defaultTldScan" required="false">
<p>Controls if JARs are scanned or skipped by default when scanning
for TLDs.
If <code>true</code>, a JAR is scanned when its name either matches
none of <strong>tldSkip</strong> patterns or
any of <strong>tldScan</strong> patterns.
If <code>false</code>, a JAR is scanned when its name matches
any of <strong>tldScan</strong> patterns and
none of <strong>tldSkip</strong> patterns.
If not specified, the default value is <code>true</code>.</p>
</attribute>
</attributes>
</subsection>
</section>
<section name="Nested Components">
<p>No components may be nested inside a <strong>Jar Scan Filter</strong> element.
</p>
</section>
<section name="Special Features">
<p>No special features are associated with a <strong>Jar Scan Filter</strong>
element.</p>
</section>
</body>
</document>
|
