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.
- -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.
- -Using kooky ascii art, the specific ClassLoader structure for Ant2 is as -follows:
- -$ANT_HOME/bin/ant-launcher.jar
-
- These classes are loaded from all the jars present in the $ANT_HOME/lib
- directory.
-
$ANT_HOME/bin/lib/ directory.
- $ANT_HOME/shared/ directory.
- 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.
+ +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.
+ +Using kooky ascii art, the specific ClassLoader structure for Ant2 is as + follows:
+ +$ANT_HOME/bin/ant-launcher.jar
+
+ These classes are loaded from all the jars present in the
+ $ANT_HOME/lib
+ directory.
+
+
$ANT_HOME/bin/lib/ directory.
+
+ $ANT_HOME/shared/ directory.
+
+ 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.
- -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;
- -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;
- -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;
- -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.
- -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.
+ +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;
+ +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;
+ +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;
+ +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.
+ +