From 9391dab2fef600986d1452c562d0a1437a3caa58 Mon Sep 17 00:00:00 2001 From: Stefan Bodewig Date: Wed, 30 Mar 2005 10:08:18 +0000 Subject: [PATCH] Remove dead docs git-svn-id: https://svn.apache.org/repos/asf/ant/core/trunk@278087 13f79535-47bb-0310-9956-ffa450edef68 --- docs/projects/antlib/antlib_classloaders.html | 172 -------- docs/projects/antlib/antlib_contract.html | 152 ------- docs/projects/antlib/antlib_descriptors.html | 171 -------- docs/projects/antlib/antlib_namespaces.html | 259 ------------ docs/projects/antlib/antlib_roadmap.html | 153 ------- docs/projects/antlib/index.html | 169 -------- docs/projects/antlib/roles.html | 395 ------------------ 7 files changed, 1471 deletions(-) delete mode 100644 docs/projects/antlib/antlib_classloaders.html delete mode 100644 docs/projects/antlib/antlib_contract.html delete mode 100644 docs/projects/antlib/antlib_descriptors.html delete mode 100644 docs/projects/antlib/antlib_namespaces.html delete mode 100644 docs/projects/antlib/antlib_roadmap.html delete mode 100644 docs/projects/antlib/index.html delete mode 100644 docs/projects/antlib/roles.html diff --git a/docs/projects/antlib/antlib_classloaders.html b/docs/projects/antlib/antlib_classloaders.html deleted file mode 100644 index 69baf2806..000000000 --- a/docs/projects/antlib/antlib_classloaders.html +++ /dev/null @@ -1,172 +0,0 @@ - - - - - - - - Apache Ant - Antlib Class Loaders - - - - - - -

- -

- -
- - - - - - -
Apache Ant siteApache Ant logo -
- - - - - - - - - - - - - - -
- - - - -
- the Apache Ant site -
-
-
-
- -
- - - - - -
- - - - -
Home
- 		- - - - -
Projects
-
-
- -
- -
-
-
    -
-
- - -
-
 
-
-
-

Antlib Class Loaders

-

- - Jose Alberto Fernandez -

-

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

- 
-<antlib name="A" classpathref="XYZ"/>
-<antlib name="B" classpathref="XYZ"/>
-
-

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

-

- - Stefan Bodewig 23.04.2003 17:11 -

-

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

-

- - Costin Manolache 29.04.2003 18:52 -

-

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

- -
-
- -

- Copyright © 2000-2003 The Apache Software Foundation. All rights reserved. - -

- - - - - - - - - - - diff --git a/docs/projects/antlib/antlib_contract.html b/docs/projects/antlib/antlib_contract.html deleted file mode 100644 index 540b3e24f..000000000 --- a/docs/projects/antlib/antlib_contract.html +++ /dev/null @@ -1,152 +0,0 @@ - - - - - - - - Apache Ant - Antlib Contract - - - - - - -

- -

- -
- - - - - - -
Apache Ant siteApache Ant logo -
- - - - - - - - - - - - - - -
- - - - -
- the Apache Ant site -
-
-
-
- -
- - - - - -
- - - - -
Home
- 		- - - - -
Projects
-
-
- -
- -
-
-
    -
-
- - -
-
 
-
-
-

Antlib Contract

-

- - definition of antlibs -

-

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

-

- - loading of antlibs -

-

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

-

- - links -

-

- Antlib task documentation -

-

- Antjar task documentation -

-

- - todo -

-

- - versions -

-

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

- -
-
- -

- Copyright © 2000-2003 The Apache Software Foundation. All rights reserved. - -

- - - - - - - - - - - diff --git a/docs/projects/antlib/antlib_descriptors.html b/docs/projects/antlib/antlib_descriptors.html deleted file mode 100644 index 6cd3ae72c..000000000 --- a/docs/projects/antlib/antlib_descriptors.html +++ /dev/null @@ -1,171 +0,0 @@ - - - - - - - - Apache Ant - Antlib Descriptor - - - - - - -

- -

- -
- - - - - - -
Apache Ant siteApache Ant logo -
- - - - - - - - - - - - - - -
- - - - -
- the Apache Ant site -
-
-
-
- -
- - - - - -
- - - - -
Home
- 		- - - - -
Projects
-
-
- -
- -
-
-
    -
-
- - -
-
 
-
-
-

Antlib Descriptor

-

- - antlib descriptor in the proposal -

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

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

-

- - concerns concerning the location of the descriptor (Costin Manolache) -

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

- -
-
- -

- Copyright © 2000-2003 The Apache Software Foundation. All rights reserved. - -

- - - - - - - - - - - diff --git a/docs/projects/antlib/antlib_namespaces.html b/docs/projects/antlib/antlib_namespaces.html deleted file mode 100644 index 3b68d46d5..000000000 --- a/docs/projects/antlib/antlib_namespaces.html +++ /dev/null @@ -1,259 +0,0 @@ - - - - - - - - Apache Ant - Antlib Namespaces - - - - - - -

