<?xml version="1.0" encoding="ISO-8859-1"?>
<document url="http://www.dom4j.org/status.xml">

  <properties>
    <title>Change History</title>
    <author email="jstrachan@apache.org">James Strachan</author>
 </properties>
 
  <body>
      <section name="CVS">
        <p>Fixed bug in <code>BeanElement</code> which prevented proper execution of the bean samples (contributed by Wonne Keysers).</p>
        <p><code>STAXEventWriter</code> now uses <code>XMLEventConsumer</code> instead of <code>XMLEventWriter</code> (contributed by Christian Niles).</p>
        <p>Fixed bug in <code>SAXReader</code> that caused problems parsing files in OSX (reported by Paul Libbrecht).</p> 
        <p>Fixed bug in <code>XMLWriter</code> that caused whitespace to be added between successive calls of the <code>characters(...)</code> method (reported by Paul Libbrecht).</p>
        <p>Improved performance of <code>NamespaceCache</code> in multithreaded environments (contributed by Brett Finnell).</p>
      </section>

      <section name="1.5 beta 2">
        <p>Added flag to <code>OutputFormat</code> that supresses newline after XML declaration.</p>
        <p>Upgraded dependencies to their latest version on ibiblio.</p>
        <p>Added method to <code>DocumentHelper</code> that allows user to specify encoding when parsing an xml <code>String</code>
           (contributed by Todd Wolff).</p>
        <p>Fixed a ClassCastException bug in <code>BeanElement</code>.</p>
        <p>Fixed a bug in <code>SAXContentHandler</code> which caused a <code>NullPointerException</code> in some 
           situations.</p>
        <p>Fixed bug which prevented an element's namespace prefix from being registered for use in xpath expressions (contributed by Todd Wolff).</p>
        <p>Fixed bug in <code>XMLWriter</code> that caused duplication of the default namespace declaration (reported by Todd Wolff).</p>
        <p>Added a bunch of patches to make the dom4j DOM classes more DOM compliant (contributed by Curt Arnold).</p>
        <p>Fixed bug in <code>DispatchHandler</code> which made the handler not reusable (reported by Ricardo Leon).</p>
        <p>Fixed bug in <code>SAXContentHandler</code> that caused incorrect CDATA section parsing (contributed by Todd Wolff).</p>
        <p>Fixed bug in <code>SAXContentHandler</code> that caused incorrect entity handling.</p>
        <p>Fixed bug in <code>XMLWriter</code> causing padding to be disabled, even if enabled in the specified outputformat (reported by Bo Gundersen).</p>
        <p>Added initial support for STaX streams (contributed by Christian Niles).</p>
      </section>

      <section name="1.5 beta 1">
        <p>Fixed encoding bug in <code>Document.asXML()</code> and <code>DocumentHelper.parseText()</code>.</p>
        <p>Fixed bug in SAXReader that caused problems resolving relative URIs when parsing java.io.File Objects (reported by Kohsuke Kawaguchi).</p>
        <p>The iterators returned by the Element.elementIterator(...) methods now support remove().</p>
        <p>DOMWriter writes now DOM Level 2 attributes and elements (reported by Geert Dendoncker and Joury Gokel).</p>
        <p>Use latest implementation of the Aelfred parser.</p>
        <p>Fixed some problems with internal/external DTD declarations (reported by Bryan Thompson).</p>
        <p>Upgraded to Jaxen 1.1 beta 2.</p>
        <p>Ignore attribute order when comparing Elements in <code>NodeComparator</code>.</p>
        <p>Fixed bug in XMLWriter where namespace declarations were duplicated.</p>
        <p>Fixed bug in parsing a Processing Instruction (reported by Vladimir Kralik).</p>
        <p>Added support for Stylesheet modes (reported by Mark Diggory).</p>
        <p>Don't escape &quot; and &apos; characters in attribute values if it's not necessary (contributed by Christian Niles).</p>
        <p>Fixed some <code>DOMNodeHelper</code> issues (reported by Henner Kollmann).</p>
        <p>Fixed some datatype issues (reported by Thomas Draier).</p>
        <p>Fixed an bug where the EntityResolver was not set on the XMLReader.</p>
        <p>Fixed multithreaded access on <code>DefaultElement</code>.</p>
        <p>Fixed problem parsing XML Files (reported by Geoffrey Vlassaks).</p>
        <p>Added xml:space attribute support based on XML Specification 1.0.</p>
      	<p>Maven build of dom4j is now nearly complete. Maven is now used for the website generation.</p>
        <p>Fixed some bugs in BackedList (contributed by Alessandro Vernet).</p>
      </section>
      
      <section name="1.4 Release">
        <p>Added patch supplied by Dan Jacobs that fixes some entity encoding problems in XMLWriter - cheers Dan!
        </p>
        <p>Patched the DOMElement replaceChild method to return the correct Node and to throw a DOMException when trying to replace a non-existing child.
        </p>
        <p>Added patch to BackedList that could cause IndexOutOfBoundsExceptions to be thrown
        	that was kindly supplied by Andy Yang - thanks Andy!	
        </p>
        <p>Update of Cookbook containing a chapter about rule API.
        </p>
        <p>Patched SAXWriter to not pass in null System or Public IDs which can cause problems in Saxon.
        </p>
        <p>Patched dom4j to work against Jaxen 1.0 RC1 or later build.
        </p>
        <p>Applied patch to bug found by Tom Oehser that XPath expressions using elements or attributes whose name starts 
        with '_' were not being handled correctly. It turns out this was a SAXPath issue.
        </p>
        <p>Applied patch to bug found by Soumanjoy Das that creating a new DOMDocument then calling createElement() would generate
          a ClassCastException.
        </p>
        <p>Applied patch supplied by James Dodd that fixes a MIME encoding issue in the embedded Aelfred parser
        </p>
        <p>Applied patch to fix bug found by David Frankson. Adding attributes with null values causes problems in XSLT engines
            so now adding a null valued attribute is equivalent to removing the attribute. So null attribute values are silently ignored.
            e.g.
