ant-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From dona...@apache.org
Subject cvs commit: jakarta-ant/proposal/myrmidon/src/xdocs librarys.xml
Date Fri, 29 Mar 2002 03:10:47 GMT
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="peter@apache.org">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="peter@apache.org">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:ant-dev-unsubscribe@jakarta.apache.org>
For additional commands, e-mail: <mailto:ant-dev-help@jakarta.apache.org>


Mime
View raw message