<?xml version="1.0"?>
<!DOCTYPE document [
  <!ENTITY project SYSTEM "project.xml">
]>
<document url="loader.html">

  &project;

  <properties>
    <author email="craigmcc@apache.org">Craig R. McClanahan</author>
    <title>The Loader Component</title>
  </properties>

<body>


<section name="Introduction">

  <p>The <strong>Loader</strong> element represents the <em>web
  application class loader</em> that will be used to load Java
  classes and resources for your web application.  Such
  a class loader must follow the requirements of the Servlet
  Specification, and load classes from the following locations:</p>
  <ul>
  <li>From the <code>/WEB-INF/classes</code> directory inside your
      web application.</li>
  <li>From JAR files in the <code>/WEB-INF/lib</code> directory
      inside your web application.</li>
  <li>From resources made available by Catalina to all web
      applications globally.</li>
  </ul>

  <p>A Loader element MAY be nested inside a <a href="context.html">Context</a>
  component.  If it is not included, a default Loader configuration will be
  created automatically, which is sufficient for most requirements.</p>

  <p>For a more in-depth description of the class loader hierarchy
  that is implemented by Catalina, see <strong>FIXME - Reference</strong>.</p>

    <blockquote><em>
    <p>The description below uses the variable name $CATALINA_HOME
    to refer to the directory into which you have installed Tomcat 5,
    and is the base directory against which most relative paths are
    resolved.  However, if you have configured Tomcat 5 for multiple
    instances by setting a CATALINA_BASE directory, you should use
    $CATALINA_BASE instead of $CATALINA_HOME for each of these
    references.</p>
    </em></blockquote>

</section>


<section name="Attributes">

  <subsection name="Common Attributes">

    <p>All implementations of <strong>Loader</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.catalina.Loader</code> interface.
        If not specified, the standard value (defined below) will be used.</p>
      </attribute>

      <attribute name="delegate" required="false">
        <p>Set to <code>true</code> if you want the class loader to follow
        the standard Java2 delegation model, and attempt to load classes from
        parent class loaders <strong>before</strong> looking inside the web
        application.  Set to <code>false</code> (the default) to have the
        class loader look inside the web application first, before asking
        parent class loaders to find requested classes or resources.</p>
      </attribute>

      <attribute name="reloadable" required="false">
        <p>Set to <code>true</code> if you want Catalina to monitor classes in
        <code>/WEB-INF/classes/</code> and <code>/WEB-INF/lib</code> for
        changes, and automatically reload the web application if a change
        is detected.  This feature is very useful during application
        development, but it requires significant runtime overhead and is
        not recommended for use on deployed production applications.  You
        can use the <a href="../manager-howto.html">Manager</a> web
        application, however, to trigger reloads of deployed applications
        on demand.</p>

        <p><strong>NOTE</strong> - The value for this property will be
        inherited from the <code>reloadable</code> attribute you set on
        the surrounding <a href="context.html">Context</a> component,
        and any value you explicitly set here will be replaced.</p>
      </attribute>

    </attributes>

  </subsection>


  <subsection name="Standard Implementation">

    <p>The standard implementation of <strong>Loader</strong> is
    <strong>org.apache.catalina.loader.WebappLoader</strong>.
    It supports the following additional attributes (in addition to the
    common attributes listed above):</p>

    <attributes>

      <attribute name="checkInterval" required="false">
        <p>The number of seconds between checks for modified classes and
        resources, if <code>reloadable</code> has been set to
        <code>true</code>.  The default is 15 seconds.</p>
      </attribute>

      <attribute name="debug" required="false">
        <p>The level of debugging detail logged by this <strong>Engine</strong>
        to the associated <a href="logger.html">Logger</a>.  Higher numbers
        generate more detailed output.  If not specified, the default
        debugging detail level is zero (0).</p>
      </attribute>

      <attribute name="loaderClass" required="false">
        <p>Java class name of the <code>java.lang.ClassLoader</code>
        implementation class to use.  If not specified, the default value is
        <code>org.apache.catalina.loader.WebappClassLoader</code>.</p>
      </attribute>

    </attributes>

  </subsection>


</section>


<section name="Nested Components">

  <p>No components may be nested inside a <strong>Loader</strong> element.</p>

</section>


<section name="Special Features">

  <p>No special features are associated with a <strong>Loader</strong>
  element.</p>

</section>


</body>


</document>
