Menu
▾
▴
[Tm4j-commits] tm4j/lib/ant/apache-ant-1.7.0/docs/ant2 FunctionalRequirements.html, NONE, 1.1 VFS.txt, NONE, 1.1 actionlist.html, NONE, 1.1 features.html, NONE, 1.1 original-specification.html, NONE, 1.1 requested-features.html, NONE, 1.1 requested-features.txt, NONE, 1.1
|
From: Xuan B. <med...@us...> - 2008-01-25 19:21:14
|
Update of /cvsroot/tm4j/tm4j/lib/ant/apache-ant-1.7.0/docs/ant2 In directory sc8-pr-cvs10.sourceforge.net:/tmp/cvs-serv12860/lib/ant/apache-ant-1.7.0/docs/ant2 Added Files: FunctionalRequirements.html VFS.txt actionlist.html features.html original-specification.html requested-features.html requested-features.txt Log Message: Update 4 years old ant. --- NEW FILE: actionlist.html --- <html> <head><title>Ant1.9 Action List</title></head> <body bgcolor="#ffffff"> <center> <h1>Ant1.9 Action List</h1> <h2>Precursor to Ant2</h2> <i>Peter Donald [<a href="mailto:peter at apache.org">peter at apache.org</a>]</i> </center> <div align="center"> <table width="80%"><tr><td> <blockquote> <p> This document aims to contain a list of actions that people can take to produce Ant1.9. Ant1.9 is a refactoring of the Ant1.x line and a jump point for Ant2. Some changes will be backported to Ant1.x over time when they have proven themselves while other changes may only become available via Ant2.0. Ant1.9 is our melting pot where we can experiment and refactor without a thought to backwards compatability but only to the "right" way of doing things. </p> </blockquote></td></tr> </table> </div> <h2>Introduction</h2> <blockquote> <p> This document will list a bunch of actions that will guide us in the evolution of Ant1.x and provide a solid basis on which to launch Ant2.0. Feel free to add to this list of actions as our vision of Ant2 solidifies. Associated with each action is a list of victims who have "volunteered" to have a go at the action and a status. The status just tells us where they are at while the victim column will tell us exactly who is doing what. It is fine for a group of people to work on a single area. </p> <br /> <br /> <br /> <div align="center"> <table cellspacing="2" cellpadding="5" width="80%"> <tr> <td bgcolor="#eeeeee" align="center">Action</td> <td bgcolor="#eeeeee" align="center">Victims</td> <td bgcolor="#eeeeee" align="center">Status</td> </tr> <tr> <td><a href="#vfs">Create a Virtual Filesystem layer</a></td> <td>None</td> <td>Not Started</td> </tr> <tr> <td><a href="#naming">Formalize a naming scheme for task attributes/elements</a></td> <td>None</td> <td>Not Started</td> </tr> <tr> <td><a href="#selector">Design and implement s Selector API for Filesets and other Itemsets</a></td> <td>None</td> <td>Not Started</td> </tr> <tr> <td><a href="#coloring">Develope the infrastructure for coloring (or "environmental" dependency analysis)</a></td> <td>None</td> <td>Not Started</td> </tr> <tr> <td><a href="#structural">Develope the infrastructure for structural dependency analysis</a></td> <td>None</td> <td>Not Started</td> </tr> <tr> <td><a href="#exec">Refactor the Exec infrastructure into JavaBeans</a></td> <td>Peter Donald</td> <td>80%</td> </tr> <tr> <td><a href="#java">Refactor the Java infrastructure into JavaBeans</a></td> <td>None</td> <td>Not Started</td> </tr> <tr> <td><a href="#facade">Design and implement a generic solution for creating Task facades</a></td> <td>None</td> <td>Not Started</td> </tr> <tr> <td><a href="#packaging">Sketch out a basic way of separating all the tasks into type libraries</a></td> <td>None</td> <td>Not Started</td> </tr> <tr> <td><a href="#mapperext">Design and implement an API that allows mapping of file attributes during copy/move/etc tasks</a></td> <td>None</td> <td>Not Started</td> </tr> <tr> <td><a href="#filters">Design and implement an API so that Filters could be implemented as FilteredOutputStreams</a></td> <td>None</td> <td>Not Started</td> </tr> <tr> <td><a href="#catalog">Design and implement a XML "catalog" so the snippets of XML can be injected based on URI rather than relative location</a></td> <td>None</td> <td>Not Started</td> </tr> <tr> <td><a href="#i18n">Look at the feasability of i18n'ing tasks and the runtime</a></td> <td>None</td> <td>Not Started</td> </tr> <tr> <td><a href="#doco">Write a document describing the way that tasks should be written in context of Ant2</a></td> <td>Peter Donald<br />(peter at apache.org)</td> <td>Not Started</td> </tr> <tr> <td><a href="#embeddor">Design an API to embed Ant into other applications</a></td> <td>None</td> <td>Not Started</td> </tr> <tr> <td><a href="#info">Design a TypeInfo system similar to BeanInfo to describe Tasks</a></td> <td>None</td> <td>Not Started</td> </tr> <tr> <td><a href="#antdoc">Design Antdoc to generate manual from .java files</a></td> <td>None</td> <td>Not Started</td> </tr> </table> </div> </blockquote> <h3>Virtual File System</h3> <a name="vfs" /> <blockquote> <p> There has long been a recognition that it would be nice if ant supported some notion of a virtual filesystem layer. This layer would allow you to treat resources located and retrieved from different mechanisms in a uniform way. For instance it would allow the copy task to copy from a http server, a cvs server, a ftp server or the local filesystem using a uniform mechanism. So instead of having separate tasks to operate on each different resource type we would use just one task that plugged into multiple filesystems. </p> <p> When we are talking about a virtual filesystem or VFS, one of the concerns we must address is how to "name" the resource. In most cases a URL or URI style access will be sufficient but in other cases we may need to consider other options. So "cvs://localhost:/home/cvs/jakarta-avalon/README.txt?version=1.1", "ftp://some.server.com/dir/file.zip" and "file://C/WINDOWS/Desktop/MyFile.txt" are all examples of referring to different resources. </p> <p> Another concern that must be addressed is capabilities of both the resources and the filesystem. For instance it is possible to both read and write to resources using the "file" protocol but only possible to write resources using "mailto". The act of copying a file to a "mailto" url would actuall post the files as resources while copying to a "file" would duplicate the resource somewhere on the local filesystem. </p> <p> So we need to determine a list of capabilities. Some examples would be "read", "write", "list" (can you list dirs), "type" (can you get mime type), "access permissions" (can you tell if resource has permissions), "modify permissions" (can you modify permissions) etc. Some of these capabilities can be associated with the particular reosurces, while others may need to be associated with a whole filesystem/protocol (ie there is no standard mechanism to perform "list" on general "http" URLs). Thus a list of all these capabilities and mapping to various protocols will need to be established. </p> <p> Next we need to determine if we are going to support the notion of "mounting" URLs. For instance if we need to copy files from a FTP server do we allways need to specify the full URL - no matter how convoluted it is (ie "ftp://fred:se...@so...:28763/home/fred/project2/dir/file.zip") or can we mount this on a VFS and access it via that shorter url. ie We could mount "ftp://fred:se...@so...:28763/home/fred/" onto "vfs:/home" and then just access the resources via "vfs:/home/project2/dir/file.zip". This would make dealing with large urls easier and more uniform. </p> <p> So after we have decided what our options are we need to actually go about implementing the solution. It may be the case that existing VFS solutions could be reused with minor changes and thus we could save ourselves a lot of work. Candidates would be the Netbeans VFS, Suns XFile API or other available directory APIs (like JNDI). If none of them suit then we will need to write our own layer. </p> </blockquote> <h3>Naming</h3> <a name="naming" /> <blockquote> <p> Currently Ant has a mixture of tasks from various stages it's evolution, with different authors and each utilizing different naming patterns. Some tasks use names such as "src" and "dest" while others use "file" and "tofile". It would be preferrable if consistent naming patterns were used. It is recomended that we come up with a "best practices" document to document our recomended naming patterns. </p> <p> Before we can come up with such a document we need to identify common patterns through out the tasks. Several tasks have the notion of transforming input from a "source" to a "destination". So we should have consistent naming schemes for these attributes and elements. Analysis of existing tasks will likely bring out other similar patterns. Once we have identified and documented these similarities then we can establish conventions. </p> </blockquote> <h3>Selector API</h3> <a name="selector" /> <blockquote> <p> Currently our filesets allow us to select a set of files based on name patterns. For instance we could create a set of all the files that end with ".java". However there are cases when you wish to select files based on their other attributes, such as if they are read only or if they are older than a specified date etc. </p> <p> The selector API is one such mechanism to do this. The selector API will allow you to build file sets based on criteria other than name. Some possible criteria would be </p> <ul> <li>Is the file readable?</li> <li>Is the file writeable?</li> <li>What date was the file modified on?</li> <li>What size is the file?</li> <li>Does the contents contain the string "magic"?</li> </ul> <p> If we end up supporting a VFS then we could expand the number of selectors considerably. A mock representation that has been proposed before is the following. Of course this is subject to change as soon as someone wants to tackle this action ;) </p> <pre> <include> <selector type="name" value="**/*.java"/> <selector type="permission" value="r"/> <!-- could optionally be directory/or some other system specific features --> <selector type="type" value="file"/> <selector type="modify-time" operation="greater-than" value="29th Feb 2003"/> </include> </pre> </blockquote> <h3>Coloring API</h3> <a name="coloring" /> <blockquote> <p> When you execute a task such as "javac" there is two types of dependency information that is important to analyze before we determine if we need to recompile a file. Say we are compiling <code>Foo.java</code>, it may depend on the <code>Bar.java</code> file. We call this "structural" dependency information - the structure of the source file determines what other files it depend upon. However there is also "environmental" dependency information. For instance if the <code>Foo.java</code> file was compiled with <code>debug="true"</code> last run and this time needs to be compiled with <code>debug="false"</code> then it is out of date and needs to be recompiled. We call this "environmental" dependency information "coloring". </p> <p> So we need to create an infrastructure that allows tasks to manage "coloring". So a task should be able to add coloring information for each resource processed. When the task comes to process the resource again it will detect if the coloring has changed and if it has will force a recompile. </p> <p> An API for such a bean has yet to be established but an example API would be. </p> <pre> ColoringManager cm = ...; cm.addColor( "debug", "true" ); cm.addColor( "optimize", "false" ); cm.setFileSet( myFileSet ); File[] files = cm.getOutOfDate(); </pre> </blockquote> <h3>Structural Dependency Utils</h3> <a name="structural" /> <blockquote> <p> In the present ant, it is required that each task manage dependency separately. This makes it a lot of work to implement even simple dependency checking. To this day many of the core tasks do not implement it correctly. I am specifically talking about "structural" dependency information. The main reason is that it is painful to implement. </p> <p> Some tasks do no dependency checking and will recompile/transform/etc everytime. Others may perform a simple dependency checking (ie if source file is newer than destination file then recompile). Ideally a dependency system would actually calculate the dependencies correctly. So we need to have some mechanism to determine that <code>foo.c</code> actually depends upon <code>foo.h</code>, <code>bar.h</code> and <code>baz.h</code>. As this information is particular to each different task we need to allow tasks to implement this behaviour. Possibly by supplying an interface of the form; </p> <pre> public interface DependencyGenerator { File[] generateDependencies( File file ); } </pre> <p> Generating the dependency information is a costly operation and thus we do not want to be doing it everytime you run ant. We want to generate it on the initial build and then persist somewhere. Everytime a file is out of date, it's dependency information would be regenerated and stored in the dependency cache. Ideally this cache would also store the above mentioned coloring information. So the entry for <code>foo.c</code> may declare that it is dependent upon <code>foo.h</code>, <code>bar.h</code> and <code>baz.h</code>, aswell as being compiled with -O2 flag. If any of the dependencies have changed or are out of date then foo.c would need to be recompiled. </p> <p> A possible API would be </p> <pre> DependencyManager dm = ...; dm.setFileSet( myFileSet ); dm.setDependencyCache( myDependencyCacheFile ); File[] files = cm.getOutOfDate(); </pre> </blockquote> <h3>Refactor <exec> infrastructure into Beans</h3> <a name="exec" /> <blockquote> <p> Exec and its related classes have currently evolved through several iterations and thus it is not as cleanly designed and as reusable as it could be. Someone needs to pull apart exec and analyze which parts can be turned into JavaBeans and decouple them from the Ant infrastructure. Once that is done it will make these beans much easier to reuse from other tasks without relying on gaining access to the other task instance. </p> </blockquote> <h3>Refactor <java> infrastructure into Beans</h3> <a name="java" /> <blockquote> <p> Much like Exec should be decoupled from Ant runtime, so should classes to implement java task for the same benefits. </p> </blockquote> <h3>Generic Task Facades</h3> <a name="facade" /> <blockquote> <p> Currently we have a few tasks that have multiple implementations. For instance Javac task can actually call jikes, jvc, classic javac or modern javac. Similar things will be seen with the jspc task and the cc task (if it ever gets written). We need to examine this pattern and see if there is a way to generalize this and make it easier to write such tasks. </p> </blockquote> <h3>Task Packaging</h3> <a name="packaging" /> <blockquote> <p> We have already decided that we are going to package Ant tasks in separate jars and have some sort of descriptor that to describe the contents of the jar. However we have not yet decided how we will break up the tasks. Do we break up the tasks up into related tasks or into groups that ar elikely to be used together or what? A possible breakdown would be </p> <ul> <li>jdk tasks: javac, javadoc, rmic etc</li> <li>text tasks: regex replace, fixcrlf etc</li> <li>unix tasks: chmod, etc</li> <li>file tasks: copy, move, etc</li> </ul> </blockquote> <h3>Mapping File Attributes during transformation</h3> <a name="mapperext" /> <blockquote> <p> When we are copying files from one location to another it is currently possible to rename them using a mapper. So we could rename <code>Foo.java</code> to <code>Foo.java.bak</code>. On occasion it is useful to modify file attributes other than its name in such operations. So we could copy the files to another location and make them read-only in one operation. </p> </blockquote> <h3>Filters extensions</h3> <a name="filters" /> <blockquote> <p> This is partially related to the above action. Filters could be seen as a way to modify the content attribute of a file during a copy/move. It would be preferrable if filtering could be abstracted to use <code>FilteredOutputStream</code>s to perform the content modification. That way new Filter types could be constructed and used during file copy (ie an example would be a Perl FilterOutputStream that allowed you to use perl expressions to transform input). </p> </blockquote> <h3>XML Catalog to load XML Fragments</h3> <a name="catalog" /> <blockquote> <p> When including fragments of XML we are currently forced to use relative paths. However this is sometimes undesirable when a single fragment needs to be used across several projects in several different locations. Instead we could use a Catalog to name the fragment and then each developer would only need to install the fragment once and it would be accessible from all the projects. </p> </blockquote> <h3>i18n the Runtime and tasks</h3> <a name="i18n" /> <blockquote> <p> Look at the feasability of performing i18n on Ant runtime and core tasks. Look at how much work it will be and how useful it would be. Look at utilizing i18n from existing projects such as Avalon. </p> </blockquote> <h3>Embeddor API for Ant</h3> <a name="embeddor" /> <blockquote> <p> Identify different environments in which it would be useful to embed Ant or an Ant-like tool. Identify what these environments are likely to demand in terms of API and support and then design a system that works in these environments without compromising ants core goal (ie a build system). Some suggestions for such an API include; </p> <ul> <li>Pluggable ProjectBuilders to allow building of project from a variety of sources, file, URL, InputStream, SAX etc</li> <li>Pluggable ClassLoader arrangement</li> <li>Ability to set User Properties</li> <li>Ability to add Task/Data/Type definitions</li> <li>Ability to add/remove Listeners</li> <li>Ability to add/remove Loggers</li> <li>Ability to get meta-information about targets (such as name and description)</li> <li>The ability to execute a task and/or targets</li> <li>The ability to add tasklibs</li> <li>The ability to add VFS mount points</li> <li>The ability to manipulate ProjectModel and build it from GUIs</li> <li>A general task engine API</li> </ul> </blockquote> <h3>TypeInfo system</h3> <a name="info" /> <blockquote> <p> Add in the ability to represent tasks using specified meta-info, This would allow generation and manipulation of information such as what attributes are available, what elements are supported etc. </p> </blockquote> <h3>Antdoc</h3> <a name="antdoc" /> <blockquote> <p> This is partially based on the above TypeInfo system. It involves the ability to take the TypeInfo made available and generate documentation for the tasks. This would allow multiple formats of documentaiton to be easily maintained and reduce the chance that documentation gets out of whack. </p> </blockquote> </body> </html> --- NEW FILE: VFS.txt --- From: "Adam Murdoch" <ada...@ya...> Subject: RE: Virtual FileSystem Layer Date: Sat, 22 Dec 2001 12:06:37 +1000 Hi, I've also been doing a bit of work on the VFS. No code yet - instead, I've done a survey of the Ant 1 code, to help get a better idea of what we need the VFS to actually do. I've put together a rough list of the sort of features the current tasks require from the file system. This list is entirely from the task writer's POV. I've ignored the build file writer completely - though, the action list is a good summary of the build file writer's concerns. I've tried to steer clear of assumptions about what is actually going to provide each feature to the tasks, or what the API will look like to the tasks. The goal for doing up this list, was to help identify the features we want to support, and the API that the tasks will use to get at them. This should be largely independent of how we decide to represent the file system in the build files. In addition, it doesn't matter too much whether the list below is complete (I'm sure it isn't), or that the VFS provide every single one of the features. Whatever it doesn't provide, can stay up in the tasks, and be refactored down later. The assumption here is that we do actually want to put together a file system API. I think it's a good idea to at least put together some interfaces, even if the implementation is stolen from somewhere else. Without a doubt, the file system is the most widely used "service" in the current crop of tasks. The API that we choose has to have a good semantic match with what the tasks need to do, so that writing the tasks is easy. The API also has to be general enough to deal with stuff we haven't thought of yet. On that note, I personally think that JNDI might be a touch too general for what we need. So, the features. Note that many of these will be optional - not every feature will be available for every node in the file system. I've used the term "node" to mean both directories and files. I'm not suggesting we actually call them "nodes" in the API. I've used the term "root node" to mean the root of a file system. * Naming - Locate a node by absolute name. - Get the absolute name for a node. - Resolve a name to a node, relative to some base node - like FileUtils.resolveFile(). - Get the relative name of a node, relative to some base node. - Determine the base name (with and without the extension), and extension of the node. - Deal with file systems that are case sensitive, and case insentitive. * Properties - Determine what properties are available on the node. - Determine if the node exists. - Determine the type of node (file vs. directory, could be "has-content" vs "has-children"). - Determine if the node is readable. - Determine if the node is writeable. - Get/set the permissions on the node. This covers things like chmod & chown, making read-only, making executable, etc. * Content - Determine if the node can/does have content. - Get the size of the node. - Get/set the last-modified time of the node. - Get/set the mime-type of the node. - Get/set the encoding of the node. - Get a checksum of the node. - Get content as InputStream. - Get content as Reader. - Set content as an OutputStream. - Set content as a Writer. - Implicit creation of node and its ancestors when content is written. - Compare nodes for equality (last modified timestamp, checksum, bytewise compare). * Hierarchy - Get the parent node of a node. - Get the child nodes of a node. - Iterate over (or visit) the descendants of a node. - With or without a selector. - In various orders - depthwise, etc. - Be able to modify the nodes during traversal. * Modification - Create a new node of a particular type. Create all missing ancestors. - Move, copy, delete a node. - All descendants. - Optional selector. E.g. ignore empty dirs, ignore default excludes, etc. - Optional filter. * Conversion - Convert the node to a java.net.URL. - Make the node content available as a local file (to hand off to external commands). - Get the OS specific *filename* for a node. - Resolve an OS specific *filename* to a node. * File System Types - Local file. - HTTP. - FTP. - Classloader, uses Classloader.getResource(). - Temporary files. - etc ... - Compound file system. Made up of a bunch of mount points. The VFS itself. - Layered file systems (that sit on top of another file system or node): - zip, bzip, jar, tar - filtering - token replacement, etc - Factories for creating and configuring file system root nodes. - Ability to easily add new file system implementations. * Task Container - A mechanism for a task to get hold of the project's root node. - A mechanism that allows a task to create its own private root nodes, without letting it mess with the project's file system, or the file systems of other tasks. - A mechanism for cleaning up all the node InputStream, OutputStream, Reader and Writers opened by a task during its execute() method. Cleaning up files is one thing the current tasks don't do very well at all. Something like this would take care of anything the task did not explictly close. Would include root nodes it created. * Other things - Maybe some way to explicitly close a node and release all resources used by it. - Maybe detection of concurrent updates, in the case of parallel tasks. - Netbeans has an event model in its VFS. Something like this might be useful in dependency management. - nodesets. The replacement for, or generalisation of, FileSet, Path, FileList, etc - A nodeset that contains the descendents of a node that match a selector (like the current FileSet implementation). - A nodeset that contains arbitrary nodes. - An aggregating nodeset. - Custom nodeset implementations. - Reimplement the Ant 1 Fileset, Path and Filelist as adaptors sitting on top of the VFS. - A classloader that can load classes from a node. - etc .. What's missing? What shouldn't be on the list? Adam > -----Original Message----- > From: Magesh Umasankar > Sent: Saturday, 22 December 2001 10:44 AM > To: an...@ja... > Subject: Virtual FileSystem Layer > > > I have been spending some time now on the VFS > layer... Nothing major to report yet, but I just wanted > to sound off so that if I am going down the wrong > route, I correct it right away. > > I evaluated at WebNFS, NetBeansFS (NBFS) and > JNDI. > > 1. WebNFS seems to be going nowhere. It has > been dormant for quite sometime now. Licensing > is rigid. Technically, it doesn't look so bad as it > closely replicates java.io.File's API. But then, > that really gives us very little. > > 2. NBFS looks OK. It has got a few filesystems > already built. There may be some licensing issues, > I don't know, but that shouldn't concern us too > much as, according to Peter, it is Mozilla (I haven't > really check the license out, sorry). But, as far as I > can see, it seems to lack in sophisticated API features > like searching based on attributes, etc., which > we will definitely be needing for the Selector APIs. > > 3. JNDI, by far, beats the above to, in my > evaluation. It is generic enough. We don't have > any licensing issues. It has also become part of > the core JRE (1.4 onwards). Technically, it fits to a T > what we are looking for - virtual file system that > provides search controls, access attributes, > url mounting, etc. Furthermore, there's been > some ground work already done for us at Jakarta/Apache > (Catalina). I have written a SPI for a FTPFileSystem > - though it is in a real crude stage right now. I believe > this is the way to go because Ant's code would be > operating at the (Dir)Context level and we can keep > adding SPIs as we need them. Furthermore, > JNDI has been stable for quite sometime now and > we can depend on a widely used API. > > I don't think JNDI is a heavyweight API for our needs. > It seems to be the only one, so far, which encompasses > at the APIP level, all the new functionalities that we > desire to introduce. > > Let me know if my approach, so far, to go the JNDI > route seems reasonable. > > Cheers, > Magesh > > > > > -- > To unsubscribe, e-mail: <mailto:ant...@ja...> > For additional commands, e-mail: <mailto:ant...@ja...> -- To unsubscribe, e-mail: <mailto:ant...@ja...> For additional commands, e-mail: <mailto:ant...@ja...> --- NEW FILE: original-specification.html --- <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN" "strict.dtd"> <HTML> <HEAD> <TITLE>Ant Specification, version 0.5</TITLE> </HEAD> <BODY> <H1>Ant Specification</H1> <P>Version 0.5 (2000/04/20)</P> <P>This document specifies the behavior of Ant. At this time, this is a working document with no implementation. It is hoped that this specification will lead to a simplier and more consistent implementation of Ant.</P> <P>This document is not intended to be used as an end user manual or user guide to Ant. To adequatly explain the concepts herein in a way appropriate to such a use would potentially complicate this document.</P> <H2>Design Goals</H2> <P>The following are the overall design goals of Ant:</P> <UL> <LI>Simplicity</LI> <LI>Understandability</LI> <LI>Extensibility</LI> </UL> <H3>Simplicity</H3> <P>Ant must be simple to use. Of course, as the definition of simple varies according to the audience of the program. For Ant, since it is a build tool aimed at programmers, the goal is to be simple to use for a competent programmer.</P> <H3>Understandability</H3> <P>Ant must be clearly understandible for a first time as well as a veteran user. This means that a new user should be able to use Ant comfortably the first time and understand how to modify a build file by looking at it. And it should not require much experience with Ant to understand how it works and how to configure it for particular situtations.</P> <H3>Extensibility</H3> <P>Ant must be easy to extend. The API used to extend Ant must be easy to use and the way in which these extensions are located and used by the core runtime should be clear.</P> <H2>Conceptual Overview</H2> <P>This is a conceptual overview of the components used by Ant. Full APIs will be defined later.</P> <H3>Project</H3> <P>The base unit of work in Ant is the <STRONG>Project</STRONG>. A Project is defined by an editable text file and is represented by an object of type <CODE>org.apache.ant.Project</CODE> at runtime.</P> <P>A Project is a collection of <STRONG>Properties</STRONG> and <STRONG>Targets</STRONG>.</P> <H3>Properties</H3> <P>Properties are mutable name-value pairs that are scoped to the Project and held in a table. Only one pair is allowed per name. It is anticipated that this data structure would be of type <CODE>java.util.Properties</CODE> or a type that has approximatly the same contract.</P> <P>Properties can be defined in a hierarchical manner. The order of precidence in this hiearchy is:</P> <UL> <LI>Properties defined on the command line or via a GUI tool</LI> <LI>Properties defined in the text file which defines the project.</LI> <LI>Properties defined in a file in the users <CODE>user.home</CODE> directory</LI> <LI>Properties defined in the installation directory that can be shared by multiple users.</LI> </UL> <P>Note: The current version of Ant allows the System property list to be consulted for a return value if the property list doesn't satisfy the requested property name. As all Java code has access to the system property list via the <CODE>java.lang.System</CODE> class, this functionality is considered to be confusing and to be removed.</P> <P>Note: The current version of Ant allows property substitution to be performed in the project file. This functionality is being removed.</P> <H3>Targets</H3> <P>Targets are ordered collections of <STRONG>Tasks</STRONG>, units of work to be performed if a Target is executed. </P> <P>Targets can define dependancies on other Targets within the Project. If a Target is deemed to be executed, either directly on the command line, or via a dependancy from some other Target, then all of its dependencies must first be executed. Circular depenancies are resolved by examination of the dependancy stack when a Target is evaluated. If a dependancy is already on the stack of targets to be executed, then the dependancy is considered to have been satisfied.</P> <P>After all dependancies of a Target have been satisfied, all of the Tasks contained by the target are configured and executed in sequential order. </P> <H3>Tasks</H3> <P>A Task is a unit of work. When a Task is to be executed, an instance of the class that defines the behavior of the particular task specified is instantiated and then configured. This class implements the <CODE>org.apache.ant.Task</CODE> interface. It is then executed so that it may be able to perform its function. It is important to note that this configuration occurs just before execution of the task, and after execution of any previous tasks, so that configuration information that was modified by any other Task can be properly set.</P> <P>When a Task is executed, it is provided access to the object representing the Project it is running in allowing it to examine the Property list of the project and access to various methods needed to operate.</P> <H2>Task Jar Layout</H2> <P>Tasks are defined within Java Archive files. The name of the JAR determines the name under which the task is known by in the system. For example, if a Task JAR is named mvdir.jar, the task is known to the system as <CODE>"mvdir"</CODE>.</P> <P><EM>Question: Should we say that tasks belong in a JAR file with the .tsk extension?</EM></P> <P>The class within the Jar file that implements the <CODE>org.apache.ant.Task</CODE> interface is specified by a manifest attribute named <CODE>Ant-Task-Class</CODE> in the Jar manifest. An example manifest would look like:</P> <PRE> Manifest-Version: 1.0 Ant-Task-Class: org.apache.ant.task.javac.JavacTask</PRE> <P>When the task is used by Ant, a class loader is created that reads classes from the JAR file. This ensures that there is no chance of namespace collision in the classes of various task JAR files.</P> <H2>Installation</H2> <P>When Ant is installed on a user system, it installs a directory structure with the following form:</P> <PRE><installdir>/ant (unix shell script) /ant.bat /ant.jar /ant.properties /tasks/[task jar files] /docs/[documentation] /README</PRE> <P>Note: Current Jakarta practice is to name the Unix shell script with a .sh extension. This goes against Unix conventions and is unecessary. Testing has shown that the leaving the extension off on Unix will not interfere with the working of the Windows batch file.</P> <P>Note: The ant.jar file has been moved from the lib/ directory and placed alongside the shell startup scripts (which have also been moved out of the bin/ directory). This is because on windows platforms, the .jar file is an executable file of sorts.</P> <H3>Ant Properties</H3> <P>The <CODE>ant.properties</CODE> file contains a list of all the properties that should be set by default when ant is run. In addition there are a few special properties that are used directly by ant. An example of these properties in use is:</P> <PRE> system.taskdir=tasks/ user.taskdir=anttasks/</PRE> <P>The <CODE>system.taskdir</CODE> property sets where the system looks for Java ARchive files containing tasks. If this property defines a relative path, then the path is taken as relative from the installation directory.</P> <P>The <CODE>user.taskdir</CODE> property defines where users can locate Java Archive files containing tasks. If this property defines a realtive path, then the path is taken as relative from the users home directory (as defined by the <CODE>user.home</CODE> system property). Task JAR files in this directory take precendence of those in the system directory.</P> <P>Note: <EM>It has been suggested to add a properties file hook to the command line to roll in props. Pending investigation.</EM></P> <H3>User Preferences</H3> <P>In addition to the Ant installation directory, an <CODE>ant.properties</CODE> file can be located in the user's home directory (as found by the system property <CODE>user.home</CODE>) which can define user preferences such as the location of a user tasks directory. Properties defined in this file take precidence over those set in the installation's <CODE>ant.properties</CODE> file. Such a file could look like:</P> <PRE> user.taskdir=anttasks/ javac.debug=off</PRE> <P>Properties starting with <CODE>"system."</CODE> in the user's <CODE>ant.properties</CODE> file are not allowed and must cause a warning to be thrown.</P> <H2>Project Configuration</H2> <P>Ant's Project text file is structured using XML and reflects the structure of the various components described in the Conceptual Overview.</P> <P>A sample Project file:</P> <PRE><project name="projectname" defaulttarget="main" taskdir="tasks/"> <property name="javac.debug" value="on"/> <target name="main"> <taskimpl ...> ... </taskimpl> </target> </project></PRE> <H3>The Project Element</H3> <P>The <CODE>project</CODE> element has the following required attributes:</P> <UL> <LI><CODE><STRONG>defaulttarget</STRONG></CODE> defining the default target to be executed if no other target is specified when Ant is run</LI> </UL> <P>It also has the following optional allowed attributes:</P> <UL> <LI><CODE><CODE><STRONG>name</STRONG></CODE></CODE> defining a name for this project</LI> <LI><CODE><STRONG>taskdir</STRONG></CODE> defining a directory in which project specific tasks can be located. Tasks in this directory take precedence over those in the either the user taskdir or the installation taskdir.</LI> </UL> <P>The following elements are allowed as children of the project element:</P> <UL> <LI><CODE><STRONG>property</STRONG></CODE> defining a property scoped to the project</LI> <LI><CODE><STRONG>target</STRONG></CODE> defining a target</LI> </UL> <H3>The Property Element</H3> <P>asdf</P> <H3>The Target Element</H3> <P>asfd</P> <H2>Configuration of Tasks</H2> <P>The Task section of the configuration file is structured as such:</P> <PRE> <[taskname] [attname=value] [attname=value]...]> [<[elementname] [attname=value] ...> ... </[elementname]>] </[taskname]></PRE> <P>The taskname is used to find the class of the Task. Once the class has been located and an instance of it created, all of the attributes of the Task are reflected into the task instance using bean patterns. For example, if a Task contains an attribute named "directory", the method named setDirectory would be called with the attribute value cast to the appropriate type desired by the method. <EM>(What to do if the type isn't a file or a simple type, look for the class and see if it has a setString method?)</EM></P> <P>Text blocks contained by the element are added to task using an addText method. <EM>Place an example...</EM></P> <P>For each element contained in the Task definition, an addElementname method is found on the task. The parameter type of the method defines an object that will be loaded and instantiated. The attributes of the element are reflected into the object using bean methods. Any text is set using the addText method. Any elements are recursed in the same fashion.</P> <P>Search order of tasks.... project/user/system</P> <H2>Command Line</H2> <P>The command line utility provided with Ant must support the following allowable syntax:</P> <P><CODE>ant projectfile [prop=value [prop=value...]] [target]</CODE></P> <P>Internally, the command line shell scripts should call the <CODE>org.apache.ant.Main</CODE> class with the following arguments:</P> <PRE>java -Dant.home=installdir org.apache.ant.Main $*</PRE> <P>or its equivalent on the host platform. Note that the ant installation directory is a System property. The above syntax results in ant.home being placed in the System property list.</P> <P>Note: <EM>On unix, finding the directory of the script that was launched is relatively easy. However on Windows, I'm not sure the best way of handling this.</EM></P> <H2>File Naming Conventions</H2> <P>File naming in a cross platform tool is tricky. For maximum portability and understandiblity it is recommended that project files use the following conventions:</P> <UL> <LI>The '/' character is used as a directory seperator</LI> <LI>The ':' character is used as a path seperator</LI> <LI>Only relative paths are used</LI> </UL> <P>However, to allow for maximum flexibility and to allow project authors to use conventions that make sense on their native platform, Ant allows for a representation of file names which has the following rules:</P> <UL> <LI>Directories are seperated by the forward slash ('/') or backwards slash ('\') character.</LI> <LI>File names starting with either of the above directory seperators are considered to be absolute paths.</LI> <LI>On systems that support multiple file roots (e.g. Windows), a file name that starts with a single alphabetical character followed by a colon (':') followed by a directory seperator defines an absolute path where the letter corresponds with a directory root.</LI> <LI>File names starting with any other character are considered to be relative paths. In project files, all relative paths are resolved relative to the directory in which the project file is located.</LI> </UL> <P>Absolute paths are not recommended for build files as they reduce the ability to share a project between u sers or machines.</P> <P>In situtations where a set of filenames need to be specified, such as defining a classpath, both the colon (':') andsemicolon (';') are allowable characters to seperate each filename. The only case that has to be disambiguated is if a user specifies paths that contain windows style absolute paths. In this case, the colon is not treated as a path seperator if the following rules are met:</P> <UL> <LI>The character two places before the colon is either of the allowable path seperators (':' or ';') or if the colon is the second character of the string.</LI> <LI>The character immediately before the colon is a alphabetic character in the range a-z or A-Z.</LI> <LI>The character immediately after the colon is either of the allowable directory seperators ('/' or '\').</LI> </UL> <H2>Scripting Model</H2> <P>Sam, I'm leaving this to you. </P> <H2>Runtime Requirements</H2> <P>The following requirements are system requirements that Ant should have in order to run correctly. We should not bundle in any of these into the distribution of ant.</P> <UL> <LI>JDK 1.1 or greater</LI> <LI>A JAXP compliant parser on the classpath</LI> </UL> <P>Note: <EM>When running on JDK 1.2 or greater, the tools.jar isn't on the classpath by default. There's a few different ways we can take care of this. One is to put it on the classpath in the execute script (I don't like this one). Another is to find the location of tools.jar at runtime and put it on the classpath of class loaders that load in task.jars so that, at least in the scope of the Tasks, the relevant classes are there. </EM></P> <P></P> <P></P> </BODY> </HTML> --- NEW FILE: FunctionalRequirements.html --- <html> <head> <meta http-equiv="Content-Type" content="text/html; charset=windows-1252"> <title>Ant Functional Requirements Document</title> </head> <body> <h2>Ant Functional Requirements</h2> <h3>Roles</h3> <p><b>User: </b>runs Ant with a complete build specification and/or writes Ant build specifications.</p> <p><b>Task Developer: </b>writes/modifies Ant tasks.</p> <p><b>Extensions Developer: </b>develops extensions like a GUI, IDE plugin, (scripting extension?)</p> <p><b>Core Developer: </b>works on the Ant core</p> <h3>Requirements from the Ant User perspective</h3> <p>It should be easy to write a build file for small Java programs. It should be possible to write a build file set for large Java systems. Maintenance of such a set should be easy (e.g. no duplication of information).</p> <p>Every build process contains dependencies (e.g. item A needs B to be available before its own build can start). It should be possible to specify these dependencies in a declarative way.</p> <p>Suppose a working build specification for system A is available. It should be possible for system B to declare dependencies to <i>(modules of?)</i> system A without touching the build specification of A. Ant should be able to handle dependencies between modules which form a DAG.</p> <p>It should be possible to modify details of the actual build (e.g. classpath, used compiler) without the need to change the build specification. This feature is needed when starting Ant (e.g. configuration with command line parameters) and for a subproject build driven by the build of a dependent project.</p> <p>Often similar items have to be built. Therefore it should be possible to provide general <i>(template?)</i> build specifications, and to declare for a concrete item that it should be built according to such a general specification.</p> <p>One result of the build process should be a log which shows what has been done.</p> <h3>Requirements from the task developer perspective</h3> <p>A task should not need to know the structure of a build specification. It would have to provide an interface (not necessarily in the Java language sense) for the Ant core to input the necessary configuration attributes and to execute the task). There should be a standard functionality to allow a task doing log output.</p> <p>An interface (again not necessarily in the Java language sense) should be provided which allows a task to get <i>(and set?)</i> information about it's context in the build process.</p> <h3>Requirements from the extensions developer perspective</h3> <p>The Ant core should be independent from a specific representation of the build specification. It should be possible to create a specification programmatically (thereby allowing the introduction of new representations). The core should do no in- or output itself. Build errors should always lead to throwing an Exception.</p> <p>Access to the current state of a build should be available, and its modification possible.</p> </body> </html> --- NEW FILE: requested-features.txt --- Status: ======= The committers have cast votes on all items (except those that came in too late) and the results are listed below - the next step will be a design phase. This list of items will be summarized into an Ant2 specification soon. I. Things that don't affect the core but are requests for new tasks or enhancements of existing tasks. ====================================================================== [ACCEPTED] for a task doesn't mean that task will be core tasks (or even be supplied by a voter), just that having them (as optional tasks) would be acceptable. * Add a new datatype filterset to group token-filters [ACCEPTED] * make usage of particular filters/filtersets explicit in copy tasks [ACCEPTED] * make facade tasks for things like javac (JikesImpl, ModernImpl etc) One candidate is jar with implementations for fastjar for example. [ACCEPTED] * unify multiple similar tasks to use similar forms (ie all the javacc type tools) [ACCEPTED] * Obfuscating task [ACCEPTED] * Add an <ant> task that will find build files according to a fileset and invokes a common target in them. <anton>? [will need more discussion because of votes by Peter Donald and Stefan Bodewig] [finally ACCEPTED] * Add a JavaApply task that executes a given class with files from a fileset as arguments - similar to <apply>. [will need more discussion because of votes by Peter Donald and Stefan Bodewig] [finally ACCEPTED] * Include some more sophisticated loggers with the Ant distribution - especially for sending emails. Make the existing one more flexible (stylesheet used by XmlLogger). Could be part of the same module tasks would be developed in? [will need more discussion because of vote by Conor MacNeill] [finally ACCEPTED] * make the default logger's output clear, informative, and terse. Actually, this is a little bit abstract, but doesn't apply to the core either. [will need more discussion because of vote by Conor MacNeill] [REJECTED - vetoes by Conot MacNeill and Stefan Bodewig] * Better docs. More examples. Tutorials, beginner documents, reference sheets for tasks, printable version. [ACCEPTED] * RPM task. [ACCEPTED] * add an attribute to <property> to read in an entire file as the value of a property. [will need more discussion because of vote by Peter Donald] [REJECTED - veto by Peter Donald] * Task for splitting files (head/tail/split like functionality). [ACCEPTED] * Task to create XMI from Java. [ACCEPTED] * socksified networking tasks, SSH tasks. [Peter Donald expressed some legal concerns that might be overcome, depending on the implementation] * a reachable task that works much like available for network URLs. [ACCEPTED] * make PATH handling consistent. Every task that has a PATH attribute must also accept references to PATHs. [will need more discussion because of vote by Stefan Bodewig] [REJECTED - vetoes by Conor MacNeill, Glenn McAllister and Stefan Bodewig] * Task to extract classes from a JAR file that a given class depends on. Based on <depend> or IBM's JAX for example. [ACCEPTED] * Unify <available> and <uptodate> into a more general <condition> task, support AND/OR of several tests here. [will need more discussion because of vote by Peter Donald] * jsp-compilation task Sounds like a candidate for a facade task. [ACCEPTED] * URL-spider task that checks links for missing content or server errors [ACCEPTED] II. Abstract goals that need to be abstract until we get into design decisions. ====================================================================== During discussion it became obvious, that some things from this list are goals for Ant and some should be guidelines for developers, therefore there are two flavors, [ACCEPTED] and [ACCEPTED AS GUIDELINE]. * Provide a clear mission statement for Ant. [ACCEPTED] * Main goals: Simplicity, Understandability, Extensibility [ACCEPTED] * remove magic properties if at all humanly possible [ACCEPTED] * remove as much dependency on native scripts as possible. [ACCEPTED] * clean object model (ie Project/Target/Task) [ACCEPTED] * good event model to integrate well with IDE/GUI/whatever [ACCEPTED] * use a consistent naming scheme for attributes across all tasks [ACCEPTED] * keep build file syntax as compatible to Ant1 as possible - i.e. don't break something just because we can. [ACCEPTED] * keep the interface for Tasks as similar to the one of Ant1 as possible - i.e. don't break something just because we can. [ACCEPTED] * Ant should be cancelable [ACCEPTED] * no commit of new features without documentation [ACCEPTED AS GUIDELINE] * no commit of new features without testcases [ACCEPTED AS GUIDELINE] III. Things that are simple, easy to implement, where we expect the committers to agree ====================================================================== * namespace support so different concerns can occupy different namespaces from ant (thus SAX2/JAXP1.1) [ACCEPTED] * Java2 [ACCEPTED] * remove all deprecated methods, attributes, tasks [ACCEPTED] * allow all datatypes to be defined anywhere - i.e. as children of project as well as of target. [ACCEPTED] * make properties fully dynamic, i.e. allow their value to be reassigned [will need more discussion because of vote by Glenn McAllister and Conor MacNeill] [finally ACCEPTED] * unify the namespace of all data types (ie properties + filesets + patternset + filtersets). [ACCEPTED] * add a user defined message if a target will be skipped because the if/unless attribute says so. [ACCEPTED] * allow user-datatypes to be defined via a <typedef> similar to <taskdef>. [ACCEPTED] IV. Things we probably agree upon but need to discuss the details or decide between several possible options. ====================================================================== [ACCEPTED] means, the goal/idea is fine, not that a decission on a particular implementation has been made. * The ability for GUI/IDE tools to integrate easily with object model without reinventing the wheel and writing their own parser (which antidote was forced to do). Two suggested solutions were allowing GUI developers to extend object model (ie GUITask extends Task) or to have Task as interface (ie GUITask implements Task). This way the GUI tasks could be W3C DOM Elements, have property vetoers/listeners etc. [ACCEPTED] * support for numerous frontends - from command line over GUI to servlets corollary of the above? [ACCEPTED] * Fully interpreted at runtime. This almost requires some form of abstraction/proxy that stands in place of tasks till it is interpreted. This can be hashtables/simple dom-like model/whatever [ACCEPTED] * provide utility classes to aid in building tasks. ie like up-to-date functionality abstracted Need to become more specific here. [ACCEPTED] * make ant-call a low cost operations so it can certain optional/template-like operations corollary of "fully interpreted at runtime"? [ACCEPTED] * allow facilities to build projects from multiple sources. ie CSS+xml or XSLT+ XML or Velocity+text or database or from inside jars or normal build.xmls etc. allow the project tree to be built dynamically. [ACCEPTED] * move to a system that allows docs to be generated - doc snippets should be included with the tasks they document. Which DTD? Which tools for generation? [ACCEPTED] * allow tasks to be loaded from jars. tasks should be indicated by either xml file in TSK-INF/taskdefs.xml or manifest file. [ACCEPTED] * allow documentation to be stored in .tsk jars corollary of the two points above? [ACCEPTED] * better scripting/notification support so the hooks are available to send notifications at certain times. Which hooks and where? [will need more discussion because of vote by Peter Donald and Simeon Fitch] [REJECTED - vetoes by Conor MacNeill, Peter Donald and Simeon Fitch] * separate tasks into .tsk jars somehow. (Probably via function - ie java tasks, file tasks, ejb tasks). Decide on categories. [will need more discussion because of vote by Conor MacNeill] [finally ACCEPTED] * make separate build files easy (ala AntFarm) and importing different projects a breeze [ACCEPTED] * provide support for user defined task configurations - i.e. give users the ability to specify a default value for attributes (always use debug="true" in <javac> unless something else has been specified). Three ideas so far: a CSS like language, a <taskconfig> element, properties following a specific naming scheme. [ACCEPTED] * support more control over the properties that are going to be passed to subprojects (modules) [ACCEPTED] * Ask for a new CVS module for Ant tasks. We need to define rules for this to work - maybe the rules proposed for the commons project could give us a start. [will need more discussion because of vote by Conor MacNeill] [REJECTED - vetoes by Conor MacNeill and Glenn McAllister] * It should be possible to modify details of the actual build (e.g. classpath, used compiler) without the need to change the build specification. Do build.compiler and build.sysclasspath cover everything or do we need to add more stuff like this? [will need more discussion because of vote by Conor MacNeill] [REJECTED - veto by Conor MacNeill] * Task to prompt for user input. Does affect core as we need a means to request input from the Frontend. [ACCEPTED] * Add cvs login feature. Requires handling of user input. [ACCEPTED] * Easier installation process. GUI - maybe webstart from the homepage. This includes asking the user whether he wants to use optional tasks and downloads the required libs. Automatic upgrades and so on. Self-extracting jar installer: java -jar jakarta-ant-1.3-bin.jar. Prompts for destination directory, extracts archive, fixes all text files with fixCRLF task; on UNIX, makes scripts executable. Could also modify ant scripts with the location of ANT_HOME. [ACCEPTED] * Logo for Ant. [ACCEPTED] * detach Ant from System.err/.in/.out. Beware of problems with spawned processes. [ACCEPTED] * better subproject handling Whatever that means in detail. [will need more discussion because of vote by Conor MacNeill] [REJECTED - vetoes by Conor MacNeill and Stefan Bodewig] * build files should be declarative in nature [ACCEPTED] V. Things we probably don't agree on. ====================================================================== [DISC] Datatypes ---------------- * Allow mappers to be genericised so that particular features can be modified during mapping. Something similar to <fileset ...> <include name="*.sh"/> <mapper type="unix-permissions"> <param name="user" value="ant"/> <param name="group" value="ant"/> <param name="mod" value="755"/> </mapper> </fileset> [REJECTED - vetoes by Stefan Bodewig and Conor MacNeill, not enough positive votes anyway.] * Allow include/exclude tow work with multiple characteristerics of a file. ie include into fileset if file is readable, modified after 29th of Feb, has a name that matches patter "**/*.java" and the property "foo.present" is set. Something similar to <include> <item-filter type="name" value="**/*.java"/> <item-filter type="permission" value="r"/> <!-- could optionally be directory/or some other system specific features --> <item-filter type="type" value="file"/> <item-filter type="modify-time" operation="greater-than" value="29th Feb 2003"/> </include> [ACCEPTED] * provide datatypes through property tag and remove need for separate free standing entities. ie <property name="foo"> <fileset dir="blah"> <include name="*/**.java" /> </fileset> </property> [REJECTED - only one +1 vote] * provide support for non-hardwired (ie loadable) low-level components (mappers/itemset-filters/converters). Allow them to be loaded in either... [truncated message content] |
