<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<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:secret@some.server.com: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:secret@some.server.com: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>
distrib
>
Scientific%20Linux
>
5x
>
x86_64
>
media
>
main
>
by-pkgid
>
384bb5c8febd3510675147b31bd8778e
>
files
>
6