<pre>
Element element = ...;
element.addAttribute( "foo", "123" );
...
Attribute attribute = element.attribute( "foo" );
assertTrue( attribute != null );
...
element.addAttribute( "foo", null );
attribute = element.attribute( "foo" );
assertTrue( attribute == null );
</pre>
        </p>
      </section>
      
      <section name="1.3 Release">
        <section name="Patches">
        <p>Applied patch to bug found by Mike Skells that was causing XPath.matches() to return true for absolute XPaths which returned different nodes to the node provided to the XPath.
        </p>
        <p>Applied patch provided by Stefan that was causing IndexOutOfBoundsException when using the evaluate() method in DefaultXPath on an empty result set. Also added a test case to org.dom4j.TestXPathBug called testStefan().
        </p>
        <p>Applied patch suggested by Frank Walinsky, that XPath objects are now Serializable. 
        </p>
        <p>Applied patch provided by Bill Burton that fixes union pattern matching. 
        </p>
        </section>
      </section>

      <section name="1.2 Release">
        <section name="New Swing TableModel for displaying XML">

        <p>Added a new Swing TableModel for displaying XML data in a Swing user interface. It uses
          an XPath based model to define the rows and column values.
          A table definition can be specified using a simple XML format and then loaded in a small amount of code.
          e.g. here's an example of a table that will list the servlets used in a web.xml document
        </p>
<pre>
&lt;table select="/web-app/servlet"&gt;
  &lt;column select="servlet-name"&gt;Name&lt;/column&gt;
  &lt;column select="servlet-class"&gt;Class&lt;/column&gt;
  &lt;column select="../servlet-mapping[servlet-name=$Name]/url-pattern"&gt;Mapping&lt;/column&gt;
&lt;/table&gt;
</pre>
          <p>
          Notice the use of the $Name XPath variable to access other cells on the row.
          Here's the pseudo code to display a table for an XML document.
          </p>
<pre>
Document tableDefinition = ...;
Document source = ...;
TableModel tableModel = new XMLTableModel( tableDefinition, source );
JTable table = new JTable( tableModel );
</pre>
        <p>
          There is a sample program in samples/swing/JTableTool which will display any table definition
          for a given source XML document. There is an example table definition for the periodic table
          in xml/swing/tableForAtoms.xml.
        </p>
        </section>

        <section name="Registering Namespace URIs for XPath">
        <p>Added a new helper method to make it easier to create namespace contexts for doing
          namespace aware XPath expressions. The new setNamespaceURIs(Map) method on XPath makes it easier
          to pass in the prefixes and URIs you wish to use in an XPath expression. Here's an example of it in action
        </p>
<pre>
Map uris = new HashMap();
uris.put( "SOAP-ENV", "http://schemas.xmlsoap.org/soap/envelope/" );
uris.put( "m", "urn:xmethodsBabelFish" );        
XPath xpath = document.createXPath( "/SOAP-ENV:Envelope/SOAP-ENV:Body/m:BabelFish" );
xpath.setNamespaceURIs( uris );        
Node element = xpath.selectSingleNode( document );
</pre>
        <p>In addition DocumentFactory has a setXPathNamespaceURIs(Map) method so that common namespace URIs can be associated with
          a DocumentFactory so namespace prefixes can be used across many XPath expressions in an easy way. e.g.
        </p>
<pre>
// register prefixes with my factory
Map uris = new HashMap();
uris.put( "SOAP-ENV", "http://schemas.xmlsoap.org/soap/envelope/" );
uris.put( "m", "urn:xmethodsBabelFish" );        

DocumentFactory factory = new DocumentFactory();
factory.setXPathNamespaceURIs( uris );

// now parse a document using my factory
SAXReader reader = new SAXReader();
reader.setDocumentFactory( factory );
Document doc = reader.read( "soap.xml" );

// now lets use the prefixes
Node element = doc.selectSingleNode( "/SOAP-ENV:Envelope/SOAP-ENV:Body/m:BabelFish" );
</pre>
        </section>

        <section name="Whitespace handling">

        <p>There is a new <i>mergeAdjacentText</i> option available on SAXReader 
        to concatenate adjacent text nodes into a single Text node. 
        </p>
        <p>
        In addition there is a new <i>stripWhitespaceText</i> option to strip text which occurs between 
        start/end tags which only consists of whitespace. 
        </p>
        <p>
        For example, parsing the following XML with the stripWhitespaceText option enabled
        and the mergeAdjacentText option enabled
        will result in a single child node of the parent element, rather than 3 (2 text nodes containing whitespace and one element).
        </p>
<pre>
&lt;parent&gt;
  &lt;child&gt;foo&lt;/child&gt;
&lt;/parent&gt;
</pre>
        <p>
        Note that this option will not break most mixed content markup such as the following, 
        since its only whitespace between tag start/ends that gets removed; non-whitespace strings are not trimmed.
        </p>
<pre>
&lt;p&gt;hello &lt;b&gt;James&lt;/b&gt; how are you?&lt;/p&gt;
</pre>
        <p>
        Both these options together can improve the parsing performance by around 10-12% depending on the 
        structure of the document. Though the whitespace layout of the XML document will be lost, so only
        use these modes in data-centric applications like XML messaging and SOAP.
        </p>
        <p>
        So a typical SOAP or XML messaging developer, who may care more about performance than
        preserving exact whitespace layout, may use the following code to 
        make the SAX parsing more optimal.
        </p>
