From 4f069ecbb33d0a7ef49a2da13fe3f722ab95faad Mon Sep 17 00:00:00 2001 From: Peter Donald Date: Sat, 2 Mar 2002 00:53:38 +0000 Subject: [PATCH] Add in initial cut of documentation for librarys. It completely punts on descriptro format for the time being - mainly as I already documented that elsewhere and just need to convert it to xdocs git-svn-id: https://svn.apache.org/repos/asf/ant/core/trunk@271646 13f79535-47bb-0310-9956-ffa450edef68 --- proposal/myrmidon/src/xdocs/librarys.xml | 168 +++++++++++++++++++++++ 1 file changed, 168 insertions(+) create mode 100644 proposal/myrmidon/src/xdocs/librarys.xml diff --git a/proposal/myrmidon/src/xdocs/librarys.xml b/proposal/myrmidon/src/xdocs/librarys.xml new file mode 100644 index 000000000..15983fef3 --- /dev/null +++ b/proposal/myrmidon/src/xdocs/librarys.xml @@ -0,0 +1,168 @@ + + + + + On Librarys in Ant2 + Peter Donald + + + + +
+ +

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.

+ +

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 + +Jar Specification.

+ +

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 +.class 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).

+ +

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 Trax API then +the Ant library needs to have access to the Trax API and an +implementation of the API. The Antlib mechanism thus uses the standard +"Optional Package" Specification to declare dependencies on other +libraries.

+ +

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.

+ +

The following sections will describe each of these different facets +in greater detail.

+ + + +

FIXME: Import this part from other doco

+ + + + + +

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 .class file for the Java class com.biz.tasks.Mytask +would be stored in /com/biz/tasks/Mytask.class

+ + + + + +

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.

+ +

Ant2 uses the "Optional Package" mechanism. Prior to JDK1.3, an "Optional +Package" was known as an Extension. The specification for this +mechanism is available in the JDK1.3 documentation in the directory +$JDK_HOME/docs/guide/extensions/versioning.html. Alternatively +it is available online at + +http://java.sun.com/j2se/1.3/docs/guide/extensions/versioning.html.

+ +

This mechanism was adopted as it is an established standard. The standard +is also begining to be adopted by other specifications such as the Servlet +2.3 API. Thus we are likely to see an increase of jars using this mechanism +to specify dependencies.

+ +

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.

+ + +Extension-List: trax +trax-Extension-Name: Java API for XML Parsing +trax-Specification-Version: 1.1 + + +

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;

+ + +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 + + +

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;

+ + +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 + + +

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;

+ + +Extension-Name: org.realityforge.dve +Specification-Vendor: Peter Donald +Specification-Version: 1.0 + + +

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.

+ + + + + +

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.

+ +

In the current architecture all of the "Optional Packages" are assumed to +be stored in the $ANT_HOME/ext 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.

+ +

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.

+ + + +
+ + +