youys
/
ant
Not watched
1
0
Fork 1
Code
Releases 0 Wiki Activity
Issues 0 Pull Requests 0 Datasets Model Cloudbrain
Browse Source

Restyle doc 

git-svn-id: https://svn.apache.org/repos/asf/ant/core/trunk@272088 13f79535-47bb-0310-9956-ffa450edef68
master
Peter Donald 23 years ago
parent
df1067a7b4
commit
40cd098a8e
2 changed files with 315 additions and 273 deletions
Unified View
Diff Options
Show Stats Download Patch File Download Diff File
  1. +132
    -109
      proposal/myrmidon/src/xdocs/classloader.xml
  2. +183
    -164
      proposal/myrmidon/src/xdocs/librarys.xml

+ 132
- 109
proposal/myrmidon/src/xdocs/classloader.xml View File

@@ -1,113 +1,136 @@
<?xml version="1.0"?> <?xml version="1.0"?>
<document> <document>


<properties>
<title>On ClassLoaders in Ant2</title>
<author email="peter@apache.org">Peter Donald</author>
</properties>

<body>

<section name="ClassLoader Management">

<p>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.</p>

<p>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.</p>

<p>Using kooky ascii art, the specific ClassLoader structure for Ant2 is as
follows:</p>

<source>
Bootstrap
|
System
|
Common
/ \
Container Shared
/ \
Antlib1 Antlib2 ...
</source>

<ul>
<li>
The <strong>Bootstrap</strong> ClassLoader contains the classes and resources
provided by the Java runtime.
</li>
<li>
The <strong>System</strong> ClassLoader contains the classes that were made accessible
via the CLASSPATH environment variable. If the standard ant script was used then this
should only contain the classes that are used to bootstrap the ant runtime. ie
<code>$ANT_HOME/bin/ant-launcher.jar</code>
</li>
<li>
The <strong>Common</strong> ClassLoader contains the classes and resources
that are made visible to both the Container and to all the ant type librarys. This
contains all the classes that the Container uses to communicate with tasks and other
supporting infrastructure. In particular it contains the following APIs;
<ul>
<li>
<em>Task API</em> - Contains the classes that are part of the API used
to define tasks.
</li>
<li>
<em>ProjectListener API</em> - Contains the classes necessary to define new
ProjectListeners.
</li>
<li>
<em>Aspect API</em> - Contains the classes that are used to define Aspects
of the container.
</li>
<li>
<em>Container API</em> - Contains the interfaces that are required to communicate
with the objects deep within the container. <strong>NOTE</strong>: These interfaces
are not to be used by user tasks but are made available so that certain tasks (such
as &lt;antcall/&gt;) can be implemented. However they are subject to change without
notice between between different ant2 versions.
</li>
</ul>
<p>
These classes are loaded from all the jars present in the <code>$ANT_HOME/lib</code>
directory.
</p>
</li>
<li>
The <strong>Container</strong> ClassLoader contains all the classes and resources
that are part of the actual implementation of the Container. These classes are not
directly accessible to any Ant library or task. Some of the classes are indirectly
accessible to tasks and other elements defined in the ant librarys as they implement
interfaces defined in the <strong>Common</strong> ClassLoader. The classes that are
stored in jars in the <code>$ANT_HOME/bin/lib/</code> directory.
</li>
<li>
The <strong>Shared</strong> ClassLoader contains all the classes and resources
that are shared across all of the ant librarys (unless they are als needed by the
container in which case they should be placed int the <strong>Container</strong>
ClassLoader). This ClassLoader is populated by all the jars that are contained in
the <code>$ANT_HOME/shared/</code> directory.
</li>
<li>
The <strong>AntLib</strong> ClassLoaders each contain the classes and resources
that required by that particular library. Note that in some cases a single Ant
Library will manifest as a single ClassLoader containing a single jar. However
in some cases it is possible for one Ant Library to have multiple jars in its
ClassLoader or even have multiple ClassLoaders. See XXXX for further details.
</li>
</ul>

</section>

