| <!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 Librarys in Ant2</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">Build file</a> |
| </li> |
| <li> <a href="./vfs.html">Virtual File System</a> |
| </li> |
| </ul> |
| <p><strong>Extending Ant</strong></p> |
| <ul> |
| <li> <a href="./task.html">Task Writers 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 librarys 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 Ant2. The librarys (also referred to as |
| deployments) will be termed antlibs.</p> |
| <p>Ant librarys 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 librarys 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>Ant2 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 librarys 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 © 2000-2002, Apache Software Foundation |
| </em></font></div> |
| </td></tr> |
| </table> |
| </body> |
| </html> |
| <!-- end the processing --> |
| |
| |
| |
| |
