JWare/AntXtras Foundation
                     Version 3.0.0, Release Aug 2011
                   -----------------------------------


This document contains the major AntXtras version change notes. For the most
recent information, visit the website at http://antxtras.sourceforge.net/.

------------------------------------------------------------------------------
This version of AntXtras represents a new series (v3) based on JRE 1.5 
and Ant 1.8. Due to some incompatible structural changes to certain Ant
components on which AntXtras depends, AntXtras v3 is not compatible
with Ant 1.7.x and requires JRE 1.5 or later to run (the JRE requirement
is ours not Ant's).

CHANGES IN 3.0.0:
-------------------

=> Rebuilt against latest Ant 1.8.2 release. Reminder: you MUST use Ant
   1.8.0, 1.8.1, or 1.8.2 with AntXtras v3. [FS#188]

=> Extended the $x: funcut to extract the message or classname
   of the error captured by an <iferror> taskset. The 'thrown'
   selector will extract the thrown exception's message, the
   'thrownclass' will extract out the thrown exception's fully
   qualified classname, the 'thrownname' will extract just the
   exception class's leaf name, and 'thrownfull' will combine
   the output of 'thrownclass' and 'thrown' [FS#254, FS#263].

   EXAMPLE:
     1. <oja:protect>
          [work...work...work]
          <oja:iferror>
            <oja:show messageid="err.ftp" arg0="${ftp.url}"
                  arg1="${$x:thrownfull}"/>
          </oja:iferror>
        </oja:protect>


=> Updated the <assert> task to support the generic 'isalive' shorthand
   for the Ant IsReachable condition. This new condition replaces the
   v2 http-protocol specific 'httpalive' shorthand. [FS#86]

   EXAMPLE:
     1. <oja:assert isalive="internalhost.ny.mycompany.com"/>
     2. <oja:assert isalive="ftp://filevault.mycompany.net"/>


=> Enhanced <assert>, <prefer>, and <fixturecheck> to handle up to
   10 dynamic message template args like <show>. Slot {0} is always
   filled with the list of passed conditions (up to failure).[FS#136]

   EXAMPLE:
     1. <oja:assert ismatch="(local|public)" property="dist.type"
          messageid="dist.type.unknown" arg1="${dist.type}"/>


=> Fixed <batchchecks> task to pay attention to the 'messageid' 
   parameter BEFORE 'message'. [FS#136]


=> Enhanced the AntXtras <isref> condition to support a 'type' 
   option that works like the option of the same name for the
   standard Ant <isreference> condition. [FS#241]

   EXAMPLE:
     1. <oja:assert message="Environment configured for tests">
          <isref type="path" name="tests.search.path"/>
          <isref type="patternset" name="tests.includes"/>
        </oja:assert>


=> Added the $vendorinfo: function shortcut as defined in online
   "Check Installation" documentation.


=> Fixed issues with the example 'antxtras-funcuts-demo.xml' file.
   This script now works as expected out-of-the-box.



CHANGES IN 3.0.0b2:
-------------------

=> Rebuilt against latest Ant 1.8.1 release. Reminder: you MUST use Ant
   1.8.0 or 1.8.1 with AntXtras v3. [FS#188]


=> [INCOMPAT] The v1+v2 <properties> has been renamed <parameters> to
   reflect the default key normalization processing and the intended use
   of this datatype. Note that the default delimiter for a <parameters>
   object is the semi-colon ';' NOT the platform newline. There is a
   new <properties> declaration that matches the v2+v3 *REAL* Java 
   Properties definition (PropertiesLoaderDef class). [FS#196]

   EXAMPLE: (previously known as '<properties>')
     1. <parameters id="deploy.args">
          <parameter name="server" value="dev1.uk.my.com"/>
          <parameter name="port" value="5669"
          <parameter name="timeout" value="${$millis:2m}"/>
        </parameters>

     2. <parameters id="test.args" normalize="off"
           file="${conf.d}/${env}-config.properties"/>
 
 
 => Added new implementation of <properties> that leverages the v2 type
    PropertiesLoaderDef to load XML as well as standard properties 
    sources and filter chains. Advantages over the <parameters> type
    for *LOADING* properties include: no normalization of keys, can 
    load XML as well as regular properties sources, can customize
    lookup paths, can apply an Ant filter chain to source. [FS#197]

    EXAMPLE:
      1. <properties id="test.properties" 
           resource="test/config/${env}.xml">
              <classpath path="${conf.d}"/>
              <filterchain>
                <expandproperties/>
              </filterchain>
         </properties>


=> Enhanced the <unassign> task to support unassignment of multiple 
   items in a single call. Supported for variables, references, and
   properties.[FS#140]
   
   EXAMPLE
     1. <unassign vars="nextid,nextconfig"/>
     2. <unassign refs="main.path,test.path"/>


=> [INCOMPAT] We have removed support for the invertcase and various
   datetime transforms from the <copyproperty> task and all other
   components that support a "transform" option (like <assign>). You
   can always use one of the datetime function shortcuts. [FS#151]


=> Added new global (or per-project) AntXtras property that defines 
   the default delimiter for components. You can override this 
   property using -D, a project property, overlay, local, etc. Most
   AntXtras components that split script-supplied lists have been 
   updated to use the property setting when present. [FS#255]
   
   EXAMPLE:
     1. Change default list delimiter to "|" instead of ",".
           ant -Djware.antxtras.defaults.delimiter.list="|" ...
 
        Now use '|' to tokenize string lists automatically:
           <doforeach i="ch" list="a|b|c|d|e">
             ...


=> Enhanced the <assign> task to support a new delimited string
   concatenation operator "+l". [FS#153]

   EXAMPLE:
     1. (uses ',' as delimiter [default]; append to end)
        <assign var="jars" op="+l" value="${jarname}"/>
        
     2. (insert new item at specific index)
        <assign var="jars" op="+l{0}" value="${jarname}"/>

     3. (uses custom delimiter '||')
        <overlay jware.antxtras.defaults.delimiter="||">
          <assign var="re" op="+l" value="${port}"/>
          ...
        </overlay>


=> [INCOMPAT] Removed 'mergecontrol' from AntXtras foundation as
   this functionality is not used by active sub-projects. [FS#151]


=> Enhanced $map: function shortcut to work with more Map data types.
   Any Java 'Map' can be read provided its values are convertible
   to plain strings. [FS#257]


=> Enhanced <show> and <stop> to support the generic "true" and "false"
   conditions. Now you can control when these actions trigger with a
   variety of tests. [FS#144]

   EXAMPLE:
     1. <stop true="${$iszero:${waittime}}" 
              messageid="err.bad.timeout.spec"/>
 
     2. <show true="${$anyset:trace.enabled,audit.enabled}"
              messageid="lf.entering" arg0="${testname}"/>


=> Enhanced <capturelogs> to support a new "tofile" parameter that
   functions like an embedded copylogged shortcut. The new parameter
   makes a very very common use of capturelogs taskset to capture a
   log file whether or not the enclosed tasks finish normally very
   easy to script. [FS#250]
   
   EXAMPLE:
     1. asof (new-AntXtras 3.0.0b2)
          <capturelogs tofile="${logs.d}/a.log">
            [work work work...]
          </capturelogs>
     
        replaces (pre-AntXtras 3.0.0)
          <capturelogs>
            <protect>
              [work work work...]
              <always>
                <copylogged tofile="${logs.d}/a.log"/>
              </always>
            </protect>
          </capturelogs>


=> Enhanced <doforeach> to support two new loop controls: "keysof"
   and "valuesof" which let you iterate over the keys or values of
   a specified map-like structure. [FS#249]

   EXAMPLE: 
     1. <properties id="myconf" file="..."/>
        <doforeach i="name" keysof="myconf">
           [work work work...]
        </doforeach>

     2. <doforeach i="value" valuesof="myconf">
           <domatch property="value">
              <like value="FIXME|TODO">
                 [work work work...]
              </like>
           </domatch>
        </domatch>


=> Enhanced <show> to support a "tofile" option just like the standard
   Ant <echo> task. This makes <show> a complete replacement for
   <echo> with support for resource bundle messages. [FS#176]

   EXAMPLE:
     1. <show messageid="lf.entering" arg0="${testname}"
            tofile="${logfile}" append="yes"/>


=> Fixed <overlay> taskset to handle namespaced dynamic attributes.
   Note that the overlaid property's name will be of the form:
   <URI>:<LocalName> where <URI> is the declared namespace's URI in
   your Ant script and <LocalName> is the local attribute name. 
   [FS#183]

   EXAMPLE:
     1. (overlay 'org.jwaresoftware.antxtras:version' property)
        <xml ... xmlns:oja="org.jwaresofware.antxtras"...>
        ...
          <overlay oja:version="4.0.0d1">
            [work work work...]
          </overlay>


=> Enhanced <protect> taskset to allow multiple <iferror> handler
   tasksets. To differentiate <iferror>s you must supply the new
   "ofType" parameter to each iferror taskset. The <iferror>
   taskset with no "oftype" attribute is the default handler in the
   event no other match is found. You must supply only one handler
   per type of exception. [FS#251]

   EXAMPLE:
     1. <protect haltiferror="no">
          [work work work...]
          <iferror ofType="${myextension}.XYZException">
             [special cleanup...]
          </iferror>
          <iferror>
             [default cleanup...]
          </iferror>
        </protect>

     2. (UNIQUE HANDLERS ONLY -- THIS IS AN ERROR):
        <protect haltiferror="no">
          [work work work...]
          <iferror>
            [...]
          </iferror>
          <iferror>
            [...]
          </iferror>
        </protect>


=> Fixed <tally> task so that the true[property|variable] and the
   false[property|variable] attributes are not exclusive. Now you
   can set any combination of these flag attributes. [FS#181]
   
   EXAMPLE:
     1. <tally truevariable="fb.tested" trueproperty="fb.enabled">
           [check check check...]
        </tally>


=> Fixed the "in" loop control for the <doforeach> task to allow
   decreasing iteration (as setup by a negative increment). [FS#131]
   
   EXAMPLE:
     1. <doforeach i="i" in="10,0,-1">
          [work work for 10,9,8,7,6,5,4,3,2,1...]
        </doforeach>

     2. <doforeach i="i" in="0,-5,-1">
          [work work for 0,-1,-2,-3,-4...]
        </doforeach>


=> Added new shortcut presetdef <assertnot> that fails if the inverse
   of the shorthand or nested condition is false for an assertion.
   [FS#260]
   
   EXAMPLE:
     1. <oja:assertnot isfile="${rejects.d}/${TODAY}"/>


=> Renamed AntXtras version of <isset> condition to <isdeclared>
   to avoid Ant component name conflicts if you load AntXtras'
   condition antlib into to the standard namespace. The old name
   (<isset>) is still defined but is deprecated/to-be-removed
   in AntXtras v4. ONLY the condition name 'isset' is deprecated.
   The function shortcut and Java APIs are still 'isset'.
   
   EXAMPLE:
     1. (use 'isdeclared' to get AntXtras version of 'isset')
        <condition property="something.enabled">
          <isdeclared property="some.id" whitespace="ignore"/>
          <isdeclared reference="some.refid" />
        </condition>



CHANGES IN 3.0.0b1:
-------------------

=> [INCOMPAT] Rebuilt against latest Ant 1.8 release and JRE 1.5 so
   you MUST use Ant 1.8 with AntXtras v3; use an existing v2 release if
   you need to stick with Ant 1.7.x or JRE 1.4. [FS#188]


=> [INCOMPAT] As part of the goal to get the core AntXtras antlib to
   500K in size, the following components have been moved to the advanced
   antlib (antlib-advanced.xml): <prefer>, <ruleset>, <ruledef>, 
   <tallyset>, <criteria>, <strings>, <dowhile>, <call>, <callforeach>,
   <doinline>, <captureoutput>, <copylogged>, <interpretlogged>, and
   <classloaderdef>. The following components are in the testing antlib
   (antlib-unit.xml): <printbundle> and <printenv>. [FS#146, FS#151]


=> [INCOMPAT] Renamed the AntXtras <matches> CONDITION to <ismatch> to
   prevent collision with new Ant 1.7 <matches> condition. The synonym
   assertion condition was also removed. [FS#223]


=> [INCOMPAT] Invalid property references are now logged at the verbose
   level not the warning level. You can force AntXtras to signal a script
   error for malformed property references by setting the project or system
   property 'jware.antxtras.defaults.haltiferror.malformedproperties.flag'
   to true. [FS#188]


=> [INCOMPAT] The old 'if' and 'unless' attributes of the nested elements
   of a <locals> declaration have been renamed 'true' and 'false' to
   reflect how they're interpreted-- the *value* is checked as a literal
   string, not as a property name as implied by the old if/unless name.
   The if/unless attributes now really reflect the traditional use of 
   these attribute as tests for property existence ONLY. [FS#239]

   EXAMPLE:
        <locals id="edited.state">
          <property name="_callcount" if="trace.enabled"/>
          <property name="MAXWAIT" true="${$p:.strict?on}"/>
        </locals>


=> [INCOMPAT] The following v1 aliases for various components have been
   removed: <foreach>, <rule>, <autorun>, <isnumeric>, and <manageuris>.
   Use the supported component names instead: <doforeach>, <ruleset>, 
   <doinline>, <isnumber>, and <managefuncuts>. [FS#105]


=> [INCOMPAT] Removed all v1 and v2 deprecated condition aliases and
   function shortcuts. Affected items include: <isallset>, <isanyset>,
   <isnoneset>, <antversion>, etc. Also removed deprecated msgid
   and msgid attributes from rules framework. [FS#151, FS#187]


=> [INCOMPAT] The <capturelogs> taskset now defaults its "splitentries"
   feature on. This new setting makes captured log files human readable
   and is the expected setting for the majority of use-cases for this
   component. For transient log capture done on behalf of interpreters
   (e.g. evaluating results of javadoc, javac, emma, tests, etc.) you 
   can turn the feature off explicitly. [FS#184]


=> As of 3.0.0b1, when defined, the recommended namespace prefix and 
   URI for AntXtras are 'oja:' and 'jwaresoftware.antxtras'.

   EXAMPLE: Load AntXtras antlib into the 'jwaresoftware.antxtras'
   namespace referenced by the 'oja:' prefix.

        <project xmlns:oja="jwaresoftware.antxtras"...>
          ...
          <taskdef uri="jwaresoftware.antxtras"
             resource="org/jwaresoftware/antxtras/install/antlib.xml"
             classpathref="antxtras.classpath"/>
          ...
          <oja:show message="Hello World!"/>


=> The following AntXtras components now support the new <local> 
   property mechanism in Ant 1.8: <do>, <isolate>, <overlay>, <dowhile>, 
   <doforeach>, <criteria>, and each of the types of inner tasksets 
   for a <domatch>. For each of these tasksets a new locals scope is
   created for the duration of the taskset execution. There is also
   a special caveat for the <isolate> taskset: if you define a <local>
   for a property that you've already marked as "allow to pass through"
   any new local value assignment will NOT pass through (because the
   local scope masks the assignment from the 'outer' isolate parent's
   scope). [FS#221]


=> Added support for a 'isempty' operation to both $list: and $map:
   function shortcuts. [FS#217]
   
   EXAMPLE:
        <do false="${$map:myproperties?isempty}">
          [work work work...]
        </do>


=> Fixed <matches> TASK to set the falsevariable to "true" if there is
   no match; was setting value to "false". [FS#220]


=> New function shortcuts added for 3.0.0b1: $dirname:, $literal:.
   [FS#213, FS#230]

   EXAMPLE:
     1. $dirname:
        <path id="deps.path">
          <fileset dir="${$dirname:${root.d}}/deps/main">
            [in/exclusions...]
          </fileset>
        </path>

     2. $literal:
        <echo message="STATUS:${$string:default.stat|$literal:FAIL}"/>


------------------------------------------------------------------------------
-SSMC