youys
/
ant

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">

<!-- Content Stylesheet for Site -->

    
<!-- start the processing -->
    <html>
    <head>
      <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"/>
  
                      <meta name="author" value="Peter Donald">
  <meta name="email" value="peter@apache.org">
        
      <title>Apache Myrmidon - On Libraries in Ant 2</title>
    </head>
  
    <body bgcolor="#ffffff" text="#000000" link="#525D76">    
      <table border="0" width="100%" cellspacing="0">
        <!-- TOP IMAGE -->
        <tr>
          <td>      <td colspan="2">
    <a href="http://jakarta.apache.org"><img src="http://jakarta.apache.org/images/jakarta-logo.gif" align="left" border="0"/></a>
    </td>
  </td>
          <td valign="bottom"><div align="right"><b><font size="+3" color="#525D76">Apache Myrmidon</font></b></div></td>
        </tr>
      </table>
      <table border="0" width="100%" cellspacing="4">
        <tr><td colspan="2">
          <hr noshade="" size="1"/>
        </td></tr>
        
        <tr>
          <!-- LEFT SIDE NAVIGATION -->
          <td valign="top" nowrap="true">
                <p><strong>Myrmidon</strong></p>
    <ul>
          <li>      <a href="./index.html">Introduction</a>
  </li>
          <li>      <a href="./getinvolved.html">Get Involved</a>
  </li>
          <li>      <a href="./user.html">Building Myrmidon</a>
  </li>
          <li>      <a href="./todo.html">Todo List</a>
  </li>
        </ul>
      <p><strong>User Guide</strong></p>
    <ul>
          <li>      <a href="./buildfile.html">Project File</a>
  </li>
          <li>      <a href="./vfs.html">Virtual File System</a>
  </li>
          <li>      <a href="./ant1compat.html">Ant 1 Compatibility Layer</a>
  </li>
          <li>      <a href="./differences.html">Differences to Ant 1</a>
  </li>
          <li>      <a href="./task.html">My First Task</a>
  </li>
        </ul>
      <p><strong>Extending Ant</strong></p>
    <ul>
          <li>      <a href="./configuring.html">Configuration HOWTO</a>
  </li>
          <li>      <a href="./converter.html">Converter HOWTO</a>
  </li>
          <li>      <a href="./type.html">Type HOWTO</a>
  </li>
          <li>      <a href="./classloader.html">ClassLoader HOWTO</a>
  </li>
          <li>      <a href="./librarys.html">Library HOWTO</a>
  </li>
        </ul>
      <p><strong>Container Design</strong></p>
    <ul>
        </ul>
            </td>
          <td align="left" valign="top">
        <table border="0" cellspacing="0" cellpadding="2" width="100%">
    <tr><td bgcolor="#525D76">
      <font color="#ffffff" face="arial,helvetica,sanserif">
                    <a name="Library Management"><strong>Library Management</strong></a>
      </font>
    </td></tr>
    <tr><td>
      <blockquote>
                        <p>Long ago there was identified the need for libraries that contain
            tasks and other elements present in the build file. This document
            attempts to describe the mechanism via which these libraries will be
            defined and used in Ant 2. The libraries (also referred to as
            deployments) will be termed antlibs.</p>
                                <p>Ant libraries can be packaged and signed into a ANt Type Library
            format (.atl) using the standard Java Archive tools. (For details on
            the .jar file format see the

                <a href="http://java.sun.com/j2se/1.3/docs/guide/jar/index.html">
                           Jar Specification</a>.
            </p>
                                <p>When packaged into such a form the META-INF/ directory contains
            ant specific descriptors in addition to the standard Jar manifest
            and other descriptor files. The archive will also contain the

                <code>.class</code> files for all the tasks and other types the
            library defines. It may also contain additional resources that can
            be referenced in the build file (an example being DTDs).
            </p>
                                <p>The library may also need access to other libraries or resources
            to perform its job. For instance, if the task loaded an XML document
            and then processed said document using the
                <em>Trax API</em> then
            the Ant library needs to have access to the
                <em>Trax API</em> and an
            implementation of the API. The Antlib mechanism thus uses the standard
            "Optional Package" Specification to declare dependencies on other
            libraries.
            </p>
                                <p>The libraries will usually be installed in standard locations that
            make it possible for the Ant container to automatically locate and scan
            the libraries. It will also be possible for the users to specify
            additional search locations or even the specific location of ant
            libraries.</p>
                                <p>The following sections will describe each of these different facets
            in greater detail.</p>
                                  <table border="0" cellspacing="0" cellpadding="2" width="100%">
    <tr><td bgcolor="#828DA6">
      <font color="#ffffff" face="arial,helvetica,sanserif">
                        <a name="Descriptors"><strong>Descriptors</strong></a>
      </font>
    </td></tr>
    <tr><td>
      <blockquote>
                        <p>FIXME: Import this part from other doco</p>
                    </blockquote>
    </td></tr>
  </table>
                                  <table border="0" cellspacing="0" cellpadding="2" width="100%">
    <tr><td bgcolor="#828DA6">
      <font color="#ffffff" face="arial,helvetica,sanserif">
                        <a name="Class and Resource Files"><strong>Class and Resource Files</strong></a>
      </font>
    </td></tr>
    <tr><td>
      <blockquote>
                        <p>The class and resources files should be stored as in standard jars. The
                root directory being the base via which code and resources are loaded. So
                the
                    <code>.class</code> file for the Java class
                    <code>com.biz.tasks.Mytask</code>
                would be stored in
                    <code>/com/biz/tasks/Mytask.class</code>
                </p>
                    </blockquote>
    </td></tr>
  </table>
                                  <table border="0" cellspacing="0" cellpadding="2" width="100%">
    <tr><td bgcolor="#828DA6">
      <font color="#ffffff" face="arial,helvetica,sanserif">
                        <a name="Dependencies"><strong>Dependencies</strong></a>
      </font>
    </td></tr>
    <tr><td>
      <blockquote>
                        <p>It is often the case that a library will need external resources. The
                example given above described dependence on an external XML library. The
                ant library thus needs a mechanism via which to declare dependencies on
                external libraries.</p>
                                <p>Ant 2 uses the "Optional Package" mechanism. Prior to JDK1.3, an "Optional
                Package" was known as an
                    <em>Extension</em>. The specification for this
                mechanism is available in the JDK1.3 documentation in the directory

                    <code>$JDK_HOME/docs/guide/extensions/versioning.html</code>. Alternatively
                it is available online at

                    <a href="http://java.sun.com/j2se/1.3/docs/guide/extensions/versioning.html">
                                   http://java.sun.com/j2se/1.3/docs/guide/extensions/versioning.html</a>.
                </p>
                                <p>This mechanism was adopted as it is an established standard. The standard
                is also begining to be adopted by other specifications such as the
                    <em>Servlet
                                   2.3 API</em>. Thus we are likely to see an increase of jars using this mechanism
                to specify dependencies.
                </p>
                                <p>The "Optional Package" mechanism allows jars to specify dependencies on other
                jars that implement a particular specification at particular version levels. For
                example you could specify a dependency on the Trax 1.1 API by adding the following
                to the manifest of your jar.</p>
                                  <div align="left">
    <table cellspacing="4" cellpadding="0" border="0">
      <tr>
        <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
        <td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
        <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
      </tr>
      <tr>
        <td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
        <td bgcolor="#ffffff"><pre>
Extension-List: trax
trax-Extension-Name: Java API for XML Parsing
trax-Specification-Version: 1.1
                </pre></td>
        <td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
      </tr>
      <tr>
        <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
        <td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
        <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
      </tr>
    </table>
  </div>
                                <p>In some cases you may also wish to specify a dependency on a specific vendors
                implementation. For instance you may need to use xalan due to it implementing a
                particular extension you need. In that case you manifest may contain;</p>
                                  <div align="left">
    <table cellspacing="4" cellpadding="0" border="0">
      <tr>
        <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
        <td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
        <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
      </tr>
      <tr>
        <td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
        <td bgcolor="#ffffff"><pre>
Extension-List: trax
trax-Extension-Name: Java API for XML Parsing
trax-Specification-Version: 1.1
trax-Implementation-Title: org.apache.xalan.xslt
trax-Implementation-Version: 2.1.0
trax-Implementation-Vendor: Apache Software Foundation
                </pre></td>
        <td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
      </tr>
      <tr>
        <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
        <td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
        <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
      </tr>
    </table>
  </div>
                                <p>In many cases there will be no distinction between the specification and
                the implementation of a library. For instance the Velocity project only has
                one implementation and one specification. In which case it is sufficient to
                just declare a dependency on the Velocity "Specification". A library that uses
                both the Trax API and the Velocity project may look like;</p>
                                  <div align="left">
    <table cellspacing="4" cellpadding="0" border="0">
      <tr>
        <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
        <td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
        <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
      </tr>
      <tr>
        <td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
        <td bgcolor="#ffffff"><pre>
Extension-List: trax velocity
velocity-Extension-Name: org.apache.velocity
velocity-Specification-Version: 1.0
trax-Extension-Name: Java API for XML Parsing
trax-Specification-Version: 1.1
trax-Implementation-Title: org.apache.xalan.xslt
trax-Implementation-Version: 2.1.0
trax-Implementation-Vendor: Apache Software Foundation
                </pre></td>
        <td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
      </tr>
      <tr>
        <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
        <td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
        <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
      </tr>
    </table>
  </div>
                                <p>To make other jars available to Ant libraries as "Optional Packages"
                or Extensions then you need to add a few lines to the manifest of the
                other jar. The minimal manifest is the following;</p>
                                  <div align="left">
    <table cellspacing="4" cellpadding="0" border="0">
      <tr>
        <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
        <td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
        <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
      </tr>
      <tr>
        <td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
        <td bgcolor="#ffffff"><pre>
Extension-Name: org.realityforge.dve
Specification-Vendor: Peter Donald
Specification-Version: 1.0
                </pre></td>
        <td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
      </tr>
      <tr>
        <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
        <td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
        <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
      </tr>
    </table>
  </div>
                                <p>It is important to note that looking for dependencies is recursive. For example,
                if the ant library depends upon jar A and and A depends on B then both A and B will
                need to be loaded by the container.</p>
                    </blockquote>
    </td></tr>
  </table>
                                  <table border="0" cellspacing="0" cellpadding="2" width="100%">
    <tr><td bgcolor="#828DA6">
      <font color="#ffffff" face="arial,helvetica,sanserif">
                        <a name="Implementation Notes"><strong>Implementation Notes</strong></a>
      </font>
    </td></tr>
    <tr><td>
      <blockquote>
                        <p>So far there has been no mention of implementation strategies for
                managing ClassLoaders and other details about where the "Optional Packages"
                are stored. This section will outline such details but they could change
                in the future. The above specification will still be accurate but the approach
                to implementing specification will be different.</p>
                                <p>In the current architecture all of the "Optional Packages" are assumed to
                be stored in the
                    <code>$ANT_HOME/ext</code> directory. The runtime will scan
                this directory for jars and add all the "optional Packages" found into a
                registry. This registry will be used by the library loading mechanism to locate
                all the "Optional Packages". The user is able to specify an alternative directory
                or add a new directory to search on the commandline.
                </p>
                                <p>When the container attempts to load an ant library it will also try to load
                any needed dependencies. First it will check the parent ClassLoaders to see if any
                of them contain the required dependencies. If not then it will search the
                "Optional Packages" registry. If the dependency is not found then a error will be
                signaled. If the dependency is found in the "Optional Packages" registry then it is
                loaded by the same ClassLoader that is used to load the Ant library.</p>
                    </blockquote>
    </td></tr>
  </table>
                    </blockquote>
    </td></tr>
  </table>
              </td>
        </tr>

        <!-- FOOTER -->
        <tr><td colspan="2">
          <hr noshade="" size="1"/>
        </td></tr>
        <tr><td colspan="2">
          <div align="center"><font color="#525D76" size="-1"><em>
          Copyright &#169; 2000-2002, Apache Software Foundation
          </em></font></div>
        </td></tr>
      </table>
    </body>
  </html>
<!-- end the processing -->