</body>
<properties>
<title>On ClassLoaders in Ant2</title>
<author email="peter@apache.org">Peter Donald</author>
</properties>

<body>

<section name="ClassLoader Management">

<p>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.</p>

<p>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.</p>

<p>Using kooky ascii art, the specific ClassLoader structure for Ant2 is as
follows:</p>

<source>
Bootstrap
|
System
|
Common
/ \
Container Shared
/ \
Antlib1 Antlib2 ...
</source>

<ul>
<li>
The
<strong>Bootstrap</strong> ClassLoader contains the classes and resources
provided by the Java runtime.

</li>
<li>
The
<strong>System</strong> ClassLoader contains the classes that were made accessible
via the CLASSPATH environment variable. If the standard ant script was used then this
should only contain the classes that are used to bootstrap the ant runtime. ie

<code>$ANT_HOME/bin/ant-launcher.jar</code>
</li>
<li>
The
<strong>Common</strong> ClassLoader contains the classes and resources
that are made visible to both the Container and to all the ant type librarys. This
contains all the classes that the Container uses to communicate with tasks and other
supporting infrastructure. In particular it contains the following APIs;

<ul>
<li>
<em>Task API</em> - Contains the classes that are part of the API used
to define tasks.

</li>
<li>
<em>ProjectListener API</em> - Contains the classes necessary to define new
ProjectListeners.

</li>
<li>
<em>Aspect API</em> - Contains the classes that are used to define Aspects
of the container.

</li>
<li>
<em>Container API</em> - Contains the interfaces that are required to communicate
with the objects deep within the container.
<strong>NOTE</strong>: These interfaces
are not to be used by user tasks but are made available so that certain tasks (such
as &lt;antcall/&gt;) can be implemented. However they are subject to change without
notice between between different ant2 versions.

</li>
</ul>
<p>
These classes are loaded from all the jars present in the
<code>$ANT_HOME/lib</code>
directory.

</p>
</li>
<li>
The
<strong>Container</strong> ClassLoader contains all the classes and resources
that are part of the actual implementation of the Container. These classes are not
directly accessible to any Ant library or task. Some of the classes are indirectly
accessible to tasks and other elements defined in the ant librarys as they implement
interfaces defined in the
<strong>Common</strong> ClassLoader. The classes that are
stored in jars in the
<code>$ANT_HOME/bin/lib/</code> directory.

</li>
<li>
The
<strong>Shared</strong> ClassLoader contains all the classes and resources
that are shared across all of the ant librarys (unless they are als needed by the
container in which case they should be placed int the
<strong>Container</strong>
ClassLoader). This ClassLoader is populated by all the jars that are contained in
the
<code>$ANT_HOME/shared/</code> directory.

</li>
<li>
The
<strong>AntLib</strong> ClassLoaders each contain the classes and resources
that required by that particular library. Note that in some cases a single Ant
Library will manifest as a single ClassLoader containing a single jar. However
in some cases it is possible for one Ant Library to have multiple jars in its
ClassLoader or even have multiple ClassLoaders. See XXXX for further details.

</li>
</ul>

</section>

</body>
</document> </document>

+ 183
- 164
proposal/myrmidon/src/xdocs/librarys.xml View File

@@ -1,168 +1,187 @@
<?xml version="1.0"?> <?xml version="1.0"?>
<document> <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>

</subsection>

</section>

</body>
<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>

</section>

</body>
</document> </document>

Write Preview
Loading…
Cancel
Save
Please read the following content carefully:

Dear OpenI User

Thank you for your continuous support to the Openl Qizhi Community AI Collaboration Platform. In order to protect your usage rights and ensure network security, we updated the Openl Qizhi Community AI Collaboration Platform Usage Agreement in January 2024. The updated agreement specifies that users are prohibited from using intranet penetration tools. After you click "Agree and continue", you can continue to use our services. Thank you for your cooperation and understanding.

For more agreement content, please refer to the《Openl Qizhi Community AI Collaboration Platform Usage Agreement》

Agree and continue
Disagree, exit