<pre>
SAXReader reader = new SAXReader();
reader.setMergeAdjacentText( true );
reader.setStripWhitespaceText( true );
Document doc = reader.read( "soap.xml" );
</pre>
        </section>

        <section name="Patches">
        <p>Applied patch to HTMLWriter to fix bug found by Dominik Deimling that was not correctly outputting CDATA sections correctly.
        </p>
        <p>Patched the setName() method on Element so that elements can be renamed. Also added a new setQName() to the Element interface so that elements can be renamed in a namespace aware manner. Thanks to Robert Lebowitz for this.
        </p>
        <p>Applied fix to bug found by Manfred Lotz that XMLWriter in whitespace trimming mode would sometimes not correctly insert a space when text is seperated by newlines. The Test case testWhitespaceBug() in org.dom4j.TestXMLWriter reproduces the bug that has now been fixed.
        </p>
        <p>Applied patches supplied by Stefan Graeber that enhance the datatype support to support included schemata and derived element types.
        </p>
        <p>Applied patches suggested by Omer van der Horst Jansen to enable dom4j to fully work
          properly on JDK1.1 platforms. There were some uses of java.util.Stack which have been changed to ArrayList.
        </p>
        <p>Applied patches supplied by Maarten Coene that fixes some issues with using the correct
          DocumentFactory when using the DOM implementation.
        </p>
        <p>Updated the MSV support to comply with the latest MSV version, 1.12 (Nov 01 2001).
          In addition the MSVDemo.java in dom4j/src/samples/validate has been replaced by
          JARVDemo.java which now uses the <a href="http://iso-relax.sourceforge.net/JARV/">JARV</a> API 
          to validate a dom4j 
          document using the <a href="http://wwws.sun.com/software/xml/developers/multischema/index.html/">MSV</a> implementation.
          This demo can validate any XML document against any DTD, XML Schema, Relax NG, Relax or Trex
          schema - thanks to the excellent JARV API and MSV library.
        </p>
        <p>Applied patches supplied by Steen Lehmann that fixes handling of external DTD entities in SAXContentHandler 
          and fix the XML output of the ExternalEntityDecl
        </p>
        <p>Applied patch to bug found by Steen Lehmann that XPath expressions on the root element
          were not correctly handling namespaces correctly. The test case is demonstrated in
          dom4j/src/test/org/dom4j/xpath/TestSelectSingleNode.java
        </p>
        <p>Added patch found by Howard Moore when using XTags that XPath string values which contained
        strings with entities, such as the use of &amp;amp; in a text, would result in redundant spaces
        occuring, breaking URLs.
        </p>
        </section>
      </section>

      <section name="1.1 Release">
        <section name="New features">
        <p>Added a new package, org.dom4j.dtd which contains some DTD declaration classes which are added to the DocumentType interfaces
        List of declarations. This is useful for finding out details of the attribute or element delcarations inside either the 
        internal or external DTD subset of a document. 
        </p>

        <p>To expand internal or external DTD subsets when parsing with SAXReader use the 2 properties on SAXReader (and SAXContentHandler). 
        </p>

<pre>
SAXReader reader = new SAXReader();
reader.setIncludeInternalDTDDeclarations( true );
reader.setIncludeExternalDTDDeclarations( true );
Document doc = reader.read( "foo.xml" );

DocumentType docType = doc.getDocType();
List internalDecls = docType.getInternalDeclarations();
List externalDecls = docType.getExternalDeclarations();
</pre>

        <p>This new feature means that XML documents which use internal DTD subsets, external DTDs or a mixture of internal and external
        DTD subsets can now be properly round tripped.
        </p>

        <p>Note that there appears to be a bug in Crimson 1.1.3 which does not properly differentiate between internal or external DTD 
        subsets. Refer to the <a href="http://dom4j.org/javadoc/org/xml/sax/ext/LexicalHandler.html#startDTD(java.lang.String,java.lang.String,java.lang.String)">startDTD()</a>
        method of <a href="http://dom4j.org/javadoc/org/xml/sax/ext/LexicalHandler.html">LexicalHandler</a>
        for details of how startEntity/endEntity is meant to demark external DTD subsets.
        </p>

        <p>
        Its our intention to expand internal DTD subsets by default (so that documents can be properly round tripped by default)
        but require external DTD subsets to be explicitly enabled via the property on the SAXReader (or SAXContentHandler). 
        This bug in Crimson causes all DTD declarations to appear as internal DTD subsets, which both is a performance overhead
        and breaks round tripping of documents which just use external DTD declarations. So until this matter is resolved
        both internal and external declarations are not expanded by default.
        </p>

        <p>
        Note that the code works perfectly against Xerces.
        </p>
        </section>

        <section name="Patches">
        <p>Applied patch submitted by Yuxin Ruan which fixes some issues with XML Schema Data Type support
        </p>
        <p>Followed Dennis Sosnoski's suggestion, adding a null text String to an Element
          now throws an IllegalArgumentException.
          To ensure that the IllegalArgumentException is not thrown its advisable
          to check for null first. For example...
        </p>
<pre>
Element element = ...;
String text = ...;

// might throw IllegalArgumentException
// if text == null
element.addText( text );

// safer to do this
if ( text != null ) {
  element.addText( text );
}
</pre>

        <p>Fixed problem found by Kesav Kumar Kolla whereby a deserialized Document could have problems if 
          new elements were attempted to be added. The problem was an issue with DocumentFactory not correctly
          deserializing itself properly.
        </p>
        <p>Fixed problem found by David Hooker with Ant build file for the 
        binary and source distribution that was not including the manifest file
        in the distribution. 
        </p>
        <p>Applied patch submitted by Lari Hotari that was causing the XMLWriter to fail when used as a 
        SAX XMLFilter or ContentHandler to turn SAX events into XML text. Thanks Lari!
        </p>
        <p>Fixed bug found by Kohsuke Kawaguchi that there was a problem in XMLWriter during its serialization of
        a document which redeclared the default namespace prefix. It turned out to be a bug in
        org.dom4j.tree.NamespaceStack where redeclarations of namespace prefixes were not being handled properly
        during serialization. The test cases in org.dom4j.TestXMLWriter and org.dom4j.TestNamespaces have been improved
        to test these features more rigorously.
        </p>
        <p>Fixed bug found by Toby
        that was causing a security exception in applets when using a DocumentFactory.
        </p>
        <p>Implemented the suggestion by Kesav Kumar, that the detach() method now returns the node (this) so that moving 
        nodes from one part of a document to any another can now be one line of code. Here's an example of it in use.
        </p>
<pre>
Document doc1 = ...;
Document doc2; = ...;
Element destination = doc2.getRootElement();
Element source = doc1.selectSingleNode( "//foo[@style='bar']" );

