RELEASE-NOTES.txt

<!--
   Licensed to the Apache Software Foundation (ASF) under one or more
   contributor license agreements.  See the NOTICE file distributed with
   this work for additional information regarding copyright ownership.
   The ASF licenses this file to You under the Apache License, Version 2.0
   (the "License"); you may not use this file except in compliance with
   the License.  You may obtain a copy of the License at

       http://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.
-->
$Id$


                          Commons Digester Package
                                Version 2.0
                               Release Notes


INTRODUCTION
============

This is a major release. New projects are encouraged to use this release
of digester. There are breaking changes from Digester 1.8, see release notes
in detail before choosing to upgrade. There is no urgency for existing
projects to upgrade; Digester 1.8 has proven to be a stable release.

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

BREAKING CHANGES:

 * The minimum JDK requirement is now JDK 1.5. The provided binaries will not
   work on lower JDKs. The source has been updated to leverage Generics and
   other JDK 1.5 features where possible, and requires JDK 1.5 to compile.

 * This release eliminates all dependencies on Commons Collections classes.
   Previously, ArrayStack was used in the Digester implementation and was
   exposed via protected fields or inner classes of the following classes:
     org.apache.commons.digester.Digester,
     org.apache.commons.digester.CallParamRule, and
     org.apache.commons.digester.xmlrules.DigesterRuleParser
   These classes now use java.util.Stack instead. Any subclasses of the above
   using protected ArrayStack members will require appropriate migration to
   use java.util.Stack instead before they can be used with version 2.0.

OTHER IMPORTANT CHANGES:

 * The legacy schema support has been deprecated in favor of
   javax.xml.validation.Schema support.

DEPENDENCIES
=============

Digester 2.0 users should upgrade to the recommended dependency set below
where possible.

The Recommended Dependency Set for Digester 2.0 is:
   Digester 2.0 + Logging 1.1.1 + BeanUtils 1.8.0

It is also possible to use Logging 1.0.x or BeanUtils 1.7.0 instead.

NEW FEATURES
=============

 * XML SCHEMA SUPPORT
       Support for XML Schema validation using javax.xml.validation.Schema
       has been added to Digester. See Digester class Javadoc, and
       Digester#setSchema(javax.xml.validation.Schema) method.
       This allows usage of W3C XML Schema, Relax NG and Schematron for
       validation of XML documents.
       The legacy schema support has been deprecated (details below).

 * XINCLUDE AWARENESS
       The underlying SAXParser factory can now be easily configured to be
       XInclude aware. This allows for general purpose inclusion of XML or
       text documents, for example, and facilitates document modularity. For
       more details on XInclude, see: http://www.w3.org/TR/xinclude/

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

 * [DIGESTER-122] Potential NullPointerException if debug is enabled in
                  Digester#resolveEntity()

 * [DIGESTER-126] Potential NullPointerException if debug is enabled in
                  FactoryCreateRule#begin()

IMPROVEMENTS OVER PREVIOUS RELEASE
===================================

 * [DIGESTER-111] Null arguments to all Digester#parse() methods now an
                  IllegalArgumentException.

 * 'serialVersionUID' fields have been added to Serializable classes.

DEPRECATIONS
============

 * org.apache.commons.digester.Digester#schemaLanguage and
   org.apache.commons.digester.Digester#schemaLocation

    Use org.apache.commons.digester.Digester#schema instead.

 * org.apache.commons.digester.Digester#getSchemaLanguage(),
   org.apache.commons.digester.Digester#setSchemaLanguage(String),
   org.apache.commons.digester.Digester#getSchemaLocation(), and
   org.apache.commons.digester.Digester#setSchemaLocation(String)

    Use org.apache.commons.digester.Digester#getSchema() and
    org.apache.commons.digester.Digester#setSchema(javax.xml.validation.Schema)
    instead.

 * org.apache.commons.digester.ParserFeatureSetterFactory

    Switch to javax.xml.validation.Schema validation via Digester class
    instead.

 * org.apache.commons.digester.parsers package; classes
   org.apache.commons.digester.parsers.GenericParser and
   org.apache.commons.digester.parsers.XercesParser

    Switch to javax.xml.validation.Schema validation via Digester class
    instead.

OTHER NOTES
============

 * This is the first Digester release using Maven 2.