<?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="jar-scanner.html">

  &project;

  <properties>
    <title>The Jar Scanner Component</title>
  </properties>

<body>

<section name="Table of Contents">
<toc/>
</section>

<section name="Introduction">

  <p>The <strong>Jar Scanner</strong> element represents the component that is
  used to scan the web application for JAR files. It is typically used during
  web application start to identify configuration files such as TLDs or
  web-fragment.xml files that must be processed as part of the web application
  initialisation.</p>

  <p>A Jar Scanner element MAY be nested inside a
  <a href="context.html">Context</a> component.  If it is not included,
  a default Jar Scanner 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 Scanner</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.JarScanner</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 Scanner</strong> is
    <strong>org.apache.tomcat.util.scan.StandardJarScanner</strong>.
    It supports the following additional attributes (in addition to the
    common attributes listed above):</p>

    <attributes>

      <attribute name="scanAllDirectories" required="false">
       <p>If true, any directories found on the classpath will be checked to see
       if are expanded Jar files. The default is <code>false</code>. Tomcat
       determines if directory is an expanded JAR file by looking for a META-INF
       sub-directory. Only if the META-INF sub-directory exists, is the
       directory to be an expanded JAR file.</p>
      </attribute>

      <attribute name="scanAllFiles" required="false">
       <p>If true, any files found on the classpath will be checked to see if
       they are Jar files rather than relying on the file extension being
       <code>.jar</code>. The default is <code>false</code></p>
      </attribute>

      <attribute name="scanClassPath" required="false">
       <p>If true, the full web application classpath, including the shared and
       common classloaders and the system classpath (but not the bootstrap
       classpath) will be scanned for Jar files in addition to the web
       application. The default is <code>true</code>. </p>
      </attribute>

      <attribute name="scanBootstrapClassPath" required="false">
       <p>If <code>scanClassPath</code> is true and this is true the bootstrap
       classpath will also be scanned for Jar files. The default is
       <code>false</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>
