JWare/AntXtras Foundation
                      Version 0.5, Release June 2005
                   ------------------------------------

                            
This document contains the major AntXtras version change notes. For the most
recent information, visit the AntXtras website at http://www.jware.info/

------------------------------------------------------------------------------
JWare/AntXtras v0.5 (June-12-2005) major changes since v0.5b4:

=> Added a new userguide section for standard AntX value uri handlers. See
   online at: http://www.jware.info/AntXtras/docs/userguide/valueuris/


=> Fixed problems with Ant 1.6.3 changes to CallTarget and some of AntX's
   own callXYZ flowcontrol tasks. AntX is now verified against the 1.6.2,
   1.6.3, and 1.6.5 Ant releases.


=> Fixed <antversion> condition to handle beta releases of the Ant product.


=> Fixed <isreference> condition to work for objects loaded by a classloader
   different from its own when the 'class' and 'kindof' parameters are used.


=> Fixed <foreach mode="local"> when used inside of a macrodef and included
   macrodef attributes as part of its definition. BACKWARD-COMPATIBILITY
   ISSUE: it is now illegal to name a local foreach loop (naming was not
   a requirement for local loops, and was the root of the problems with 
   macrodefs).


=> Fixed valueuris.xml (now moved to antx/valueuri/antlib.xml) to use the
   "ant:current" namespace for AntX components instead of trying to load
   the components itself. The file now works even if AntX is loaded with a
   custom classpath or classloader. (Caller must now ensure that AntX is
   loaded before this antlib is used.)


=> Enhanced general transform option to support new "trim" and "stripws"
   selections. Changes are also inherited by the various transform value
   URI handlers.

   Example Usage:
        <copyproperty name="fu" value="  Fu Bar  " transform="trim"/>

        <foreach i="module" list="${modules}"...>
            <property name="moduleid" value="$stripws:@(module)}"/>
            ...


=> Fixed the <evaluatelogged> task to support a new -resulttype that lets
   you use variables for results instead of write-once project properties. 
   Now you can use <evaluatelogged> from a macrodef that is called repeatedly
   with the same (or a defaulting) result prefix. Legal values for the
   resulttype are: "property"(default), "variable", and "reference".

   Example Usage:
        <evaluatelogged resulttype="variable" prefix="emma"
            interpreter="emma-checker" maxwarnings="1"/>
        <domatch var="emma.result">
            ...


=> Fixed <evaluatelogged> to support nested <parameter> elements. These
   simple key-value pairs are passed verbatim to the interpreter.

   Example Usage:
        <evaluatelogged prefix="findbugs"
            interpreter="findbugs-checker" maxwarnings="10">
            <parameter name="format" value="xml"/>
            <parameter name="medium=error" value="yes"/>
            <parameter name="low=warning" value="yes"/>
        </evaluatelogged>


=> Moved valueuris.xml to antx/valueuri/antlib.xml. BACKWARD-COMPATIBILITY
   ISSUE: you should update your scripts to use this new antlib file. The
   beta valueuris.xml file has been removed from the final distribution.


=> Refactored the valueuri implementations into their own package tree; 
   please update your antlibs with the new package names. See the builtin
   antx/valueuri/antlib.xml (used to be valueuris.xml) file for the new
   locations of various handlers.


=> Enhanced the <strings> data type to allow nested references to other
   <strings> (like most other set data types). For now, the referred-to
   strings list is inserted when the <strings> instance is parsed. AntX 
   0.6 will support a "dynamic" option like the standard <propertyset>.

   Example Usage:
        <strings id="thirdparty.coverage.filters">
            <string value="-org.*"/>
            <string value="-junit.*"/>
            <string value="-com.ibm.*"/>
        </strings>
        
        <strings id="application.coverage.filters">
            <string value="+${packagestem}*"/>
            <string value="-${packagestem}*.tests*.*"/>
            <strings listref="thirdparty.coverage.filters"/>
        </strings>


------------------------------------------------------------------------------
JWare/AntXtras v0.5b4 (April-10-2005) major changes since v0.5b3:

=> This is scheduled to be the last beta release of the AntX-0.5. The next
   release will be the final 0.5 release.


=> BACKWARD-COMPATIBILITY ISSUE (from v0.5b3):
   The <true> component is now an AntX presetdef for <equals value="true">
   as used (very very very often) with the <domatch> to simulate an if-else
   construct. In the previous beta <true> was a synonym for the <domatch>
   <meets> element.

   Example Usage:
        <macrodef name="fubar">
            <attribute name="files"/>
            ...
                <domatch value="${$notwhitespace:@{files}}">
                    <true>
                        ...[do a-b-c]
                    </true>
                    <otherwise>
                        ...[do x-y-z]
                    </otherwise>
                </domatch>