- -

- -
- - - - - - -
Apache Ant siteApache Ant logo -
- - - - - - - - - - - - - - -
- - - - -
- the Apache Ant site -
-
-
-
- -
- - - - - -
- - - - -
Home
- 		- - - - -
Projects
-
-
- -
- -
-
-
    -
-
- - -
-
 
-
-
-

Antlib Namespaces

-

- - J.Pietschmann 03.05.2003 17:25 -

-

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

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

-or as -

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

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

- -
-
- -

- Copyright © 2000-2003 The Apache Software Foundation. All rights reserved. - -

- - - - - - - - - - - diff --git a/docs/projects/antlib/antlib_roadmap.html b/docs/projects/antlib/antlib_roadmap.html deleted file mode 100644 index 802c36a61..000000000 --- a/docs/projects/antlib/antlib_roadmap.html +++ /dev/null @@ -1,153 +0,0 @@ - - - - - - - - Apache Ant - Antlib Roadmap - - - - - - -

- -

- -
- - - - - - -
Apache Ant siteApache Ant logo -
- - - - - - - - - - - - - - -
- - - - -
- the Apache Ant site -
-
-
-
- -
- - - - - -
- - - - -
Home
- 		- - - - -
Projects
-
-
- -
- -
-
-
    -
-
- - -
-
 
-
-
-

Antlib Roadmap

-

- - Antlib with tasks and types only -

-

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

-

- - Roles and components in build files -

-

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

-

- - Roles and components in antlibs -

-

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

-

- - Namespaces -

-

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

- -
-
- -

- Copyright © 2000-2003 The Apache Software Foundation. All rights reserved. - -

- - - - - - - - - - - diff --git a/docs/projects/antlib/index.html b/docs/projects/antlib/index.html deleted file mode 100644 index 7764341e0..000000000 --- a/docs/projects/antlib/index.html +++ /dev/null @@ -1,169 +0,0 @@ - - - - - - - - Apache Ant - Antlib - - - - - - - - -

- -

- -
- - - - - - -
Apache Ant siteApache Ant logo -
- - - - - - - - - - - - - - -
- - - - -
- the Apache Ant site -
-
-
-
- -
- - - - - -
- - - - -
Home
- 		- - - - -
Projects
-
-
- -
- -
-
-
    -
-
- - -
-
 
-
-
-

Antlib

-

- - Introduction -

-

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

-

- - Overview -

-

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

-

- - Specific themes -

-
    -
  1. - Antlib contract -
    2. -
  2. - Antlib descriptors -
    3. -
  3. -Classloaders -
    4. -
  4. -Roles, polymorphism, introspection -
    5. -
  5. -XML namespaces -
    6. -
  6. -Roadmap -
    7. -
- -
-
- -

- Copyright © 2000-2003 The Apache Software Foundation. All rights reserved. - -

- - - - - - - - - - - diff --git a/docs/projects/antlib/roles.html b/docs/projects/antlib/roles.html deleted file mode 100644 index 2d600c44a..000000000 --- a/docs/projects/antlib/roles.html +++ /dev/null @@ -1,395 +0,0 @@ - - - - - - - - Apache Ant - Roles - - - - - - -

- -

- -
- - - - - - -
Apache Ant siteApache Ant logo -
- - - - - - - - - - - - - - -
- - - - -
- the Apache Ant site -
-
-
-
- -
- - - - - -
- - - - -
Home
- 		- - - - -
Projects
-
-
- -
- -
-
-
    -
-
- - -
-
 
-
-
-

Roles

-

- - What is a role -

-

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

-
-

- - What do they do that is no possible in ANT -

-

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

-

- - roles versus DynamicConfigurator -

-

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

-

- - Implementation of roles in the proposal -

-

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

-

- - Usage of Roles -

-

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

- - Declaration of roles -

-

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

-
-

- - Declaration of implementations (members) -

-
-

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

-

- - Scoping rules -

-
-

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

-

- - Syntax -

-
-

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

-

- - Making ant aware of tag/role/class associations -

-

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

- 
-  <filter name="escapeunicode" class="org.apache.tools.ant.filters.EscapeUnicode"/>
-
-

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

-

- - Method names in parent classes supporting roles -

-

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

-

- - Cardinality problems -

-

- - One tag, several implementations -

-

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

-

- - Parent classes accepting one interface in different functions -

-

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

    -
  • source
    • -
  • target
    • -
-

-

Stefan Bodewig/Costin Manolache suggest :

- 
- <dependset>
-   <zipfileset ant:type="srcfileset">
- </dependset>
-
-

- - adapters -

-

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

-

- - role proposal -

-

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

- 
-<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="...."] />
-
-
- -
-
- -

- Copyright © 2000-2003 The Apache Software Foundation. All rights reserved. - -

- - - - - - - - - - -