Start to document the Containers ClassLoader

hierarchy. Adapted terminology from Catalina as that terminology is more widely used. Punt on antlib ClassLoader structure as that is defined via library specific mechanisms git-svn-id: https://svn.apache.org/repos/asf/ant/core/trunk@271647 13f79535-47bb-0310-9956-ffa450edef68
23 years ago · f4ff4f5559
--- a/proposal/myrmidon/src/xdocs/classloader.xml
+++ b/proposal/myrmidon/src/xdocs/classloader.xml
@@ -0,0 +1,113 @@
 <?xml version="1.0"?>
 <document>

  <properties>
    <title>On ClassLoaders in Ant2</title>
    <author email="peter@apache.org">Peter Donald</author>
  </properties>

 <body>

 <section name="ClassLoader Management">

 <p>In many ways Ant2 needs to follow rules similar to a number of 
 different application servers with respect to ClassLoader management. 
 Ant2 will create a number of different ClassLoaders that have access 
 to different sets of resources (and thus Classes). The main reason
 for this arrangment is to partition different sections of the 
 application such as the Container, the Task API, task/type libraries 
 and support libraries.</p>

 <p>The recomended structure for ClassLoader relationships is a hierarchy.
 When a ClassLoader is asked for a resource (or a class) it first delegates
 to it's parent to ask for the resource. If the resource is not present in 
 its parent ClassLoader then the ClassLoader attempts to locate the resource
 in it's own store. In practice this means that all the classes (and static 
 variables defined by said classes) in a parent ClassLoader are shared with 
 the child ClassLoaders.</p>

 <p>Using kooky ascii art, the specific ClassLoader structure for Ant2 is as 
 follows:</p>

 <source>
      Bootstrap
          |
       System
          |
       Common
      /      \
 Container  Shared
             /   \
        Antlib1  Antlib2 ... 
 </source>

 <ul>
  <li>
    The <strong>Bootstrap</strong> ClassLoader contains the classes and resources 
    provided by the Java runtime.
  </li>
  <li>
    The <strong>System</strong> ClassLoader contains the classes that were made accessible 
    via the CLASSPATH environment variable. If the standard ant script was used then this 
    should only contain the classes that are used to bootstrap the ant runtime. ie 
    <code>$ANT_HOME/bin/ant-launcher.jar</code>
  </li>
  <li>
    The <strong>Common</strong> ClassLoader contains the classes and resources 
    that are made visible to both the Container and to all the ant type librarys. This 
    contains all the classes that the Container uses to communicate with tasks and other
    supporting infrastructure. In particular it contains the following APIs;
    <ul>
      <li>
        <em>Task API</em> - Contains the classes that are part of the API used
        to define tasks.
      </li>
      <li>
        <em>ProjectListener API</em> - Contains the classes necessary to define new 
        ProjectListeners.
      </li>
      <li>
        <em>Aspect API</em> - Contains the classes that are used to define Aspects 
        of the container.
      </li>
      <li>
        <em>Container API</em> - Contains the interfaces that are required to communicate
        with the objects deep within the container. <strong>NOTE</strong>: These interfaces
        are not to be used by user tasks but are made available so that certain tasks (such 
        as &lt;antcall/&gt;) can be implemented. However they are subject to change without 
        notice between between different ant2 versions.
      </li>
    </ul>
    <p>
      These classes are loaded from all the jars present in the <code>$ANT_HOME/lib</code>
      directory. 
    </p>
  </li>
  <li>
    The <strong>Container</strong> ClassLoader contains all the classes and resources
    that are part of the actual implementation of the Container. These classes are not
    directly accessible to any Ant library or task. Some of the classes are indirectly 
    accessible to tasks and other elements defined in the ant librarys as they implement 
    interfaces defined in the <strong>Common</strong> ClassLoader. The classes that are 
    stored in jars in the <code>$ANT_HOME/bin/lib/</code> directory.
  </li>
  <li>
    The <strong>Shared</strong> ClassLoader contains all the classes and resources
    that are shared across all of the ant librarys (unless they are als needed by the
    container in which case they should be placed int the <strong>Container</strong> 
    ClassLoader). This ClassLoader is populated by all the jars that are contained in
    the <code>$ANT_HOME/shared/</code> directory.
  </li>
  <li>
    The <strong>AntLib</strong> ClassLoaders each contain the classes and resources
    that required by that particular library. Note that in some cases a single Ant 
    Library will manifest as a single ClassLoader containing a single jar. However 
    in some cases it is possible for one Ant Library to have multiple jars in its 
    ClassLoader or even have multiple ClassLoaders. See XXXX for further details.
  </li>
 </ul>

 </section>

 </body>
 </document>