=> Several new value URI handlers have been included in this AntX release.
   Please see the online overview for a general description of the new
   handlers. Now you can also "pipeline" value uris using the "|" between
   uris; the result of the first evaluation is passed as the fragment to
   the second and down the line. Only the first uri can have an explicit
   fragment.

   Example Usage:
        <echo message="Currently: ${$now:|$uppercase:}"/>

        <echo message="It Took: ${$var:duration|$duration:}"/>

        <property name="START.label"
           value="${$datetime:|$escapehtml:?uppercase}"/>


=> Added an "includesource" parameter to the <checkpoint> task. Omitting
   source information (target's name) makes it easier for generic dashboard
   update scripts to parse checkpoint files.

   Example Usage:
        <checkpoint message="${PASS}: ${duration}" includesoure="no"
                    tofile="${dashboard.dir}/compile-apis.status"/>


=> All failed assertion messages are now prefixed with a "Failed assertion: "
   lead string. This makes it easier to identify why a build or test run
   failed from the console messages.

   Example Usage:
       (If this fails):
        <assert isdirectory="${no-such-dir}" 
                msg="Directory ${no-such-dir} exists"/>
                
       (Old Output was)
         [assert] Directory ${no-such-dir} exists

       (New Output is)
         [assert] Failed assertion: Directory ${no-such-dir} exists.


=> Reworked <manageprinters> so you can include it in a regular antlib file.
   Also, you can now include all printer components including <printer> in a
   SAMS run configuration script.

   Example Usage:
        <antlib>
            <manageprinters>
                <printer id="error.printer" 
                    classname="com.idaremedia.antx.print.ErrorsPrinter">
                    <forclass name="java.lang.Exception"/>
                    <forclass name="com.idaremedia.antx.ErrorSnapshot"/>
                </printer>
                ...
            </manageprinters>
            ...
        </antlib>


=> Exported a new <evaluatelogged> utility task that lets you process either
   the set of logged messages captured by one of the AntX capture tasks
   like <capturelogged> or a single log file for some application defined
   criteria. The evaluation's result is summarized in a single "result" 
   property that will be set to one of three possible values: "CLEAN",
   "PROBLEM", or "FAILURE".
   
   Example Usage:
        <typedef name="javadoc-checker" 
            classname="com.idaremedia.antx.capture.JavadocLogInterpreter"/>
        ...
        <target name="docs" depends="...">
            <capturelogs importantfrom="info">
                <javadoc ....>
                <evaluatelogged interpreter="javadoc-checker" prefix="_doc"
                    maxwarnings="50" maxerrors="0"/>
            </capturelogs>
            <domatch property="_doc.result">
                <equals value="PROBLEM">
                    ...
                <equals value="FAILURE">
                    ...
            </domatch>
        </target>

   

=> Enhanced <assert> to support, as valid short hand options, any 
   client-supplied condition types that support the AntX URIable interface.
   This means <assert> now supports the other AntX-based project conditions
   automatically.

   Example Usage:
        <typedef name="isweekend" 
            classname="com.mystuff.conditions.IsWeekend"/>
        ...
        <assert isweekend="${DSTAMP}" msg="Backup only on weekend"/>


=> Added a new <batchchecks> utility taskset that lets you batch the execution
   of a series of assertions or fixture checks into a single (final) pass
   or fail. You would use this taskset to iterate through a set of required
   properties en-masse while linking any failures to a specific feedback
   message.
   
   Example Usage:
        <target name="preinit">
            <batchchecks>
                <fixturecheck isset="module-root" 
                    msg="The 'module-root' property is defined."/>
                <fixturecheck isset="module-name"
                    msg="The 'module-name' property is defined."/>
                ...
            </batchchecks>
            ...
        </target>


=> Added a standalone <isdirectory> condition to match the <assert> task's
   shorthand isdirectory parameter. (Note that <isdirectory> is just a 
   convenient wrapper for the standard Ant <available> task.)

   Example Usage:
        <target name="preinit">
            <assert msgid="err.invalid.environ">
                <isdirectory location="${BUILDTOOLS_HOME}"/>
                <isdirectory location="${workspace}/outputs"/>
                ...
            </assert>

------------------------------------------------------------------------------
JWare/AntXtras v0.5b3 (January-05-2005) major changes since v0.5b2:

=> Enhanced <copylogged> to accept file URLs in addition to regular
   file system paths.

=> Enhanced both <call> and <callforeach> to accept macrodefs as callable
   targets. If you specify one or more macros, the flowcontrol task's mode
   is automatically set to "local". Macrodefs are significantly faster than
   local targets when you do not need to block the fixture modifying side
   effects of the target on the current project.

   Example Usage:
        <macrodef name="synclibs">
            ...
        <macrodef name="checkout">
            ...
        <macrodef name="merge">
            ...
            
        <call macros="synclibs/>
        <callforeach i="module" list="a,b,c" macros="checkout,merge"/>


=> Enhanced the <foreach> task to support a "local" mode. If you set the
   mode local, the <foreach> task's nested elements are executed as part
   of a local macrodef *within the current project*. This option is much
   faster than an isolated-project execution if you do not need to block
   the effects of the nested tasks on the current project.

   Example Usage:
        <foreach name="preparesource" i="module" list="a,b,c" mode="local">
            <cvs command=".../>
            <copy .../>
        </foreach>


=> Enhanced <assign> to handle float numbers for all simple arithmetic
   operations (+,++,-,--). In order to ensure a simple fixed decimal result
   string, you must set the "transform" parameter to "decimal" (new). This
   option formats the final float string so it contains three decimal places
   at most; otherwise, the string is assigned whatever the double's
   default "toString" method returns.

   Example Usage:
        <assign var="pi-1" value="3.14"/>
        <assign var="pi-1" op="-" value="1" transform="decimal"/>
        <assert equals="2.14" variable="pi-1"/>


=> Enhanced <assign> to handle two simple string manipulation operations:
   strcat (+s) and strlen (len). These operations are useful when building
   strings with optional parts.
   
   Example Usage:
        <assign var="co.cmd" value="checkout"/>
        <do if="scrub.empties">
            <assign var="co.cmd" op="+s" value=" -P"/>
        </do>
        <assign var="co.cmd" op="+s" value=" ${moduleid}"/>


=> Enhanced <protect> with a new "againstall" option. When turned on, the
   <protect> will capture *any* kind of runtime exception for processing
   not just Ant-specific build exceptions.
   
   Example Usage:           
        <protect haltiferror="no" againstall="yes">
            <throw-generic-runtime-exception/>
        </protect>


=> The <default> element of the AntX <domatch> flow control task now has a 
   synonym <otherwise>. Which of the two elements you use depends on how the
   <domatch> is being used. Typically, if you use a <domatch> to reflect an
   if-[elseif-]else flow, you would use the <otherwise> construct instead
   of the more switch-like <default>.
   

=> Added support for the hard limit stop "maxloops" option to both <foreach>
   and <callforeach>. This option (as originally used in the <dowhile> loop)
   lets you guard against runaway loops.
   
   Example Usage:
        <fileset id="xml.sources".../>
        <callforeach i="file" files="xml.sources" maxloops="20".../>


=> Added a "msg" option to the <never> task so you can include a custom
   script message with the generated Error.
   
   Example Usage:
        <never msg="This is really really broken"/>


=> Enhanced <callinline> with a new "super" parameter to specify a call to 
   an overridden imported target of the same name as the current target.
   
   Example Usage:
        [In 'imported.xml' script]
        <project name="imported"...>
            <target name="init">
                ...
            </target>
        </project>
        
        [In 'importing.xml' script]
        <project name="importing"...>
            <import file="imported.xml"/>
            <target name="init">
                <echo message="Insert local bits here..."/>
                <callinline super="imported"/>
            </target>
        </project>


=> Added a new fixture definition task <datadef> that lets you dynamically
   add data items to the current project without prematurely installing
   a global id (reference) to an unconfigured proxy object.

   Example Usage:
        <target name="might_never_be_called">
            <datadef name="antlibs.in" tellproperty="antlibs.merged">
                <strings suffix="/antlib.xml">
                    <string value="${antxtras.src}"/>
                    <string value="${sams.src}"/>
                    <string value="${antunit.src}"/>
                </strings>
            </datadef>
            ...
        </target>

------------------------------------------------------------------------------
JWare/AntXtras v0.5b2 (October-07-2004) major changes since v0.5b1:

=> Bug [1034224] fixed by tweaking the standard AntX condition antlib to use
   "is" in front of all our condition names. This (better) ensures our
   conditions do not conflict with regular task and/or type names. See the
   QuickStart Guide for the updated names.


=> The auto-install AntX antlib.xml now works even if AntX is put in its
   own namespace. It is no longer necessary to call <install-steprunner>
   explicitly.


=> The manager task for value URIs has been renamed <manageuris> to be
   consistent with the existing AntX fixture manager tasks. A sample
   configuration file com/idaremedia/antx/valueuris.xml has been added; it
   contains a listing of all the builtin AntX value URI handlers. You can
   use valueuris.xml as-is, or as a starting point for your own scripts.


=> Fixed builtin value URI handlers to understand "@(propertyname)" as a
   local substitute for ${propertyname}. This lets you embed regular Ant
   property references (recursively) into value URIs.

   Example Usage:
        <manageuris action="enable">
            ...[Turn on value-URIs; see User Guide for options]
        
        <property name="endtime" value="@($var:endtime)"/>
        <echo message="Finished: ${$datetime:@(endtime)}..."/>

        <property name="MIT.lic" value="MIT/latest"/>
        <property name="license" value="${$default:license?@(MIT.lic)"/>


=> Updated the <do> taskset to support a generic "is true" and "is false"
   condition, including results of value URIs. This new condition supersedes
   the individual "if*" and "unless*" conditions as the most flexible way
   to control when a set of tasks get executed based on the existence (or
   not) of certain properties. The existing individual tests are still
   perfectly valid options (especially if you decide not to use AntX's
   value URIs).

   Example Usage:
        <manageuris action="enable">
            ...[Turn on value-URIs; see User Guide for options]

        <do true="${$filenotempty:@(varsconf)}">
            <.../>
        </do>


=> Updated the <do> taskset to support a generic "meets criteria" execution
   condition. This allows you to link the execution of a set of tasks to a 
   custom condition that is as complex as you make it. The named test must
   one of the AntX rule types (like a <tallyset> or the new <criteria>), or
   any component that implements the Ant "Condition" interface.

   Example Usage:
        <manageuris action="enable">
            ...[Turn on value-URIs; see User Guide for options]

        <tallyset id="create-apis">
            ...[Test whether javadoc needed]
        </tallyset>

        <do test="create-apis">
            <javadoc .../>
        </do>


=> Updated the <domatch> task to support a generic "meets criteria" choice.
   A criteria choice refers to an existing (named) condition like a <tallyset>
   or <criteria> that is evaluated when the choice is tested. If the condition
   evaluates true, the choice's tasks are executed. The targeted condition
   can use global and overlaid fixture information to determine its result.
   
   Example Usage:
        <tallyset id="is-BIG-state">
            <equals match="Texas" property="name"/>
            <issettrue property="big"/>
        </tallyset>

        <tallyset id="is-sml-state">
            <equals match="Maine" property="name"/>
        </tallyset>

        <foreach i="name" list="Texas,Maine,Utah"...>
            <domatch>
                <meets criteria="is-BIG-state">
                    ...
                <meets criteria="is-sml-state">
                    ...
                <default>
                    ...
            </domatch>
        </foreach>


=> Added a <criteria> rule type that works like an isolated boolean function
   (or a weird combination of a <macrodef> and a <tally>). The <criteria>
   type is used to create non-trivial tests that tasksets like <do> and 
   <domatch> use to determine whether to execute their nested tasks. Unlike
   the existing <tally> and <tallyset>, a <criteria> can contain tasks other
   than conditions and must explicitly assign its result (a boolean) to a
   specified variable. See the User Guide for a complete description of this
   new rule type.


=> Added a <dowhile> taskset to the AntX standard flowcontrol components. 
   This taskset evaluates a named criteria and executes its nested tasks
   until the criteria fails. As with <do> and <domatch>, the named
   condition must be one of the AntX rule types or any component that
   implements the Ant "Condition" interface.

   Example Usage:
        <criteria id="moreLogs" resultvariable="out:moreLogs">
            ...[determine if there are more logs]
        </criteria>

        <property name="logsDir" value="${auditDir}/closedlogs"/>

        <dowhile test="moreLogs" i="ith.log" maxloops="31" haltifmax="yes">
            ...[process the log at $var:nextlogfile]
        </dowhile>


=> Enhanced <tally> to support both a 'truevariable' and 'falsevariable' 
   update option. This helps tally work easier with the new <criteria> and
   test features of various looping tasks.


=> The <parentdir> task is now part of AntX's file system helper tasks. You
   can use <parentdir> to create paths relative to a single known base without
   creating many (unused) intermediary properties. You can also get the
   location of classpath-based resources or temp directory-based items.
   
   Example Usage:
        <parentdir of="${basedir}" pop="2" pathproperty="etc" append="etc"/>
        <property name="css" value="${etc}/css"/>
        <assert isdirectory="${css}" msg="CSS directory exists"/>


=> The <listdir> task is now part of AntX's file system helper tasks. You
   can use <listdir> to create a list of a directory's contents and then
   iterate over that list.
   
   Example Usage:
        <listdir path="${closedlogs}" torefid="_logs">
            <filter includes="*.log,*.oldlog"/>
        </listdir>
        <echo message="Found ${$itemlist:_logs?size} logs to process"/>
        <callforeach i="log" items="_logs" steps="processLog"/>
        <unassign reference="_logs"/>


------------------------------------------------------------------------------
JWare/AntXtras v0.5b1 (September-22-2004) major changes since v0.4:

=> AntX 0.5 will be based on Ant 1.6.2. (Because some interfaces in 1.6.2
   do not exist in 1.6.1, AntX 0.5 requires Ant 1.6.2 or later.)


=> The AntX binary distribution no longer includes the "full" jar file. This
   jar contained the AntX tests in compiled form. Because this archive seemed
   to be rarely used, it has been removed. You can still use the source
   distribution to create your own development archive. (For similar reasons,
   the developer-specific release notes are no longer part of this document.)


=> The <overlay> taskset now supports elements in namespaces other than the
   default. Also, underscores in an <overlay>'s (direct) dynamic attributes
   are no longer converted to periods; this allows users to specify properties
   with underscores.

   Example Usage:
        <taskdef name="run" classname="..." uri="test:antx"/>
        ...
        <overlay xmlns:t="test:antx"
            debug.level="finetrace" debug_level="warning">
            
            <t:run .../>
            <assert notequals="${debug.level}" property="debug_level"/>
        </overlay>


=> You can now make an <isolate> wrapper porous by specifying a set of
   properties (<locals>) you want passed through. You can alternatively allow
   all changes through except a named set. The AntX 0.5 antlib.xml
   includes two presetdef variants of <locals> (<macrolocals>) and <isolate>
   (<macroisolate>) that are useful for isolating macrodef transient property
   settings.
   
   Example Usage:
        <macrodef name="javadocs">
            <attribute name="clean" default="no"/>
            <sequential>
                <macrolocals>
                    <property name="clean" value="@{clean}"/>
                    <property name="generate"/>
                </macrolocals>
                <macroisolate>
                    <tally trueproperty="generate">
                        ...
                    </tally>
                    <do if="clean">
                        <delete .../>
                    </do>
                    <do if="generate">
                        <javadoc.../>
                    </do>
                </macroisolate>
            </sequential>
        </macrodef>


=> You can now remove a variable or project reference that was created 
   with the <assign> task by using the new <unassign> task. This new task
   clarifies how fixture data can be removed and is particularly useful
   for tests that need to undo fixture modifications in their teardown
   sequences.
   
   Example Usage:
        <assign name="someref" value="blablabla" scope="project"/>
        ...[test test test]
        <unassign reference="someref"/>


=> AntX 0.5 introduces a new system-wide feature called "value URIs". You
   would use a value uri to extract fixture information other than Ant
   properties using property reference syntax. AntX includes support for
   the expected fixture elements (properties, references, variables) but
   the system is most useful if it's extended to include your own value
   URI handlers. See the AntXtras QuickStart guide for a complete
   description of this new feature. (In AntX 0.4, only the <overlay> taskset
   supported value uris.) Several sample handlers are included in the AntX
   contrib distribution.
   
   Example Usage:
        <manageuris action="enable">
            ...[Turn on value-URIs; see User Guide for options]

          <echo message="Finished: ${$datetime:$var:endtime}..."/>

          <do true="${$test:isWeekDay}"...>

          <copy file="${$artifact:licenses#main}" todir="..."/>
        
          <get username="nightlybuild" password="${$auth:nightlybuild}".../>



=> A new <truncatefiles> task has been added to the standard AntX I/O 
   helpers task collection. Use this task to truncate a file's contents 
   without deleting the file. 

   Example Usage:
        <truncatefiles haltiferror="yes">
            <files dir="${filterfiles}/dynamic">
                <include name="**/*.xml,vars"/>
                <include name="**/*.properties,vars"/>
            </files>
        </truncatefiles>


=> A new "urlproperty" parameter has been added to all the temporary
   object creation tasks like <newtempdir> and <tempdir>. If specified AntX
   will save a normalized file URL to the property.
   
   Example Usage:
        <newtempdir prefix="sql-" urlproperty="sqldir.url"/>



=> The standard AntX "transform" parameter now supports an "ospathurl" value
   to complement the existing "ospath" option. Also you can now pass a file
   url in to be converted to a normalized os path.

   Example Usage:
        <copyproperty name="out.url" value="${out}" transform="ospathurl"/>


=> You can make a <copyproperty> create a new system property by setting
   its 'scope' parameter to "system".
   
   Example Usage:
        <copyproperty name="jware.antx.strict.scriptcheck.enabled"
            value="yes" scope="system"/>


-SSMC