From e271ddf2bd89ae9ffe18c87d59f8afc7fe8fc88b Mon Sep 17 00:00:00 2001 From: Antoine Levy-Lambert Date: Fri, 4 Jul 2003 11:38:14 +0000 Subject: [PATCH] Remove obsolete documentation concerning antlib. git-svn-id: https://svn.apache.org/repos/asf/ant/core/trunk@274764 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 deletions(-) delete mode 100644 xdocs/projects/antlib/antlib_classloaders.xml delete mode 100644 xdocs/projects/antlib/antlib_contract.xml delete mode 100644 xdocs/projects/antlib/antlib_descriptors.xml delete mode 100644 xdocs/projects/antlib/antlib_namespaces.xml delete mode 100644 xdocs/projects/antlib/antlib_roadmap.xml delete mode 100644 xdocs/projects/antlib/index.xml delete mode 100644 xdocs/projects/antlib/roles.xml diff --git a/xdocs/projects/antlib/antlib_classloaders.xml b/xdocs/projects/antlib/antlib_classloaders.xml deleted file mode 100644 index 7ceae81d4..000000000 --- a/xdocs/projects/antlib/antlib_classloaders.xml +++ /dev/null @@ -1,68 +0,0 @@ - - - - - - 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 deleted file mode 100644 index 1b2e95c6b..000000000 --- a/xdocs/projects/antlib/antlib_contract.xml +++ /dev/null @@ -1,45 +0,0 @@ - - - - - - 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 deleted file mode 100644 index 54e9051cb..000000000 --- a/xdocs/projects/antlib/antlib_descriptors.xml +++ /dev/null @@ -1,71 +0,0 @@ - - - - - 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 deleted file mode 100644 index 94c59b6f9..000000000 --- a/xdocs/projects/antlib/antlib_namespaces.xml +++ /dev/null @@ -1,151 +0,0 @@ - - - - - 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 deleted file mode 100644 index df8b8e143..000000000 --- a/xdocs/projects/antlib/antlib_roadmap.xml +++ /dev/null @@ -1,48 +0,0 @@ - - - - - - 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 deleted file mode 100644 index f22b2b29a..000000000 --- a/xdocs/projects/antlib/index.xml +++ /dev/null @@ -1,68 +0,0 @@ - - - - - - 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 deleted file mode 100644 index ff331da19..000000000 --- a/xdocs/projects/antlib/roles.xml +++ /dev/null @@ -1,263 +0,0 @@ - - - - - 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 -

- - - - -]]> -
- -