webapps/docs/config/jar-scan-filter.xml - tomcat80 - Git at Google

 <?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 Scanner</strong> element.
   </p>
 </section>


 <section name="Special Features">
   <p>No special features are associated with a <strong>Jar Scanner</strong>
   element.</p>
 </section>

 </body>

 </document>
	<?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 Scanner</strong> element.
	</p>
	</section>


	<section name="Special Features">
	<p>No special features are associated with a <strong>Jar Scanner</strong>
	element.</p>
	</section>

	</body>

	</document>