$Id: RELEASE-NOTES.txt,v 1.13.2.2 2004/08/30 08:01:47 rdonkin Exp $


                          Commons Digester Package
                                Version 1.6
                               Release Notes


INTRODUCTION:
============

This is mostly a feature release. A few minor bugs have been fixed (as listed
below) but Digester 1.5 proved to be a very stable release.

IMPORTANT NOTES
===============

New License
-----------
This release is done under version 2.0 of the Apache License.
Please see the LICENSE.txt and NOTICE.txt files in the distribution.

RSS Support
-----------
The RSS package present in previous distributions of Digester was only ever 
intended to be a "worked example", so the code has been moved to the
"src/examples/api/rss" directory within the CVS repository, and is no
longer part of the standard Digester binary distribution. However
the same package structure has been preserved, so any users who were using the
rss code in production should just have to compile the example code and
include that additional jar in the classpath. These classes are still contained
in the source distribution and so (for those for which such things matter)
are still officially released (though no longer distributed in the binary).

Examples Added
--------------
Several examples have been added to CVS at src/examples, for the enlightenment
of new Digester users. They can be access either through CVS or by grabbing the
source distribution.

Author and Version javadoc tags removed
---------------------------------------
All @author tags were removed, as per Apache Foundation policy. A list of
all the developers and contributors involved in Digester can still be
found via the Digester website, or in the "project.xml" file in the base
directory of the Digester CVS repository.

All @version tags were removed as they were not considered to be useful.

Dependencies
------------
The 1.6 Digester release supports greater choice for the user in terms of it's
dependencies. By choosing the correct combination of dependencies, Digester
can be used with either (incompatible) series of commons-collection releases
or none at all.

Compatible Dependency Sets:
   Digester 1.6 + Logging 1.0.x + BeanUtils 1.x + Collections 2.x
   Digester 1.6 + Logging 1.0.x + BeanUtils 1.x + Collections 3.x
   Digester 1.6 + Logging 1.0.x + BeanUtils 1.7

NEW FEATURES:
=============

Improved Java Docs
------------------
As usual, documentation has improved in this release. 

Plugins
-------
There is a new package org.apache.commons.digester.plugins which provides
the facility for rules to declare "plugin points" in the parsed xml at
which users can specify their own classes to be instantiated and potentially
configured via the same xml file. This allows xml configuration files to
be "user extendable", in the manner that log4j, ant, etc. are (though with
even more flexibility in many ways). See the package documentation for
more information.

Substitution and Variable Expansion
-----------------------------------
Via the Substitutor class and the Digester.setSubstitutor method, xml
attributes and element data can be manipulated before being seen by any
Rule instances. Taking advantage of this framework, a VariableSubstitutor
class is provided which allows the parsing app to set up a table of values
that can be referenced via "${varname}" syntax (and variants thereof) in 
the input xml. See the package documentation for 
org.apache.commons.digester.substitution for more information. 

Parser Feature Setter
-----------------------------------
The ParserFeatureSetterFactory class (plus the helper classes in the
new org.apache.commons.digester.parser package) provides a portable
mechanism for setting some parser features which have not yet been
standardised by JAXP or similar specifications. See the package
documentation for more information.

PathCallParamRule
-----------------
This new Rule class allows the "path" to the current xml node, or 
just the name of the current xml node, to be passed as a parameter
of a CallMethodRule.

SetNestedPropertiesRule
------------------------
Allows child elements to be mapped to bean properties, like the
SetPropertiesRule maps attributes to bean properties. Example:
  <widget>
    <width>1</width>
    <height>2</height>
    <label>Hello, World</label>
  </widget>
This could previously be done via the BeanPropertySetterRule and the
ExtendedBaseRules engine with trailing-wildcard support, but this
Rule can be used with the default Rules class.

WithDefaultsRulesWrapper
------------------------
A Rules class which wraps any other Rules implementation and enhances it
so that if no rules are matched for an element in the input then a default
set of Rule instances are returned.

