Created attachment 12756 [details]
Zip of the project reflecting my suggestion: unzip and README.txt, please

Abstract:
=========

<checkToken> is a custom ANT-Task that can be used together with the
tokenfiltering of
the <copy>-task. It fails if at least one tokens is not supplied a value and
warns if values are supplied without matching tokens.

It can also be used to assure that different properties files contain the same
set of keys.

This .tar.gz is intended to illustrate the enhancement request to ANT that I made.

I assume that you read this after having seen my enhancement request in Bugzilla and
unpacked the attached checkTokens.tar.gz, so you know about ANT.
If not check out http://ant.apache.org.

Holger Krauth (Holger.Krauth@danet.de/Holger.Krauth@web.de)


Background Tokenfiltering:
==========================

The copy task inside ANT has a built in feature called tokenfiltering.
If switched on, it parses all files to be copied for tokens and replaces
all tokens with values found in the fiven filtersfile.

Thus, you can define your application's "demo.properties" as a pattern, e.g.
containing
the line "port=@_port_@", the latter "port" being the token.
(The default token delimiters '@' are inappropriate if there is a comma separated
list of smtp addresses somewhere in your properties files!
Thus I chose to take '@_' and '_@' repectively).

Having 2 filtersfiles "test.properties" and "production.properties"
containing the line "port=2222" and "port=1111" enables you to produce (via ANTs
copy)
a "demo.properties" containing either "port=2222" or "port=1111" depending on
the filtersfile passed when copying with tokenfiltering.

A nice side effect is that all environment specific settings are gathered in one
single
filtersfile.


Motivation:
===========

We use tokenfiltering a lot to build applications for different environments:
local, inhouseTest, testSystem, production...

For efficient usage of tokenfiltering I was missing
(1) an error message if a tokens value could not be found in a filtersfile
(2) a warning if a filtersfile contains a tokenvalue that is never used

If you need to be convinced about the necessity:
Imagine a property connect.as.uid= being empty due to tokenname mistyping just
for the production
built of your application and to connecting to a database a anonymous and so
never retrieving the
whole data but just what anonymous can so and so due to missing values
assuming... Contact me
for colourful examples from real life.


Contents:
=========

./README.txt
./build.xml
./runDemo.sh

./src/java/jakarta/contribution/suggestion/ant/Demo.java
./src/java/jakarta/contribution/suggestion/ant/CheckTokens.java

./src/build-patterns/demo.properties

./src/build-environments/test.properties
./src/build-environments/production.properties

./src/test/jakarta/contribution/suggestion/ant/CheckTokensTest.java

./lib/ant-1.5.jar
./lib/junit-3.8.1.jar
./doc/api/index.html


Running Demo:
=============

This mini-project contains a Demo.main() being:

        Properties p = new Properties();
        p.load(ClassLoader.getSystemResource("demo.properties").openStream());
        System.out.println("Connecting to " + p.getProperty("host") + ":"
                + p.getProperty("port"));

The shippend build.xml can build this demo application for environment "test" or
"production":

$ ...checkTokens/ > ant test.deploy
[...]
$ ...checkTokens/ > runDemo.sh
Connecting to testhost:2222

$ ...checkTokens/ > ant production.deploy
[...]
$ ...checkTokens/ > runDemo.sh
Connecting to PRODUCTION-HOST:1111


These build targets are depending on the <checkTokens> task which can easily be
provoked to fail:
Open the ./src/build-environments/production.properties and change the line
port=1111
to be
CORRUPTport=1111


Building again will end up like:
$ ...checkTokens/ > ant production.deploy
[...]
checkTokens:
[checktokens] production.properties contains unused value 'CORRUPTport'!
[checktokens] production.properties provides no value for 'port' from
demo.properties!

BUILD FAILED
file:/home/hokr/projects/checkTokens/build.xml:83: There were errors.


Here "contains unused" is just a warning, whereas "provides no value" is an error.


For further details, please refer to the code.
or send me your comments, remarks, suggestions to Holger.Krauth@danet.de

Thank you for reading.

Regards,
  Holger Krauth