// lets move the source to the destination
destination.add( source.detach() );
</pre>
        <p>Added better checking in selectSingleNode() implementation so that XPath expressions which do not
          return a Node throw a meaningful exception (not ClassCastException) informing the user of
          why the XPath expression did not succeed.
        </p>
        <p>Added patch found by Kesav Kumar that a document containing null Strings would cause a NullPointerException
          to be thrown if it was passed into SAXWriter (used by the JAXP - XSLT code). Now the SAXWriter will
          quietly ignore null Strings, as will XMLWriter.
        </p>
        </section>
      </section>

      <section name="1.0 release">
        <section name="New features">
          <p>Added helper method setXMLFilter() to SAXReader making it easier to install SAX filters to filter or preprocess SAX events
          before a dom4j Document is created. Also added a new sample program called sax.FilterDemo that demonstrates how to use a SAX filter
          with dom4j.
          </p>
          <p>
            Added full support for <a href="http://jaxen.org">Jaxen</a> function, namespace and variable context interfaces.
            This allows the XPath engine to be fully customized. e.g.
<pre>
XPath xpath = document.createXPath( "//foo[@code='123']" );

// customize function, namespace and variable contexts
xpath.setFunctionContext( myFunctionContext );
xpath.setNamespaceContext( myNamespaceContext );
xpath.setVariableContext( myVariableContext );

List nodes = xpath.selectNodes( document );
</pre>
          </p>
          <p>
            Added new helper class <code>org.dom4j.util.XMLErrorHandler</code> which 
            turns SAX ErrorHandler callbacks into XML that can then be output in a JAXM or SOAP message
            or styled via XSLT or whatever.
          </p>
          <p>Added new helper method <code>DocumentHelper.makeElement(doc, "a/b/c")</code> which will
            navigate from a document or element to the given simple path, creating new elements along the way if need be.
            This allows elements to be found or created using a simple path expression mechansim.
          </p>
          <p>Added helper method getQName(String qualifiedName) to Element so that easier element name matching can be done. Here are some examples of it in use.
<pre>
// find all elements with a local name of "foo" 
// in any namespace
List list = element.elements( "foo" );

// find all elements with a local name "foo" 
// and the default namespace URI
List list = element.elements( element.getQName( "foo" ) );