CallMethodRule target offset
----------------------------
Constructors now exist on this rule to allow the target object on which the
method is invoked to be specified as an offset on the digester object stack.
Previously, CallMethodRule always targetted the top object on the stack. Note
that at the current time, factory methods for these constructors do not
exist on the Digester class; the Rule needs to be constructed directly then
added to the digester to access this (not commonly needed) functionality. 

CallMethodRule handling of return value from invoked method
------------------------------------------------------------
A protected method "processMethodCallResult" on the CallMethodRule has
been created so that it is simple to subclass this Rule and override this
method to implement special checks or other processing of the return value
of a method invoked via this rule.

Digester lazy initialization
----------------------------
A new "initialize" method has been added that subclasses of Digester can
override to perform any initialization they wish to do before parsing
commences, but do not wish to do in the constructor.

Digester new Rule factory methods
---------------------------------
Factory methods have been added for the new CallParamPathRule and
SetNestedPropertiesRule. A factory method for the pre-existing
ObjectParamRule class has also been added.

Note that the new Plugin rules do not have factory methods, nor do the
new variants on the CallMethodRule which take an "offset" parameter. Use of
these rules is considered rare enough that a factory method is not
necessary. This may be revised at a later time.

Named Stacks
------------
The digester now provides push, pop, peek and isEmpty methods that take
a stack name as a parameter. These can be used for any purpose that new
Rule classes find useful. 

Param stack access now public
------------------------------
The previously package-scope methods for accessing the digester's parameter
stack are now public. This makes it possible for users to implement new
"call param" rules in their own namespace.

The createSAXException methods are now public
----------------------------------------------
These previously protected methods are now public, so that Rule classes
(both user-implemented and in subpackages of Digester) can call them when
errors are encountered.

SAXLogger access
-----------------
Since Digester 1.2, messages have been logged about SAX events handled by
the Digester during parsing via a "saxLog" logging object which is different 
from the Log object that is used for "higher-level" digester messages.
The new methods getSAXLogger and setSAXLogger on the Digester class allow 
access to this separate Log instance.

Matched rules stack
-------------------
New member "matches" on class Digester holds a stack where each element is a 
list of matching rules. When a child xml element is entered, the list of
matches is pushed onto the stack, and at end it is popped off. This
yields performance benefits, and potentially useful info for use by
rule classes.

Entity Resolver changes
-----------------------
The digester's default entity resolver behaviour is now to try resolving via
the SYSTEM id if the PUBLIC id is not present.

XMLRules new features
-----------------------
The ability to load rules from an InputSource has been added.
Support has been added for SetRootRule and ObjectParamRule.
The "context class loader" will be used, if one exists, when
resolving "include" statements in xmlrules files.
FromXmlRuleSet rulesets can now be added to a Digester instance 
starting at a base pattern specified by the caller.
A getCause() method has been added to the XmlLoadException class.

RuleSetBase allows patterns ending in '/'
-----------------------------------------
The subject of this one says it all.

Commons Collections dependency
==============================
The commons-collections library has recently undergone a major release (3.0).
Digester has been tested with both commons-collections 2.1 and 3.0 and
there are no known issues with using either version of this library. See above
for the list of compatible dependency sets.


BUGS FROM PREVIOUS RELEASE
==========================

Reports Addressed
------------------
#22131 SetPropertiesRule: Avoid NPE when debugging enabled and no top object
#24613 xmlrules DTD does not provide SetRootRule
#25112 Cannot find digester-rules.dtd [DOCTYPE incorrect]
#28486 ExtendedBaseRules: Match can compute "longest match" incorrectly.

Outstanding Reports:
--------------------
#20903 ENH New rule for the digester (CallFactoryMethodRule)
#21903 ENH Include filename or uri if Digester.parse throws an exception

Bugs fixed with no bugzilla entry
----------------------------------
NodeCreateRule: r1.3 end method was not popping digester stack
ExtendedBaseRules: r.11 (patternStart)
ExtendedBaseRules: r.9 (findExactAncesterMatch(parentPattern))


DEPRECATION:
============
None