<?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 entries 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>