// find all elements which match the local name "foo" 
// and the namespace URI mapped to the "x" prefix
List list = element.elements( element.getQName( "x:foo" ) );
</pre>
          </p>
          <p>
            Added helper method on <code>org.dom4j.DocumentFactory</code> called <code>getQNames</code>
            that returns a List of all the QNames that were used to parse the documents.
          </p>
          <p>
            Added an EntityResolver property to SAXReader to make it easier to configure a specific EntityResolver.
          </p>
        </section>

        <section name="Patches">
          <p>Added patch so that patterns such as <code>@id='123'</code> and <code>name()='foo'</code> are now
            working properly again. Also patterns such as <code>not(@id='123')</code> work now too.
          </p>
          <p>Patched the dynamic loading of classes to fix some ClassLoader issues found with some application servers.
          </p>
          <p>Ported the data type support to work with the latest MSV library from Sun
          </p>
          <p>Fixed bug spotted by Stefan Graeber that was causing a DocumentException to be thrown with Xerces
            when turning validation mode on.
          </p>
          <p>Patched bug in QName which was using the qualified name rather than the local name along with the namespace URI
            to determine equality.
          </p>
          <p>
            Added patch kindly supplied by Michal Palicka that SAXReader was passing in the wrong name for the SAX string-interning feature. Thanks Michal!
          </p>
          <p>
            Fixed the behaviour of DocumentFactory.createXPathFilter() to use XPath filtering
            rather than XSLT style patterns. One of the major differences is that an XSLT pattern
            (used in the &lt;xsl:template match="pattern"/&gt; element in XSLT) works slightly 
            differently. An element &lt;foo&gt; would match an XSLT pattern "foo" whereas an
            element &lt;bar&gt; could match an XPath filter "foo" if it contained a child &lt;foo&gt; 
            element.
          </p>
          <p>
            Patched the behaviour of Node.matches(String xpathExpression) so that it uses
            XPath filters now rather than XSLT patterns.
          </p>
          <p>
            Patched bug in XRule implementation in org.dom4j.rule that was causing ordering problems
            when using stylesheets - the Rule precendence order was not being correctly used.
          </p>
          <p>
            Backed out a previous patch added to 0.9 such that attributes with no namespace prefix are in
            no namespace. An attribute does not inherit the default namespace - the only way to put an attribute
            into a namespace is via a namespace prefix.
          </p>
          <p>
            Patched XMLWriter to that a flush() is not required when using an OutputStream 
            and the various sub-document write() methods 
            are called such as write(Element), write(Attribute), write(Node), write(Namespace) etc.
          </p>
          <p>
            Fixed bug in SAXReader that setEntityResolver() was not always behaving properly. 
            Also the default entity resolver used to locate XML Schemas seems to work properly now.
          </p>
          <p>
            Moved the XML Schema Data Type supporting classes in org.dom4j.schema.Schema* to
            org.dom4j.datatype.Datatype*. This should avoid confusion and better describe the
            intent of the classes, to implement Data typing, rather than schema validation.
            We hope to use the <a href="http://www.sun.com/software/xml/developers/multischema/">MSV</a> 
            library for all of our schema validation requirements.
          </p>
          </section>
        </section>
        <section name="0.9 release">
          <section name="Full support for the Jaxen XPath engine">
            <p>The XPath engine in dom4j has been migrated to using <a href="http://jaxen.org">Jaxen</a>.
              This single XPath engine can be plugged into any model such that Jaxen will support
              DOM, dom4j, EXML and JDOM. Hopefully we'll get Jaxen working on Java Beans too.
            </p>
            <p>
              In general this will mean a much better, more compliant and more bug-free XPath
              engine for dom4j as it will be used extensively across XML object models.
            </p>
            <p>
              Already numerous irregularities have been fixed in the XPath support in dom4j.
              We have donated the dom4j XPath test harness to Jaxen so that we now have a large
              rigorous test harness to ensure correct XPath behaviour - this test harness is run
              against all 4 current XML object models to ensure consistent behaviour and valid 
              XPath compliance.             
            </p>
            <p>
              We are also in the process of migrating over our XPath extension functions as 
              well as adding additional XPath functions such as those defined in XSLT and XPointer.
            </p>
          </section>
          <section name="New features">
            <p>New class org.dom4j.io.XMLResult which is-a JAXP Result which uses the same
                org.dom4j.io.OutputFormat object to provide its formatting options 
                to allow XML output from JAXP (such as via XSLT) to be pretty printed.
            </p>
            <p>XMLWriter now implements the SAX XMLFilter interface so that it can
              be added to a SAX parsing filter chain to output the XML being parsed in a simple way.
              Many thanks to Joseph Bowbeer for his help in this area.
            </p>
            <p>Added setProperty() and setFeature() methods to SAXReader to allow
              the easy configuration of custom parser properties via SAXReader, such
              as being able to specify the location of schema or DTD resources.
            </p>
            <p>Added new method OutputFormat.createCompactFormat() for those wishing
              to output their XML in a compact format, such as in messaging systems.
            </p>
          </section>
          <section name="Patches and bug fixes">
            <p>Fixed bug in getNamespaceForPrefix() where if the prefix is null or ""
               and there is a default namespace defined, this method was returning 
               a namespace instance with the incorrect URI. 
            </p>
            <p>Patched DOM writer so that it uses JAXP if it is available on the CLASSPATH
               using namespace aware mode by default.
            </p>
            <p>Fixed a number of issues relating to namespaces and the redefinition of namespace prefixes.
              We now have a quite aggressive JUnit test harness to ensure that we handle namespace URIs
              correctly when prefixes are mapped and unmapped.
            </p>
            <p>Applied patch from Andrew Wason for HTMLWriter to support the full
              HTML 4.01 DTD elements which do not require proper XML element closes.
              The new elements are PARAM, AREA, LINK, COL, BASE and META.
            </p>
            <p>Fixed bug found by Dennis Sosnoski that SAX warnings were causing
              exceptions to be thrown by the SAXReader. Now warnings are silently ignored.
              If you want to detect warnings then an ErrorHandler should be registered with the
              SAXReader.
            </p>
            <p>Patched bug that was also found by Jonathan Doughty for the non-standard
               behaviour of the FilterIterator. Also added Jonathan's JUnit test case
               to the distribution so that this problem should not come back. 
            </p>
            <p>Fixed bug that when round tripping into JAXP and back again, sometimes
              additional namespace attributes were appearing.
              Now the TestRoundTrip JUnit test case includes JAXP round tripping.
            </p>
            <p>Fixed bug that attributes without a namespace prefix which are inside
              an element with a default namespace declaration of the form xmlns="theURI", 
              the attribute now correctly inherits the namespace URI.
            </p>
            <p>Applied patch found by Stefan Graeber that the UserDataFactory was not
              correctly creating UserDataAttribute instances.
            </p>
            <p>Fixed bug that SAXWriter and DocumentSource were not correctly producing
            lexical events such as entities, comments and DOCTYPE declarations.
            Many thanks to Joseph Bowbeer for his help in this area.
            </p>
          </section>
        </section>
        <section name="0.8 release">
          <section name="New methods">
            <pre>hasContent()</pre>
            <p> has been added to the Node interface
              so that it is easy to decide if a node is a leaf node or not.
              This method was suggested by Dane Foster.
              This method returns true if the node is a Branch (i.e. an Element or Document)
              which contains at least one node.
            </p>
            <pre>getPath(Element context)</pre>
            <pre>getUniquePath(Element context)</pre> 
            <p>These new methods 
              allow paths and unique paths to be created relatively. Previously both
              getPath() and getUniquePath() would create absolute XPath expressions. 
              These new methods allow relative path expressions to be created by providing
              an ancestor Element from which to make the path expression.
              This method was suggested by Chris Nokleberg.
            </p>
          </section>
          <section name="Patches and bug fixes">
            <p>Fixed bug found by Chris Nokleberg when using the UserDataElement
               that the clone() and createCopy() methods were not correctly 
               copying the user data object. A JUnit test case has been added that
               tests this fix (org.dom4j.TestUserData).
               If any deep copying of user data objects is required then
               UserDataElement now has a method getCopyOfUserData()
               which can be overloaded to perform a deep copy of any user data
               objects if required.               
            </p>
            <p>Minor patch for dom4j implementors wishing to create their own 
              QName implementations. Previously the DocumentFactory class was
              hardwired to use QNameCache internally which was hard wired to 
              only create QName instances.
              Now some factory methods have been added such that you can derive 
              your own DocumentFactory which uses your own
              QNameCache which creates your own QName classes.
            </p>
            <p>If JAXP can be found in the CLASSPATH then it is now used first by
              the SAXReader to find the correct SAX parser class. 
              We have found that sometimes (e.g. Tomcat 4.0 beta 6) the value
              of the org.xml.sax.driver system property is set to a class which is not 
              in the CLASSPATH but a valid JAXP parser is present. 
              So now we try JAXP first, then the SAX system property then if all else fails
              we use the bundled Aelfred SAX parser.
            </p>
            <p>Fixed XPath bug found by James Elson that the path /foo[@a and @b] or
              /foo[@a='1' and @b='2'] was no longer working correctly. This is now fixed
              and many tests of this nature have been added to the JUnit test harness.
            </p>
            <p>Fixed some namespace related bugs found by Steen Lehmann.
              It appears that for a document of:-

           </p>
<pre>
&lt;a xmlns="dummyNamespace"&gt;
  &lt;b&gt;
    &lt;c&gt;Hello&lt;/c&gt;
  &lt;/b&gt;
