From 1783eaa89e2db276f662f6e6fab0f82715ecc43d Mon Sep 17 00:00:00 2001 From: Antoine Levy-Lambert Date: Tue, 13 May 2003 15:30:44 +0000 Subject: [PATCH] documentation about the antlib proposal and related questions git-svn-id: https://svn.apache.org/repos/asf/ant/core/trunk@274567 13f79535-47bb-0310-9956-ffa450edef68 --- xdocs/projects/antlib/antlib_classloaders.xml | 68 +++++ xdocs/projects/antlib/antlib_contract.xml | 45 +++ xdocs/projects/antlib/antlib_descriptors.xml | 71 +++++ xdocs/projects/antlib/antlib_namespaces.xml | 151 ++++++++++ xdocs/projects/antlib/antlib_roadmap.xml | 48 ++++ xdocs/projects/antlib/index.xml | 68 +++++ xdocs/projects/antlib/roles.xml | 263 ++++++++++++++++++ 7 files changed, 714 insertions(+) create mode 100644 xdocs/projects/antlib/antlib_classloaders.xml create mode 100644 xdocs/projects/antlib/antlib_contract.xml create mode 100644 xdocs/projects/antlib/antlib_descriptors.xml create mode 100644 xdocs/projects/antlib/antlib_namespaces.xml create mode 100644 xdocs/projects/antlib/antlib_roadmap.xml create mode 100644 xdocs/projects/antlib/index.xml create mode 100644 xdocs/projects/antlib/roles.xml diff --git a/xdocs/projects/antlib/antlib_classloaders.xml b/xdocs/projects/antlib/antlib_classloaders.xml new file mode 100644 index 000000000..7ceae81d4 --- /dev/null +++ b/xdocs/projects/antlib/antlib_classloaders.xml @@ -0,0 +1,68 @@ + + + + + + Antoine Levy-Lambert + Antlib Class Loaders + + + + +
+

+ Let me first say that this feature appeared by the need to be able to say, +

+ + +]]> +

+ And being able to make sure that B and A use the same classLoader + and therefore they can use each other components. +

+

+ + 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. +

+
+
+... + +

+ +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. +

+ +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. +

+ +Stefan +

+ +
+
+

+The main issue is how to enforce ordering to deal with dependencies +between the antlibs. +

+Or simply do not deal with dependencies, ie antlibs must not (yet) +depend on on the other, except for the core ones. +

+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. +

+
+ + \ No newline at end of file diff --git a/xdocs/projects/antlib/antlib_contract.xml b/xdocs/projects/antlib/antlib_contract.xml new file mode 100644 index 000000000..1b2e95c6b --- /dev/null +++ b/xdocs/projects/antlib/antlib_contract.xml @@ -0,0 +1,45 @@ + + + + + + Antoine Levy-Lambert + Antlib Contract + + + +
+

+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, ... +

+

+The precise location of the deployment descriptor is already a point of discussion. (such as com/xyz/anttasks/antlib.xml). Costin Manolache would prefer deployment descriptors to live in packages The original proposal is to put the deployment descriptor into META-INF/antlib.xml in the jar files. +

+
+
+

+Under ant.home, a new subdirectory autolib would be created for antlibs to be loaded "spontaneously". +

+

+antlibs can also be loaded explicitly with an <antlib/> task. +

+
+ +
+

+ Antlib task documentation +

+

+ Antjar task documentation +

+
+
+ +

+ant-required-version, antlib-version (version used to build the library) +

+ +
+ + \ No newline at end of file diff --git a/xdocs/projects/antlib/antlib_descriptors.xml b/xdocs/projects/antlib/antlib_descriptors.xml new file mode 100644 index 000000000..54e9051cb --- /dev/null +++ b/xdocs/projects/antlib/antlib_descriptors.xml @@ -0,0 +1,71 @@ + + + + + Antoine Levy-Lambert + Antlib Descriptor + + +
+ + + ... + + ... + + ... + + +]]> +

+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 +

+
+
+My concerns with getResources() as opposed to +getResource( PACKAGE/antlib.xml): +
    +
  1. +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. +
    2. +
    +
  2. +Placing multiple antlibs in a single jar may be trickier. +
    3. +
    +
  3. +It may place too much emphasis on the .jars and filesystem layout. +
    4. +
    +
  4. +A bit harder to control ( as we know from c-logging and JAXP ), +
    5. +
    +
  5. 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. +
    6. +
+
+

+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. +
+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. +

+ +Costin +
+ + diff --git a/xdocs/projects/antlib/antlib_namespaces.xml b/xdocs/projects/antlib/antlib_namespaces.xml new file mode 100644 index 000000000..94c59b6f9 --- /dev/null +++ b/xdocs/projects/antlib/antlib_namespaces.xml @@ -0,0 +1,151 @@ + + + + + Antoine Levy-Lambert + Antlib Namespaces + + + + +
+

+Nicola Ken Barozzi wrote: +< This seems interesting, and brings up what XML namespaces can be used for. +

+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. +

+ +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. +

+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. +

+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 +

+ + + + + + + + + + +]]> +

+or as +

+ + + + + + + + + + +]]> +

