<?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-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 and directories of class 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.</p>

  <p>For example you can include the bootstrap classpath when scanning for jar
  files:</p>
<source><![CDATA[<Context>
  ...
  <JarScanner scanBootstrapClassPath="true"/>
  ...
</Context>]]></source>

  <p>If a Jar Scanner element 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 <code>true</code>, any directories found on the classpath will be
       checked to see if they are expanded JAR files.
       The default is <code>false</code>.</p>
       <p>Tomcat determines if a directory is an expanded JAR file by looking
       for a META-INF sub-directory. Only if the META-INF sub-directory exists,
       the directory is assumed to be an expanded JAR file. Note that for scans
       for matches to <code>@HandlesTypes</code> annotations, all directories
       will be scanned irrespective of the presence or not of a META-INF
       sub-directory.</p>
      </attribute>

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

      <attribute name="scanManifest" required="false">
       <p>If <code>true</code>, the Manifest files of any JARs found will be
       scanned for additional class path entires and those entries will be added
       to the URLs to scan. The default is <code>true</code>.</p>
      </attribute>

    </attributes>

  </subsection>


</section>


<section name="Nested Components">
  <p>Only a <a href="jar-scan-filter.html">Jar Scan Filter</a> 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>