&lt;/a&gt;
</pre>
           <p>Then the path /a/b/c will not find anything - this is correct according to the XPath spec.
              Instead the path /*[name()='a']/*[name()='b']/*[name()='c'] is required.
              These changes have been applied to getPath() and getUniquePath() such that
              these methods now work, irrespectively of the namespaces used in a document.
              Finally many new test cases have been added to validate a variety of XPath
              expressions with various uses of namespaces.
            </p>
           <p>SAXWriter now fully supports the SAX feature "http://xml.org/sax/features/namespace-prefixes".
              Failure to support this feature properly was causing problems
              when outputting a dom4j Document using JAXP - the namespace declarations often did not appear correctly.
            </p>
           <p>Patched bug in XMLWriter which caused multiple duplicate namespace declarations to sometimes appear.
            </p>
          </section>
        </section>
        <section name="0.7 release">
          <section name="Integration with SAXPath">
            <p>The <a href="http://saxpath.org">SAXPath</a> project is a 
              Simple API for XPath parsing. Its analogous to
              SAX in that the API abstracts away the details of parsing XPath 
              expressions and provides a simple event based callback
              interface. 
             </p>
            <p>
              Originally dom4j was using a parser generated via the <a href="http://antlr.org">Antlr</a> tool
              which resulted in a considerably larger code base. 
              Now dom4j uses SAXPath for its XPath parsing which results in faster XPath parsing 
              and a much smaller code base. 
             </p>
            <p>
              The dom4j.jar is now about 100 Kb smaller!
              Also several XPath related bugs are now fixed. For example the numeric paths like '2 + count(//foo)' are now working.              
             </p>
         </section>
          <section name="Patches and bug fixes">
            <p>Fixed bug found by Tobias Rademacher that XML Schema Data Type support
            wasn't working correctly when the XSD document used a namespace prefix.
            The bug was hidden by a further bug in the JUnit test case that was not correctly
            testing this case. Both these bugs are now fixed.
            </p>
            <p>Fixed bug found by Piero de Salvia that some invalid XPath expressions were not correctly
            throwing exceptions. Now any attempt to use any invalid XPath expressions should result
            in an 
              <a href="apidocs/org/dom4j/InvalidXPathException.html">InvalidXPathException</a>
            being thrown.
            </p>
            <p>Applied patch submitted by Theodor Schwarzinger that fixes the preceding-sibling and preceding axes.
            </p>
            <p>Fixed bug found my James Elson that the normalize() method was being quite agressive and removing 
              all text nodes! New JUnit test case added to ensure this doesn't break again.
            </p>
            <p>Improved the setContent() semantics on Branch (and so Element and Document) such that the 
              parent and document relationships are correctly removed for old content and added for new content.
              As a helper method, the setContent() method will clone any content nodes which are already
              part of an existing document. So for example the following code will clone the content of a document.
<pre>
    Document doc1 = ...;
    Document doc2 = DocumentHelper.createDocument();  
    doc2.setContent( doc1.content() );
</pre>
              Though this behaviour is much more useful when used with elements...
<pre>
    Element sourceElement;
    Element destElement;

    // copy the content of sourceElemenet
    destElement.setContent( sourceElement.content() );
</pre>
            </p>
          </section>
        </section>
        <section name="0.6 release">
          <section name="Serialization support added">
            <p>Support has been added for Java Serialization so dom4j documents can be serialized over RMI or EJB calls.
            Note that currently Serialization is <i>much</i> slower (by a factor of 2-5 times) than using the textual format of
            XML so we recommend sending XML text over RMI rather than serialization if possible. Over time we will tune
            the serialization implementation to be at least as fast as using the text format (even if that means under the 
            covers we just use the text format).
            </p>
          </section>
          <section name="Patches and bug fixes">
            <p>Fixed bug in XPath engine found by Christophe Ponsard
              for paths of the form /* which were not finding
              anything. Now we have an extensible XPath test harness (in src/test/org/dom4j/TestXPathExamples.java)
              which contains some test cases for these kinds of paths. We can extend these cases
              to test other XPath expressions easily.
            </p>
            <p>Fixed bug in elementByID() method found by Thomas Nichols that was resulting in
              the element not being found correctly.
            </p>
            <p>Fixed bug in IndexedElement reported by Kerstin Gr�nefeld that was causing
              a null pointer exception when using XPath on an IndexedElement.
            </p>
            <p>Applied the patch supplied by Mike Skells that fix problems with the
              getUniquePath() method not returning properly indexed elements
            </p>
            <p>Applied a fix to the problem found by Dane Foster when using dom4j with JTidy.
              JTidy returns null for getLocalName() so DOMReader has been patched to handle
              nulls returned from either getLocalName() or getName().
            </p>
            <p>Fixed bug reported anonymously to the Sourceforge Site
              <a href="http://sourceforge.net/tracker/index.php?func=detail&amp;aid=436670&amp;group_id=16035&amp;atid=116035">
              here
              </a>
              that explicitly creating a Document from an existing Element could cause problems when
              using XMLWriter.
            </p>
            <p>Assorted performance tunings of SAX parsing, avoiding unnecessary repeated code paths.
            </p>
            <p>Tidied factory and construction of Element code such that there are no longer
            dependencies on the SAX Attributes class. This was originally added as a performance
            enhancement, but after further refactoring this is now no longer needed.
            This makes the process of creating new Element derivations or DocumentFactory
            implementations easier.
            </p>
          </section>
        </section>

        <section name="0.5 release">
          <section name="NodeComparator available">
            <p>For those wishing to do value based comparisons of Nodes, 
              Element, Attributes, Documents or Document fragments
              there is a new 
              <a href="apidocs/org/dom4j/util/NodeComparator.html">NodeComparator</a>
              class which implements the 
              <a href="http://java.sun.com/j2se/1.3/docs/api/java/util/Comparator.html">Comparator</a>
              interface from the Java Collections Framework.
            </p>
          </section>
          <section name="New helper method DocumentHelper.parseText()">
            <p>A new helper method has been added for parsing text.
              For example:-
            </p>
<pre>
    Document document = DocumentHelper.parseText(
        "&lt;team&gt; &lt;author&gt;James&lt;/author&gt; &lt;/team&gt;"
    );
</pre>

          </section>
          <section name="New Branch.normalize() method">
            <p>The Branch interface (and so Document and Element interfaces) has 
              a new normalize() method that has the same semantics as the same method 
              in the DOM API to remove empty Text nodes and merge adjacent Text nodes.
            </p>
          </section>
          <section name="Easier document building methods">
            <p>A document can now be constructed more easily now that the addXXX() methods
              return a reference to the Document or Element which created them.
              An example is shown below
            </p>
<pre>
import org.dom4j.Document;
import org.dom4j.DocumentHelper;
import org.dom4j.Element;

public class Foo {

    public Document createDocument() {
        Document document = DocumentHelper.createDocument();
        Element root = document.addElement( "root" );

        Element author1 = root.addElement( "author" )
            .addAttribute( "name", "James" )
            .addAttribute( "location", "UK" )
            .addText( "James Strachan" );
        
        Element author2 = root.addElement( "author" )
            .addAttribute( "name", "Bob" )
            .addAttribute( "location", "Canada" )
            .addText( "Bob McWhirter" );

        return document;
    }
}
</pre>
            <p>
              Note that the addElement() method returns the <b>new</b> child element
              not the parent element.
            </p>
            <p>
              To promote consistency, the Element.setAttributeValue() method is now deprecated
              and should be replaced with Element.addAttribute().
            </p>
          </section>
          <section name="Patches and bug fixes">
            <p>Applied Theo's patch for cloning of Documents correctly 
              together with JUnit test cases to ensure this keeps working.
            </p>
            <p>Applied Rob Wilson's patch that NullPointerExceptions 
              were being thrown if a Document is output with the XMLWriter
              and an attribute value is null.
            </p>
            <p>Fixed problem found by Nicolas Fonrose that XPath expressions
              using namespace prefixes were not working correcty.
            </p>
            <p>Fixed problem found by Thomas Nichols whereby default namespaces
              with no prefix were not being processed correctly. 
              As a result of finding this bug we now have a rigorous JUnit round trip test 
              harness in place which highlighted a number of issues with namespaces when
              round tripping from dom4j to SAX to DOM to Text and back again.
              These issues have now been fixed and should not show up again hopefully.
            </p>
            <p>Fixed some detach() bugs that were found with Attributes.
            </p>
            <p>Default encoding is now "UTF-8" rather than "UTF8". Thanks to
              Thomas Nichols for spotting that one. Also the default 
              line seperator when using XMLWriter is now "\n" rather than "\r\n"
            </p>
            <p>If an XMLWriter is used with an OutputStream then an explicit call to 
            flush() is no longer required after calling write(Document)
            </p>
            <p>Some housekeeping was performed in the naming of some implementation classes.
              The old XPathXXX.java classes in the org.dom4j.tree package 
              where XXX = Attribute, CDATA, 
              Comment, Entity, ProcessingInstruction and Text have been renamed to
              DefaultXXX and the corresponding DefaultXXX has been renamed to
              FlyweightXXX. This makes it clearer the purpose of these implementation
              classes. The default implementations of the leaf nodes are mutable but cannot
              be shared across elements. The FlyweightXXX implementations are immutable
              and can be shared across nodes and documents.
            </p>
          </section>
        </section>

        <section name="0.4 release">
          <section name="Enhanced event notification mechanism">
            <p>A new enhanced event notification mechanism has been implemented
              by David White.
              Now you can register multple
              <a href="apidocs/org/dom4j/ElementHandler.html">ElementHandler</a>
              instances with a 
              <a href="apidocs/org/dom4j/io/SAXReader.html">SAXReader</a>
              object before you parse a document such that the different
              handlers are notified when different paths are reached.
            </p>
            <p>
              The <a href="apidocs/org/dom4j/ElementHandler.html">ElementHandler</a>
              interface now has both <code>onStart()</code> and <code>onEnd()</code>
              allowing more fine grained control over when you are called
              and the ability to perform actions before or after the content
              for an Element is populated.
              The methods also take a reference to a 
              <a href="apidocs/org/dom4j/ElementPath.html">ElementPath</a>
              to allow more optimised and powerful access to the path to the specified document.
            </p>
          </section>
          <section name="Early alpha release of XML Schema Data Type support">
            <p>This release contains an alpha release of XML Schema Data Type
            support.  
            The main class in question is the XML Schema Data Type aware
            <a href="apidocs/org/dom4j/datatype/DatatypeDocumentFactory.html">DatatypeDocumentFactory</a>            
            which will create an XML Schema Data Type aware XML object model.
            </p>
            <p>
              The <code>getData()</code> and <code>setData(Object)</code> methods
              on 
              <a href="apidocs/org/dom4j/Attribute.html">Attribute</a> and            
              <a href="apidocs/org/dom4j/Element.html">Element</a>            
              allow access to the concrete data types such as Dates and Numbers.
            </p>
          </section>
          <section name="Patches and bug fixes">
            <p>Applied Theo's patch for the XPath <code>substring</code> function 
              that was causing the incorrect string indexes to be returned.
              The <code>substring</code> now returns the correct answer.
            </p>
            <p>Applied Theo's patch for incorrectly escaping of element text.
            </p>
            <p>Fixed bug in the XPath engine for absolute path expressions which 
              now work correctly when applied to leaf nodes.
            </p>
            <p>Fixed bug
              in the <code>name()</code> and <code>local-name()</code> 
              functions such that the following expressions now work fine
              <code>local-name(..), name(parent::*)</code>.
            </p>
          </section>
          <p>A variety of minor performance tuning optimisations have been made.
          </p>
        </section>

        <section name="0.3 release">
          <p>The <code>org.dom4j.io.OutputFormat</code> class now has a new helper
            method to make it easier to create pretty print formatting objects.
            The new method is <code>OutputFormat.createPrettyPrint()</code>.
            So to pretty print some XML (trimming all whitespace and indenting nicely)
            the following code should do the job...
          </p>
<pre>
    OutputFormat format = OutputFormat.createPrettyPrint();
    XMLWriter writer = new XMLWriter( out, format );
    writer.write( document );
    writer.close();
</pre>
          <p><code>SAXReader.read(String url)</code> can now accept either 
            a URL or a file name which makes things a little easier.
            The logic uses the existence of a ':' in the url String to determine if
            it should be treated as a URL or a File name. 
          </p>
          <p>For more explicit control over whether documents are Files or URLs
            call <code>SAXReader.read(File file)</code> or <code>SAXReader.read(URL url)</code>
          </p>
          <p>A new extension function, <i>matrix-concat()</i> was submitted by 
          James Pereira.
          By default, doing <i>concat()</i> functions in XPath the 'string-value' is taken
          for each argument.
          So for a document:-</p>
<pre>
&lt;root project="dom4j"&gt;
    &lt;contributor&gt;James Pereira&lt;/contributor&gt;
    &lt;contributor&gt;Bob McWhirter&lt;/contributor&gt;
&lt;/root;&gt;
</pre>
        <p>Then the XPath</p>

<pre>
concat( 'thanks ', /root/contributor )
</pre>

        <p>would return</p>

<pre>
"thanks James Pereira"
</pre>

      <p>as the <i>/root/contributor</i> expression matches a node set of 2 
      elements, but the "string-value" takes the first elements text.
      Whereas <i>matrix-contact</i> will do a cartesian product of all the 
      arguments and then do the concatenation of each combination of nodes. So
      </p>

<pre>
matrix-concat( 'thanks ', /root/contributor )
</pre>

      <p>will produce</p>

<pre>
"thanks James Pereira"
"thanks Bob McWhirter"
</pre>

      <p>The cartesian product is done such that multiple paths can be used.
      </p>

<pre>
matrix-concat( 'thanks ', /root/contributor, ' for working on ', '/@project' )
</pre>

      <p>will produce</p>

<pre>
"thanks James Pereira for working on dom4j"
"thanks Bob McWhirter for working on dom4j"
</pre>

      <p>Fixed bug where <code>XMLWriter.write(Object)</code> was not correctly
        writing a Document instance.
      </p>
      <p>Finally, a couple of small issues with the build process have been fixed.
      The dom4j.jar no longer contains any SAX or DOM classes (they are all in dom4j-full.jar)
      And the Antlr grammar files for the XPath parser are now corrrectly 
      included in the binary  distribution.
      </p>
        </section>
 
        <section name="0.2 release">
          <p>There following new features were added:-
          </p>
          <ul>
            <li>Clean integration with XSLT via JAXP / TrAX API.
            </li>
            <li>New SAXValidator to allow validation on prebuild Document instances
            </li>
            <li>XMLWriter and HTMLWriter rewritten so that they work at either 
                the SAX level or the dom4j level. 
                API much improved and more like Reader and Writer in the JDK.
            </li>
            <li>API modified to avoid clashes with WC3 DOM such that a dual 
                implementation of dom4j and DOM is now possible. An early alpha
                release of a DOM implementation of dom4j is available.
            </li>
            <li>New sorting method added to Node for easier selections of nodes
              which are sorted via an XPath expression. The following
              code sorts all CUSTOMER elements by their name attributes and 
              removes duplicates:-
              <pre>
Document document 
  = new SAXReader().read( new File( "customers.xml" ) );

List customers 
  = document.selectNodes( "//CUSTOMER", "@name", true );
              </pre>
            </li>
            <li>The getText() and getStringValue() methods of Element now return
              the textual values of CDATA, Entity and Text nodes. 
              The previous version only returned Text node values.
            </li>
            <li>Refactored code and removed XPathEngine, XPathHelper and 
                all the static newXXX() methods in DocumentFactory.
                Added equivalent methods to DocumentHelper and DocumentFactory.
            </li>
          </ul>
          <p>This release also includes full XPath source code.
          </p>
        </section>
        <section name="0.1 release">
          <p>Initial release which comes complete with DOM, JAXP and SAX 
            support and integrated XPath
          </p>
        </section>
 
    <section name="To Do List">
      <ul>
        <li>The internal subset does not pass through DOMReader and DOMWriter. This needs patching!
        </li>
        <li>We should add support for Xerces XNI API via an XNIReader and XNIWriter. This would also allow
          dom4j users to make good use of the NekoHTML parser thats layered on top of XNI.
        </li>
        <li>Better documentation and user guides
        </li>
        <li>A lazy parser; implement a special Element implementation (or probably a special List)
          which allows the XPP (XML Pull Parser) to parse the document as it is navigated rather than
          all up front.
        </li>
        <li>Build a dom4j validator based on top of Suns MSV library
        </li>
        <li>Ensure that the optional DOM implementation passes the DOM compliance tests
        </li>
        <li>Implement a ValidatingDocumentFactory and an EncodingDocumentFactory
          which can be used by developers where invalid strings may be specified
          allowing validation or encoding of names or text values to be
          done in one place for use across parsers or application code.
          This would avoid any performance hit by making this kind of validation 
          the default behaviour.
        </li>
        <li>Implement a canonical XML processor
        </li>
        <li>Implement XML Signature
        </li>
        <li>Implement XPointer, XLink and XInclude
        </li>
        <li>Build a version of XMLC which uses the dom4j API rather than DOM which
          could also make use of XPath, XSLT and Java 2 Collections support.
        </li>
        <li>
          Consider adding support for 
          <a href="http://developer.java.sun.com/developer/earlyAccess/adding_generics/">Java Generics</a> 
          such that typesafe Iterators can be used. For example
          <pre>
Iterator&lt;Node&gt; iter = element.nodeIterator();
while ( iter.hasNext() ) {
    Node node = iter.next();
}

Iterator&lt;Element&gt; iter2 = element.elementIterator( "foo" );
while ( iter2.hasNext() ) {
    Element foo = iter2.next();
}
          </pre>
        </li>
        <li>Implement XSLT engine on top of <i>dom4j</i>?
        </li>
        <li>XML Query implementation on top of <i>dom4j</i>?
        </li>
      </ul>
    </section>

    <section name="Known problems">    
      <p>The following functions are not yet fully supported in the inbuilt
        XPath engine</p>
      <ul>
        <li>id()</li>
        <li>generate-id()</li>
        <li>format-number()</li>
      </ul>
      <p>The optional W3C DOM implementation of the dom4j API is not yet at 
      full DOM compliance</p>
    </section>

    <section name="Contributors">    
      <p>The following people have contributed to the dom4j project. 
      Many thanks to you all!</p>
      <ul>
        <li>James Strachan</li>
        <li>Bob McWhirter</li>
        <li>James Dodd</li>
        <li>James Elson</li>
        <li>Jakob Jenkov</li>
        <li>James Pereira</li>
        <li>David White</li>
        <li>Tobias Rademacher</li>
        <li>Rashmi Mathew</li>
        <li>Jonathan Doughty</li>
        <li>Joseph Bowbeer</li>
        <li>Michal Palicka</li>
        <li>Yuxin Ruan</li>
        <li>Steen Lehmann</li>
        <li>Maarten Coene</li>
        <li>Stefan Graeber</li>
      </ul>
    </section>

  </body>
</document>