+take your pick (if you think the "foo" and "bar" prefixes are too +long, use "a" and "b" instead, it doesn't matter). +

+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. +

+ +Summary: +

+
    +
  1. +XML namespaces are there to facilitate aggregation of XML adhering + to schemas (content models) of different, uncoordinated origin. +
  2. +XML Namespaces should be used in a way that no end user action + can result in two namespace names becoming unintentionally the + same. +
  3. +XML Namespace names should preferably be assigned by the people + or project which specifies the semantics of the XML elemnets and + attributes therein. +
  4. +XML Namespace names should be kept unchanged until a change of + the semantic of the elements warrants a change. +
  5. +Good tools should not monopolize XML namespace syntax for its + own semantics. +
    6. +
+

+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. +

+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. +

+HTH +J.Pietschmann +

+
+ + diff --git a/xdocs/projects/antlib/antlib_roadmap.xml b/xdocs/projects/antlib/antlib_roadmap.xml new file mode 100644 index 000000000..df8b8e143 --- /dev/null +++ b/xdocs/projects/antlib/antlib_roadmap.xml @@ -0,0 +1,48 @@ + + + + + + Antoine Levy-Lambert + Antlib Roadmap + + + + +
+

+Let me quote here Stefan Bodewig - April 24th 2003. +

+

+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). +

+

+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. +

+

+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. +

+
+
+

+A second step : make a detailed proposal concerning roles and implement roles and components in ant core. +

+
+
+

+ Once roles and components are properly defined and implemented in ant core, we would revisit <antlib> and implement roles and components there. +

+
+
+

+ After we have antlibs, roles, and components, we should specify how we are going to proceed concerning namespaces and prefixes. +

+
+ + diff --git a/xdocs/projects/antlib/index.xml b/xdocs/projects/antlib/index.xml new file mode 100644 index 000000000..f22b2b29a --- /dev/null +++ b/xdocs/projects/antlib/index.xml @@ -0,0 +1,68 @@ + + + + + + Jose Alberto Fernandez + Antoine Levy-Lambert + Antlib + + + + +
+

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. +

+
+ +
+

+ Jose Alberto Fernandez 03.04.2003 18:25 +

+

+There are the following features in the antlib proposal: +

    +
  1. + antlib & antjar +
    2. +
  2. + 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). +
    3. +
  3. + A scoping framework for the symbol tables needed to manage the antlib definitions (I think ANT has something on this regard) +
    4. +
  4. + A framework for managing classloaders where you can specify which classloader to use when loading an antlib. +
    5. +
+

+
+
+
    +
  1. + Antlib contract +
    2. +
  2. + Antlib descriptors +
    3. +
  3. +Classloaders +
    4. +
  4. +Roles, polymorphism, introspection +
    5. +
  5. +XML namespaces +
    6. +
  6. +Roadmap +
    7. +
+
+ + + + diff --git a/xdocs/projects/antlib/roles.xml b/xdocs/projects/antlib/roles.xml new file mode 100644 index 000000000..ff331da19 --- /dev/null +++ b/xdocs/projects/antlib/roles.xml @@ -0,0 +1,263 @@ + + + + + Antoine Levy-Lambert + Roles + + +
+

+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. +

+

+ +In the antlib proposal, there are two preset roles : +

    +
  • task
    • +
  • datatype
    • +
+Examples of other roles are : +
    +
  • mapper
    • +
  • filter
    • +
+

+

+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. +

+
+ +

+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. +

+ +
+
+

+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. +

+

+ +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. +

+
+

this section quotes Jose Alberto Fernandez

+

+Here I may deviate from the exact code and add thoughts about where +do I think it should go. +

+ +

+The principle is very simple: +

+
+
    +
  1. +A role is defined by an interface. This interface is the parameter + for a new special family of addConfigured(<interface>) methods. +
    2. +
  2. +

    +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. +

    +
    +
    3. +
  3. +

    + 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. +

    +
    +
    4. +
  4. +

    +The resulting object is passed as an argument to the addConfigured() method. +

    +
    +
    5. +
+ + +

+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. +

+
+

+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. +

+
+

+There can only be one pair associated with each name. +

+
+ + +
+

+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. +
+

+

+The name used for the role during the declaration only determines which +Adaptor will be available, if required. +
+

+

+ +Within a role-interface there can only be one object associated +with each name. +
+

+ + +
+

+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. +
+

+ + +
+

+I have left out the issues of how the syntax looks like on purpose. +
+

+

+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. +
+

+ +
+
+

+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 +

+Example : + +]]> +

+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. +

+
+
+

+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. +

+

+CM : + +addTYPE(TYPE) + +for instance addChainableReader(ChainableReader a) +

+

+PR: +to add an element before its own attributes and nested elements are configured. + +void add(TYPE) + +to add an already configured element + +void addConfigured(TYPE) + +

+

+in the ant code of 1.6 : +public Object createDynamicElement(String name) +

+
+
+ +

+The <weblogic> element in <ejbjar>, <jspc>, <serverdeploy>, has different meanings. +

+

+This is an argument to introduce roles in ant, and to associate an XML tag with a role and an implementation class. +

+ + +

+As an example, the dependset task accepts nested filesets for two different functions : +

    +
  • source
    • +
  • target
    • +
+

+

Stefan Bodewig/Costin Manolache suggest :

+ + + +]]> + + +

+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. +

+ +
+
+

+slightly modified version of something writte by Jose Alberto Fernandez +

+ + + + +]]> +
+ +