<?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>'*' &#151; means zero or more characters,</li>
      <li>'?' &#151; 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>
