donaldp 02/03/28 19:10:47 Modified: proposal/myrmidon/src/xdocs librarys.xml Log: Restyle doc Revision Changes Path 1.2 +180 -161 jakarta-ant/proposal/myrmidon/src/xdocs/librarys.xml Index: librarys.xml =================================================================== RCS file: /home/cvs/jakarta-ant/proposal/myrmidon/src/xdocs/librarys.xml,v retrieving revision 1.1 retrieving revision 1.2 diff -u -r1.1 -r1.2 --- librarys.xml 2 Mar 2002 00:53:38 -0000 1.1 +++ librarys.xml 29 Mar 2002 03:10:47 -0000 1.2 @@ -1,168 +1,187 @@ <?xml version="1.0"?> <document> - <properties> - <title>On Librarys in Ant2</title> - <author email="[EMAIL PROTECTED]">Peter Donald</author> - </properties> - -<body> - -<section name="Library Management"> - -<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> - -<subsection name="Descriptors"> - -<p>FIXME: Import this part from other doco</p> - -</subsection> - -<subsection name="Class and Resource Files"> - -<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> - -</subsection> - -<subsection name="Dependencies"> - -<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> - -<source> -Extension-List: trax -trax-Extension-Name: Java API for XML Parsing -trax-Specification-Version: 1.1 -</source> - -<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> - -<source> -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 -</source> - -<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> - -<source> -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 -</source> - -<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> - -<source> -Extension-Name: org.realityforge.dve -Specification-Vendor: Peter Donald -Specification-Version: 1.0 -</source> - -<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> - -</subsection> - -<subsection name="Implementation Notes"> - -<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> + <properties> + <title>On Librarys in Ant2</title> + <author email="[EMAIL PROTECTED]">Peter Donald</author> + </properties> + + <body> + + <section name="Library Management"> + + <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> + + <subsection name="Descriptors"> + + <p>FIXME: Import this part from other doco</p> + + </subsection> + + <subsection name="Class and Resource Files"> + + <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> + + </subsection> + + <subsection name="Dependencies"> + + <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> + + <source> + Extension-List: trax + trax-Extension-Name: Java API for XML Parsing + trax-Specification-Version: 1.1 + </source> + + <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> + + <source> + 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 + </source> + + <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> + + <source> + 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 + </source> + + <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> + + <source> + Extension-Name: org.realityforge.dve + Specification-Vendor: Peter Donald + Specification-Version: 1.0 + </source> + + <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> + + </subsection> + + <subsection name="Implementation Notes"> + + <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> -</subsection> + </subsection> -</section> + </section> -</body> + </body> </document>
-- To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]> For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
