$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: 1 2 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