antoine 2003/05/13 08:30:44
Added: xdocs/projects/antlib antlib_classloaders.xml
antlib_contract.xml antlib_descriptors.xml
antlib_namespaces.xml antlib_roadmap.xml index.xml
roles.xml
Log:
documentation about the antlib proposal and related questions
Revision Changes Path
1.1 ant/xdocs/projects/antlib/antlib_classloaders.xml
Index: antlib_classloaders.xml
===================================================================
<?xml version="1.0"?>
<document>
<properties>
<index value="2"/>
<author email="[EMAIL PROTECTED]">Antoine Levy-Lambert</author>
<title>Antlib Class Loaders</title>
</properties>
<body>
<section name="Jose Alberto Fernandez">
<p>
Let me first say that this feature appeared by the need to be able to say,
</p>
<source><![CDATA[
<antlib name="A" classpathref="XYZ"/>
<antlib name="B" classpathref="XYZ"/>
]]></source>
<p>
And being able to make sure that B and A use the same classLoader
and therefore they can use each other components.
</p>
<p>
My solution at the time was this idea of a named classloader that
you could define using a classpath, and then tell your antlibs use
this or that classloader, if you use the same classloader visibility
is guaranteed.
</p>
</section>
<section name="Stefan Bodewig 23.04.2003 17:11">
...
<p>
I understand that usecase (using the same class loader for 2 different
antlibs)
and think it's important. See Steve
Loughran's comment on the .NET tasks wanting to have access to the
datatypes defined in the cpptasks project for example.
</p><p>
Take a look at what Costin had done to <taskdef> and <typedef>
with
the loaderref attribute. This has now (i.e. CVS HEAD) been
generalized in ClasspathUtils, the infrastructure for named
classloaders is there - at least the foundation for it.
</p><p>
Stefan
</p>
</section>
<section name="Costin Manolache 29.04.2003 18:52">
<p>
The main issue is how to enforce ordering to deal with dependencies
between the antlibs.
</p><p>
Or simply do not deal with dependencies, ie antlibs must not (yet)
depend on on the other, except for the core ones.
</p><p>
Using an unified class loader ( at least as default ) - like jboss is doing,
or like JMX loading policy - has a lot of benefits. It also has some cases
that are not well covered - so we'll probably need to deal with both
"unified loader" and "loader hierarchy" cases.
</p>
</section>
</body>
</document>
1.1 ant/xdocs/projects/antlib/antlib_contract.xml
Index: antlib_contract.xml
===================================================================
<?xml version="1.0"?>
<document>
<properties>
<index value="2"/>
<author email="[EMAIL PROTECTED]">Antoine Levy-Lambert</author>
<title>Antlib Contract</title>
</properties>
<body>
<section name="definition of antlibs">
<p>
Antlibs are special-purpose jar files containing a deployment descriptor
called antlib.xml.
These jar files contain ant tasks and types. In the near future, they will
also contain custom components too able to act as filters, mappers, ...
</p>
<p>
The precise location of the deployment descriptor is already a point of
discussion. (such as com/xyz/anttasks/antlib.xml). <a
href="antlib_descriptors.html#concerns concerning the location of the
descriptor (Costin Manolache)">Costin Manolache would prefer deployment
descriptors to live in packages </a> The original proposal is to put the
deployment descriptor into META-INF/antlib.xml in the jar files.
</p>
</section>
<section name="loading of antlibs">
<p>
Under ant.home, a new subdirectory autolib would be created for antlibs to be
loaded "spontaneously".
</p>
<p>
antlibs can also be loaded explicitly with an <antlib/> task.
</p>
</section>
<section name="links">
<p>
<a
href="http://cvs.apache.org/viewcvs.cgi/*checkout*/ant/proposal/sandbox/antlib/docs/manual/CoreTasks/antlib.html?rev=HEAD";>Antlib
task documentation</a>
</p>
<p>
<a
href="http://cvs.apache.org/viewcvs.cgi/*checkout*/ant/proposal/sandbox/antlib/docs/manual/CoreTasks/antjar.html?rev=HEAD";>Antjar
task documentation</a>
</p>
</section>
<section name="todo">
<subsection name="versions">
<p>
ant-required-version, antlib-version (version used to build the library)
</p>
</subsection>
</section>
</body>
</document>
1.1 ant/xdocs/projects/antlib/antlib_descriptors.xml
Index: antlib_descriptors.xml
===================================================================
<?xml version="1.0"?>
<document>
<properties>
<index value="2"/>
<author email="[EMAIL PROTECTED]">Antoine Levy-Lambert</author>
<title>Antlib Descriptor</title>
</properties>
<body>
<section name="antlib descriptor in the proposal">
<source><![CDATA[
<antlib version="1.5" >
<task name="mkdir" class="org.apache.tools.ant.taskdefs.Mkdir"/>
...
<data-type name="fileset" class="org.apache.tools.ant.types.FileSet"/>
...
<role name="filter" class="org.apache.tools.ant.filters.ChainableReader"/>
...
<filter name="escapeunicode"
class="org.apache.tools.ant.filters.EscapeUnicode"/>
</antlib>
]]></source>
<p>
This is the layout of the antlib descriptor in the proposal. In each antlib
jar file, the descriptor would be found under
META-INF/antlib.xml
</p>
</section>
<section name="concerns concerning the location of the descriptor (Costin
Manolache)">
My concerns with getResources() as opposed to
getResource( PACKAGE/antlib.xml):
<ol>
<li>
startup time. In order to load one library you need to process all
of them. It can be resolved with caching the result and looking at .jar
modifications. Most likely we'll have dozens of antlibs - and that'll only
grow in time. The processing of (all) TLDs at startup ( for tomcat ) adds a
very visible overhead on startup, and at least tomcat is a long-running
process.
</li>
<br/>
<li>
Placing multiple antlibs in a single jar may be trickier.
</li>
<br/>
<li>
It may place too much emphasis on the .jars and filesystem layout.
</li>
<br/>
<li>
A bit harder to control ( as we know from c-logging and JAXP ),
</li>
<br/>
<li>Explicit control over what antlibs are to be used - versus loading
everything. Well - I like "magic" loading, but a lot of things in ant
are done explicitely.
</li>
</ol>
<br/>
<p>
I have no problem accepting a getResources() solution ( just like I'm
ok with using XML - but not any XML :-), but those issues should be
considered.
<br/>
A lot of the "mess" in ant is the result of doing some things without
considering all implications or just as side effect of how code happened
to work. That's why I'm so strongly for breaking things down to individual
problems instead of a bundle solution.
</p>
Costin
</section>
</body>
</document>
1.1 ant/xdocs/projects/antlib/antlib_namespaces.xml
Index: antlib_namespaces.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<document>
<properties>
<index value="2"/>
<author email="[EMAIL PROTECTED]">Antoine Levy-Lambert</author>
<title>Antlib Namespaces</title>
</properties>
<body>
<section name="J.Pietschmann 03.05.2003 17:25">
<p>
Nicola Ken Barozzi wrote:
< This seems interesting, and brings up what XML namespaces can be used
for.
</p><p>
XML namespaces are indented to disambiguate short local element
and attribute names. Any sematic associated to XML namespaces
beside this has to be weighted carefully.
</p><p>
Lets take an example. There are two projects, Foo and Bar,
each providing a task, lets call them <foo> and <bar>
respectively. Both tasks take a <part> child, by coincidence.
Of course, because the projects act uncoordinated, the <part>
child element has a different semantic. In order to make this
clearer, let's say the Foo <part> takes an optional <mumble>
child while the Bar <part> takes three mandatory <xonx>
children.
</p><p>
Someone finds both the <foo> and the <bar> task exciting and
wants to use both in an Ant build file. No problem so far:
because ot the way Ant elements get their child elements and
create associated Java objects, this should work.
Now said someone got a super-duper schema directed XML editor
and wants to use it for editing the build.xml file. He asks
all projects for a schema (DTD, XSD, RNG, whatever) for this
purpose and merges them in order to get a schema for his build
file. At this point the two <part> elements are likely to clash
(at least for DTDs, where element names are global). While
it is possible to merge the content models so that <part> now
takes either an optional <mumble> or three <xonx> children, this
would allow the user to put <xonx> children into the <part> of
the <foo> task. This is only a minor inconvenience for most
people, but an unthinkable horror for true purists.
</p><p>
Introduce namespaces: the Foo projects names its namespace
"http://www.fooproject.org/anttask"; while the Bar project uses
"URI:bar" or whatever. For the XML parser it is only really
important that two different strings are used. You see, the
longer the strings the less tha chance they will clash, and
they probably won't clash if they start with the URLs of the
project's homepages (the intent behind the recommendation to
use URLs, because it's the closest thing to a global registry
you can get short of actually creating a global registry).
Anyway, because the expanded names of the <part> elements are
now "{http://www.fooproject.org/anttask}part"; and "{URI:bar}part"
respectively they obviously no longer clash.
BTW you can write this as
</p>
<source><![CDATA[
<target name="foo">
<foo xmlns="http://www.fooproject.org/anttask";>
<part>
<mumble>
</part>
</foo>
<bar xmlns="URI:bar">
<part><xonx/><xonx/><xonx/></part>
</bar>
<target>
]]></source>
<p>
or as
</p>
<source><![CDATA[
<target name="foo"
xmlns:foo="http://www.fooproject.org/anttask";
xmlns:bar="URI:bar">
<foo:foo>
<foo:part>
<foo:mumble>
</foo:part>
</foo:foo>
<bar:bar>
<bar:part><bar:xonx/><bar:xonx/><bar:xonx/></bar:part>
</bar:bar>
<target>
]]></source>
<p>
take your pick (if you think the "foo" and "bar" prefixes are too
long, use "a" and "b" instead, it doesn't matter).
</p><p>
So far, the namespace names should only be different for different
projects, so why is it dangerous to associate some semantic with it,
like letting them point to a jar file? The problem is again that
general purpose XML tools, like the above mentioned super-duper XML
editor may associate their own semantics with the namespace, like
how to auto-format certain elements. This information will be stored
in some config files, and it requires that the namespace name is
the same until the semantics of the elements in it have changed
enough that it warrants assigning a new namespace name.
</p><p>
Summary:
</p>
<ol>
<li>
XML namespaces are there to facilitate aggregation of XML adhering
to schemas (content models) of different, uncoordinated origin.
</li><li>
XML Namespaces should be used in a way that no end user action
can result in two namespace names becoming unintentionally the
same.
</li><li>
XML Namespace names should preferably be assigned by the people
or project which specifies the semantics of the XML elemnets and
attributes therein.
</li><li>
XML Namespace names should be kept unchanged until a change of
the semantic of the elements warrants a change.
</li><li>
Good tools should not monopolize XML namespace syntax for its
own semantics.
</li>
</ol>
<p>
The schema directed editor should provide an example hoe tools
can take advantage of XML namespaces: use them as a key into a
DB/config to get it's own associated semantic.
In particular for Ant/Antlib I can imagine that each library
provides a factory object associated to the XML namespace for
the library.
</p><p>
The FOP parser uses such a two stage lookup: first the namespace
is used to get a factory object from a hash table, then the factory
is used with the local XML element name to create a Java object
which is inserted into the FO tree. The hash table with the factories
is initialized at startup, the associations between namespace name
and factory class name is read from a Services file. Want to add
a FOP extension? Get the default Services file, add a line with
your namespace-to-factoryclassname mapping put it into the jar with
all the classes and drop the jar as first into the classpath. If the
user wants to use multiple extensions, well, edit the main Services
instead, dead easy.
</p><p>
HTH
J.Pietschmann
</p>
</section>
</body>
</document>
1.1 ant/xdocs/projects/antlib/antlib_roadmap.xml
Index: antlib_roadmap.xml
===================================================================
<?xml version="1.0"?>
<document>
<properties>
<index value="2"/>
<author email="[EMAIL PROTECTED]">Antoine Levy-Lambert</author>
<title>Antlib Roadmap</title>
</properties>
<body>
<section name="Antlib with tasks and types only">
<p>
Let me quote here Stefan Bodewig - April 24th 2003.
</p>
<p>
Let's make a version of antlib that knows about two predefined roles,
task and data-type. I think this is already feature complete in the
proposal (which does even more).
</p>
<p>
Let's move this code with the restriction to tasks and types into the
main branch ASAP. Let's sort out the classloading requirements as
well as the interplay of antlib with taskdef and typedef here.
</p>
<p>
After this flies, I'd expect us to get roles sorted out. If we feel
like removing the difference between tasks and types, we can do so
then as well.
</p>
</section>
<section name="Roles and components in build files">
<p>
A second step : make a detailed proposal concerning roles and implement
roles and components in ant core.
</p>
</section>
<section name="Roles and components in antlibs">
<p>
Once roles and components are properly defined and implemented in ant core,
we would revisit <antlib> and implement roles and components there.
</p>
</section>
<section name="Namespaces">
<p>
After we have antlibs, roles, and components, we should specify how we are
going to proceed concerning namespaces and prefixes.
</p>
</section>
</body>
</document>
1.1 ant/xdocs/projects/antlib/index.xml
Index: index.xml
===================================================================
<?xml version="1.0"?>
<document>
<properties>
<index value="2"/>
<author email="[EMAIL PROTECTED]">Jose Alberto Fernandez</author>
<author email="[EMAIL PROTECTED]">Antoine Levy-Lambert</author>
<title>Antlib</title>
</properties>
<body>
<section name="Introduction">
<p>The purpose of this document is to summarize the discussions taking
place concerning antlib. I will try to always give proper credit, and to
represent
honestly different views expressed on the ant development mailing list.
Send comments/criticisms if you are not happy with these documents.
</p>
</section>
<section name="Overview">
<p>
Jose Alberto Fernandez 03.04.2003 18:25
</p>
<p>
There are the following features in the antlib proposal:
<ol>
<li>
antlib & antjar
</li>
<li>
type definitions that allow to define new implementations of mappers,
selectors, paths, conditions, etc. That you can define in your antlib and a way
to link this with the introspectors (I am not sure how complete this is).
</li>
<li>
A scoping framework for the symbol tables needed to manage the antlib
definitions (I think ANT has something on this regard)
</li>
<li>
A framework for managing classloaders where you can specify which
classloader to use when loading an antlib.
</li>
</ol>
</p>
</section>
<section name="Specific themes">
<ol>
<li>
<a href="antlib_contract.html"> Antlib contract</a>
</li>
<li>
<a href="antlib_descriptors.html"> Antlib descriptors</a>
</li>
<li>
<a href="antlib_classloaders.html">Classloaders</a>
</li>
<li>
<a href="roles.html">Roles, polymorphism, introspection</a>
</li>
<li>
<a href="antlib_namespaces.html">XML namespaces</a>
</li>
<li>
<a href="antlib_roadmap.html">Roadmap</a>
</li>
</ol>
</section>
</body>
</document>
1.1 ant/xdocs/projects/antlib/roles.xml
Index: roles.xml
===================================================================
<?xml version="1.0"?>
<document>
<properties>
<index value="2"/>
<author email="[EMAIL PROTECTED]">Antoine Levy-Lambert</author>
<title>Roles</title>
</properties>
<body>
<section name="What is a role">
<p>
I am quoting here Jose Alberto Fernandez 26.04.2003 22:05:
Roles allow defining families of objects (members of a role) that can be
used by tasks or inner elements developed separately.
The developer of the object accepting a particular role as a subelement
has no knowledge of the implementation of the object but much more
importantly it has no knowledge of the XML element tag used to refer
to this subelement in the XML file.
</p>
<p>
In the antlib proposal, there are two preset roles :
<ul>
<li>task</li>
<li>datatype</li>
</ul>
Examples of other roles are :
<ul>
<li>mapper</li>
<li>filter</li>
</ul>
</p>
<p>
What does it all mean? It means we can now write a task, well typed, which
can be accept different XML subelements depending on the declarations of
other objects present on the build. The vendor specific elements of
<ejbjar>, <jspc> and others are typical examples of where this
capability
can be very useful. Other parts of core could benefit of course.
</p>
<br/>
<subsection name="What do they do that is no possible in ANT">
<p>
They allow IntrospectionHelper to connect an XML subelement eventhough
introspection cannot find a create or add/Configured method for it.
It is a well typed methanism, the parent object will only be passed objects
that it knows how to deal with. And the parent object does not need to have
any knowledge of what currently available members are on the role.
</p>
</subsection>
</section>
<section name="roles versus DynamicConfigurator">
<p>
The closest thing in ANT today is DynamicConfigurator but its purpose
is on the other way around. Given an elementTag with no matching method
it is up to the parent object to try to make sense of it.
If we were to use this mechanism to accomplish what roles try to do,
it would require the parent object implementor to be aware of where
to find the correct definition (remember it is a 3rd party implementation)
and perform the creation. It will be also its responsibility to
resolve type conflicts, name collisions, etc. This are all things
that should be done by IntrospectionHelper directly.
</p>
<p>
Also notice that Roles do not supersede DynamicConfigurator. On one hand roles
let external implementations to be considered as possible subelements
of a parent object, on the other hand, DynamicConfigurator allows a node
to decide given its current state what is the meaning of a particular element.
This cannot be done by roles in the general case, and that is good.
</p> </section>
<section name="Implementation of roles in the proposal">
<p>this section quotes Jose Alberto Fernandez</p>
<p>
Here I may deviate from the exact code and add thoughts about where
do I think it should go.
</p>
<subsection name="Usage of Roles">
<p>
The principle is very simple:
</p>
<br/>
<ol>
<li>
A role is defined by an interface. This interface is the parameter
for a new special family of addConfigured(<interface>) methods.
</li>
<li>
<p>
When IntrospectionHelper fails to find a create/add method for the
element, it will look at all the roles used in the addConfigured
methods and on each of those roles will try to find an object declared
with that element-tag name. If one and only one match is found then
the instantiation is successful and the new object will be configured;
otherwise it is an error and parsing stops.
</p>
<br/>
</li>
<li>
<p>
The configured object may or may not implement the Role interface,
if it does not, an Adaptor object may be instantiated as a proxy
for the object. Which adaptor is used depends on how the implementation
was declared.
</p>
<br/>
</li>
<li>
<p>
The resulting object is passed as an argument to the addConfigured() method.
</p>
<br/>
</li>
</ol>
</subsection>
<subsection name="Declaration of roles">
<p>
A role definition associates a name with an (Interface,Adaptor) pair.
The only reason for associating a name with the role is to ease notation when
declaring members of a role.
</p>
<br/>
<p>
Notice that the same interface or the same Adaptor may appear in multiple
declarations. This only means that depending on the name used the adaptor
of choice will be different.
</p>
<br/>
<p>
There can only be one pair associated with each name.
</p>
<br/>
</subsection>
<subsection name="Declaration of
implementations (members)">
<br/>
<p>
A class is declared as belonging to a role by specifying the name to be used
when appearing in that role. The same class may belong to multiple roles
and may specify the same or different names on each one.
<br/>
</p>
<p>
The name used for the role during the declaration only determines which
Adaptor will be available, if required.
<br/>
</p>
<p>
Within a role-interface there can only be one object associated
with each name.
<br/>
</p>
</subsection>
<subsection name="Scoping rules">
<br/>
<p>
This is probably the more dificult aspect since given the way
<ant> and <antcall> work it means possible redeclarations on every
level of recursion. Whether declarations should just supercede
one another or be smarter is something to look into.
<br/>
</p>
</subsection>
<subsection name="Syntax">
<br/>
<p>
I have left out the issues of how the syntax looks like on purpose.
<br/>
</p>
<p>
Syntax is just that and I am sure we can reach agreement somehow.
It is also clear that we should provide tasks to define roles
and declare members of roles direclty on the build.
<br/>
</p>
</subsection>
</section>
<section name="Making ant aware of tag/role/class associations">
<p>
The antlib proposal says :
Let's declare explicitly that a tag can be used in a particular role and is
implemented by a specific class.
The declaration happens inside antlibs in the file META-INF/antlib.xml
</p>
Example :
<source><![CDATA[
<filter name="escapeunicode"
class="org.apache.tools.ant.filters.EscapeUnicode"/>
]]></source>
<p>
CM says :
A normal typedef is enough to make ant aware of the existence of the class
org.apache.tools.ant.filters.EscapeUnicode.
Due to the fact that EscapeUnicode implements ChainableReader, the
association between EscapeUnicode and the filter role does not need to be
stated explicitly.
</p>
</section>
<section name="Method names in parent classes supporting roles">
<p>
There is a discussion about how methods to add nested elements of a specific
roles in a parent class should be called, and what their signature should be
like.
</p>
<p>
CM :
<source>
addTYPE(TYPE)
</source>
for instance <source>addChainableReader(ChainableReader a)</source>
</p>
<p>
PR:
to add an element before its own attributes and nested elements are
configured.
<source>
void add(TYPE)
</source>
to add an already configured element
<source>
void addConfigured(TYPE)
</source>
</p>
<p>
in the ant code of 1.6 :
<source>public Object createDynamicElement(String name)</source>
</p>
</section>
<section name="Cardinality problems">
<subsection name="One tag, several implementations">
<p>
The <weblogic> element in <ejbjar>, <jspc>,
<serverdeploy>, has different meanings.
</p>
<p>
This is an argument to introduce roles in ant, and to associate an XML tag
with a role and an implementation class.
</p>
</subsection>
<subsection name="Parent classes accepting one
interface in different functions">
<p>
As an example, the dependset task accepts nested filesets for two different
functions :
<ul>
<li>source</li>
<li>target</li>
</ul>
</p>
<p>Stefan Bodewig/Costin Manolache suggest :</p>
<source><![CDATA[
<dependset>
<zipfileset ant:type="srcfileset">
</dependset>
]]></source>
</subsection>
<subsection name="adapters">
<p>
The antlib proposal mentions adapter classes, which would be connected to
roles.
Costin Manolache says that adapter classes should be tied to components, not
roles.
The reason : two different components implementing the same interface (AKA
role) can require different adapters.
</p>
</subsection>
</section>
<section name="role proposal">
<p>
slightly modified version of something writte by Jose Alberto Fernandez
</p>
<source><![CDATA[
<role name="roleName" className="...." [adapter="...."] />
<!-- I have added the possibility to declare a specific adapter per component
to take into account what Costin said -->
<component name="elementName" role="roleName" className="....."
[adapter="...."] />
]]></source>
</section>
</body>
</document>
