Mailing-List: contact ant-dev-help@jakarta.apache.org; run by ezmlm
Precedence: bulk
Reply-To: ant-dev@jakarta.apache.org
Message-ID: <3AE607C2.7090701@arielpartners.com>
Date: Tue, 24 Apr 2001 19:09:54 -0400
From: Craeg K Strong <cstrong@arielpartners.com>
User-Agent: Mozilla/5.0 (Windows; U; Windows NT 5.0; en-US;
 0.8.1) Gecko/20010323
MIME-Version: 1.0
To: ant-dev@jakarta.apache.org, partners@arielpartners.com
Subject: Recursive property resolution, inside out: Possible Solution [LONG]
Content-Type: text/plain; charset=us-ascii; format=flowed
Content-Transfer-Encoding: 7bit

Hello:

This is in response to J. D. Fagan's request for a recursive property 
resolution feature in Ant2. We here at Ariel are quite familiar with the 
problem JD is trying to solve and have created a program that solves it 
(and other problems) rather nicely, without requiring any changes to 
Ant. We call it "propgen," for lack of a better name.

Propgen is a stand-alone java program that reads and writes property 
files in both java.util.Properties format and XML. We have created a 
propgen Ant task that integrates propgen with Ant.

The XML property files follow a trivially simple DTD and are used to 
parameterize XSL transformations. The idea is that you pass in both an 
input XML file and an XML parameter file. The parameters help keep your 
XSL stylesheet clean and generic.

Propgen is useful in the following environment:

- You are part of a development team with several developers.
- Some of your developers may use different operating systems.
- You build similar applications for multiple clients, and/or multiple 
flavors of the same application (development, test, production).
- You would like to avoid an explosion of Ant buildfiles, shell 
configuration files, etc. etc.

If this does not describe you, read no further. Otherwise, read on...

There are (at least) two main techniques for accomplishing this goal:

1. Generating Ant sub-buildfiles with XSL a la imake (Alexandria uses 
this technique).
2. parameterizing your buildfiles and passing in the values as properties.

Of course, the techniques may be used in combination.

One Ant convention that is useful in this context is to bootstrap 
toplevel buildfiles by loading in a user-specific properties file, such 
as ${user.home}/ant-global.properties. This is good, but not enough. We 
have identified several axes along which the value of a property may vary:

- user specific {For example: Joe's tree starts at c:\dev; Mike's tree 
starts at /home/mholden/ade}
- machine type specific {For example: ORO requires \\ for a regexp path 
separator on win32 and / on unixen}
- site specific {properties that indicate the structure of your 
development area. For example: SiteA stores documents in 
/repository/archive, RemoteSiteB stores them in C:\archive, ClientC 
stores them in Documentum.}
- Target specific {For example: by parameterizing the name of the 
transformer used to produce two different web pages, you can use the 
same buildfile for both.}

Obviously, many properties are defined in terms of others. For example, 
${dtdFiles} may be defined as ${top}/com/arielpartners/dtd, where ${top} 
has a user-specific value.

What you (the buildmeister) would like to do is to start 
simple--creating a single property file containing all properties, with 
some defined in terms of others. Then you might split the properties 
into multiple files as necessary along user/machine/site/target/etc. 
lines, creating progressively more property files to support a more 
complex environment.

Propgen combines multiple property files, resolving properties as 
needed, to produce a single set of fully resolved properties to pass to 
ant (and/or XSLT or whatever). You specify the files in order, via a 
property path. The property path functions in precisely the same manner 
as a java class path. That is, when looking to resolve a property, the 
first value found while traversing the property path wins.

In this way, we can support all required flexibility by specifying 
different property paths. Each user can have a default property path for 
the environment they use the most often, plus special property paths for 
other situations.

The "antified" version of propgen consists of five small java classes, 
all told. It uses SAX to parse XML property files. I would supply some 
examples of our property files, but this email is already too long. If 
the group would like, I will do so.

Well, that's it. Is this something that you would find useful? Have you 
run into the problems we ran into? Have you solved them in a different 
way? Would propgen functionality be useful as part of the jakarta-ant 
project? Where would it belong--possibly in the category of "optional 
useful ant add-ons," a la Antidote and antshell? All comments are welcome.

Regards,
--Craeg Strong
Ariel Partners LLC