RELEASE-NOTES.txt - commons-digester - Git at Google

 $Id: RELEASE-NOTES.txt,v 1.13 2004/05/01 20:49:56 craigmcc 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 a very stable release.

 BACKWARDS INCOMPATIBILITIES
 ===========================

 ArrayStack
 ----------
 Previously, Digester required the collections library, simply for a single
 class: ArrayStack. To avoid depending explicitly on the commons-collections
 library, a copy of this class has been made within the digester library. All
 places which once used the collections version now use the digester version.
 Unfortunately, this will require all user classes which subclass the
 modified classes to be recompiled. The affected classes are:
   CallParamRule (member bodyTextStack)
   Digester (members bodyTexts, params and stack)
   FactoryCreateRule
   xmlrules.DigesterRuleParser

 RSS Example
 -----------
 Previously, Digester included example code for processing RSS (Really Simple
 Syndication) streams in the core commons-digester.jar distribution, with the
 code in package "org.apache.commons.digester.rss".  This code has been migrated
 to the new source directory "src/examples/rss", complete with a build.xml script
 that can recreate a new JAR file (commons-digester-rss.jar) containing this
 code.  The Java package name has not changed, so the only impact on applications
 actually using these classes will be the need to acquire the sources, build the
 new JAR file, and add it toyour classpath.


 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.


 OTHER 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.

 Examples Added
 --------------
 Several examples have been added to CVS at src/examples, for the enlightenment
 of new Digester users.

 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.


 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.


 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
	$Id: RELEASE-NOTES.txt,v 1.13 2004/05/01 20:49:56 craigmcc 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 a very stable release.

	BACKWARDS INCOMPATIBILITIES
	===========================

	ArrayStack
	----------
	Previously, Digester required the collections library, simply for a single
	class: ArrayStack. To avoid depending explicitly on the commons-collections
	library, a copy of this class has been made within the digester library. All
	places which once used the collections version now use the digester version.
	Unfortunately, this will require all user classes which subclass the
	modified classes to be recompiled. The affected classes are:
	CallParamRule (member bodyTextStack)
	Digester (members bodyTexts, params and stack)
	FactoryCreateRule
	xmlrules.DigesterRuleParser

	RSS Example
	-----------
	Previously, Digester included example code for processing RSS (Really Simple
	Syndication) streams in the core commons-digester.jar distribution, with the
	code in package "org.apache.commons.digester.rss". This code has been migrated
	to the new source directory "src/examples/rss", complete with a build.xml script
	that can recreate a new JAR file (commons-digester-rss.jar) containing this
	code. The Java package name has not changed, so the only impact on applications
	actually using these classes will be the need to acquire the sources, build the
	new JAR file, and add it toyour classpath.


	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.


	OTHER 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.

	Examples Added
	--------------
	Several examples have been added to CVS at src/examples, for the enlightenment
	of new Digester users.

	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.


	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.


	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