ant-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "James Cook" <jimc...@iname.com>
Subject RE: Functional Requirements Document
Date Sat, 20 Jan 2001 18:51:57 GMT
I jotted some thoughts down regarding the requirements of a Task (and the
Task developer). Interested in feedback. Peter, I have this in HTML format
that you can grab if you want to put it into the online functional
specification. (http://www.visualxs.com/products/frantic/index.html)


jim

=============================
Task Axioms

A Task should remain a very easy class for a developer to write. One of
Ant's primary successes is the ease with which it may be extended. Any
future burdens on the Task developer should be kept to a minimum.

1. Task developers will not have to go through an external class to access
its data.

In Ant 1.x the Task developer accessed values of the Task's attributes and
properties as if they were set according to the JavaBeans standard. In fact,
this is exactly what happened. The proxy class invoked the appropriate
setXXX methods that related to the values read from an XML file.

The Servlet API is an example of a system where the Servlet developer must
"ask" for its attributes through an external class. Because this can be
burdensome or repetitive to the Servlet developer, a long list of techniques
and helper classes have been documented to automate this behavior. In Ant,
we have simply chosen to make automatic property discovery the default
behavior.

2. A Task must identify the name of all modifiable properties.

This rule is not found in Ant 1.x and it is a primary barrier preventing
Ant's integration in a GUI environment. In order for someone (or a GUI
program) to present the Ant user with a list of properties to set, they must
first know what properties can be set.

It is not sufficient to claim that all setXXX methods can be inspected to
determine all of the properties that can be set externally. This would put a
burden on the Task developer to refrain from using setXXX methods for
internal properties. Where a Task developer defines these properties must be
defined. Some examples follow:

a. The Task developer identifies the properties for the Task as a return
value for a specific method, such as getProperties().

b. The Task developer uses an external file (ala the Task list file) to
specify the properties.

c. The properties are encoded in JavaDoc for the Task. This approach could
be extended to allow Task usage instructions to be generated using a custom
Doclet. This Doclet could also be used to generate the external file
discussed in the previous point.

3. A Task must be able to return resolved and unresolved values of its
properties.

Although this shouldn't be the responsibility of the Task author, any proxy
class or Task superclass must be able to provide these values. A GUI tool
must be able to present the unresolved form of a property to the user
creating the build script. The Task itself should be oblivious to the
unresolved form, and should only know the resolved form.

By resolved and unresolved, we refer to the following examples:
  Unresolved: message = "The ${animal} jumped over the moon.
  Resolved: message = "The cow jumped over the moon.

> -----Original Message-----
> From: Peter Donald [mailto:donaldp@apache.org]
> It is 90% the right way to go IMHO ;) I will add it to CVS and
> look closely
> at it a bit later and see if I can hack on some bits ;)


Mime
View raw message