* * * * * * Beta8 (tag: jdom_1_0_b8) from Beta7 (tag: jdom_1_0_b7) * * * * * * NEW CLASSES ----------- Added a Text class. This class is primarily for internal use to store String data, so strings can now have parentage. A getText() will still return a String. The Text nodes themselves can be retrieved through a getContent() call. Added the public interface org.jdom.filter.Filter to support the "FilterList" functionality. Added org.jdom.filter.ContentFilter, a standard filter for Content. And added org.jdom.filter.ElementFilter, a standard filter for Element data. Added two non-public support classes to support the "FilterList" functionality: ContentList and AttributeList. NEW METHODS ----------- Added to Element and Document the method getContent(Filter) that takes a Filter instance. Added to CDATA the methods getTextTrim(), getTextNormalize(), append(String), append(CDATA), getParent(), getDocument(), and detach(). This brings CDATA close in line with the Text class. They'll may become the same class with a flag differentiator in the next beta. Added to Element the methods addContent(Text) and removeContent(Text). These methods support the new Text class. Also added to Element the method removeAttribute(Attribute). This method was simply overlooked before. Also added to Element the method getChildTextNormalize(). This method is similar to getChildTextTrim(). Also added to Element two new styles of getAttributeValue() which let the programmer specify default values if the attribute doesn't exist. Added to SAXBuilder the methods setFeature() and setProperty(). These methods to allow programmers to customize the underlying parser. Added to SAXOutputter the new method setLexicalHandler(LexicalHandler). Also added a new SAXOutputter constructor that takes a LexicalHandler as its last argument. Added to ProcessingInstruction the method getNames(). This method returns the pseudo-attribute names in the PI's data. Added to DocType the methods setInternalDTDSubset(String) and getInternalDTDSubset(). These methods support new functionality where a DocType can store and alter the internal DTD subset information. Also added to DocType the method setElementName(). Added a no-arg SAXOutputter constructor. Added to SAXOutputter the methods getContentHandler(), getErrorHandler(), getDTDHandler(), getEntityResolver(), getLexicalHandler(), setDeclHandler(), getDeclHandler(), setFeature(), setProperty(), getFeature(), and getProperty(). Added to Attribute the methods getAttributeType() and setAttributeType(). Also added various constructors that take an int type. These methods and constructors support the new functionality where attributes can record their type information. Note: this is something DOM can't do! Added to Document the method detachRootElement(). Added to XMLOutputter the methods outputString(List list), outputString(String str), outputString(Text text), output(List list, OutputStream out), and output(List list, Writer out). Added to EntityRef the constructor EntityRef(String name, String systemID). This supports building an EntityRef without a public ID. Added to Verifier the methods checkSystemLiteral() and checkPublicID(). NEW CONSTANTS ------------- Attribute has new constants for each attribute type: UNDECLARED_ATTRIBUTE, CDATA_ATTRIBUTE, ID_ATTRIBUTE, IDREF_ATTRIBUTE, IDREFS_ATTRIBUTE, ENTITY_ATTRIBUTE, ENTITIES_ATTRIBUTE, NMTOKEN_ATTRIBUTE, NMTOKENS_ATTRIBUTE, NOTATION_ATTRIBUTE, and ENUMERATED_ATTRIBUTE. NEW SIGNATURES -------------- The XMLOutputter escape*() methods are now public. The Verifier checkXMLName() method is now public. Changed the protected "Element parent" variable for classes to be "Object parent", with the object capable of serving double duty as either a Document parent or Element parent. Saves noticeable memory. Changed the no-arg Document constructor to be public, along with Javadocs explaining how the method is to be used. REMOVED CLASSES --------------- None. REMOVED METHODS --------------- Removed the methods deprecated in beta7. DEPRECATED METHODS ------------------ Deprecated the DOMBuilder.build() methods that build from a File, URL, or InputStream. This helps people understand those methods are for testing only. DOMBuilder.build(org.w3c.dom.Document) and such are still undeprecated. ENHANCEMENTS ------------ Added the long-awaited "FilterList" functionality! This improves the reliability and performance of the lists returned by getContent() and getChildren() calls. These lists are now fully live, they fully enforce well-formedness constraints, and they don't require in-memory copying before returning. A huge improvement! Integrated the Text class for wrapping strings behind the scenes and thus allowing strings to have parentage. Added the ability for the DocType to have an internal DTD subset, and changed the SAX and DOM builders and outputters to support this change. Added the ability for a Document to have a detached root to make elt.detach() work easily. There will be an IllegalStateException thrown in case of read from such a Document. Added support for "attribute types". Typing is now recorded within the attribute object and fully managed during build and output. Rearchitected the internals of SAXBuilder and SAXHandler to be more extensible via subclassing. Also exposed more of the internals of SAXHandler to make subclassing easier. Made SAXOutputter much more robust, and made JDOMSource (used for transformations) more robust along with it. Changed setContent(null) to now clear the content list and does not throw an exception. Same for setChildren(null). Improved XMLOutputter to respect the xml:space attribute. Improved reporting behavior of build error messages. Improved how JDOMException reports on nested exceptions. Updated the Ant build system to version 1.4. Improved JDOM build versioning so we have versions like "1.0beta8-dev" for work after Beta8, and "1.0beta8" will only be the actual Beta8 code. Changed the Javadocs to use CVS Revision and Date tags for @version. Many Javadoc clarifications. Improved the Verifier error message when adding a PI with an "xml" target, since parsers and/or people have been trying to add it as a PI. Added verification of the system and public ID's in both DocType and EntityRef, the root element name in DocType, and the entity name in EntityRef. Added ability for DocType and EntityRef to differentiate a missing ID from the empty string ID. Changed the MANIFEST.MF to no longer list Xerces in the Class-Path entry, nor to have JDOMAbout as its Main-Class. This helps applet deployment, but does remove the ability to do the cool "java -jar jdom.jar". Added support for skipped entities in SAXHandler in the event that the parser is not resolving external entities. Added well-formedness checking to ensure there are never duplicate attributes. Many, many performance optimizations throughout. Made Xerces 1.4.4 the default parser in "lib/xerces.jar". BUG FIXES --------- Fixed XMLOutputter to no longer add spurious newlines after closing element tags. Fixed SAXBuilder to work better with XML filters. Fixed SAXHandler bug where attributes that had a namespace were being added to the Document, but did not have the Namespace correctly reported. Fixed bug where a ProcessingInstruction or DocType removed from a Document did not have its parentage set to null. Fixed bug where SAXBuilder would cache the class name even when using JAXP to create the parser, causing problems for parsers without no-arg constructors. Fixed bug where Namespace collision checking could generate false positives. Fixed bug where a document containing a huge number of character entities would cause JDOM builds to slow down exponentially. Fixed the many bugs caused by the old PartialList code, by replacing it with FilterList code. * * * * * * Beta7 (tag: jdom_1_0_b7) from Beta6 (tag: jdom_1_0_b6) * * * * * * NEW CLASSES ----------- Added JDOMSource and JDOMResult to the org.jdom.transform package. These support XSLT transforms using the JAXP TRaX model. Added Crimson, JAXP, and Xalan JARs to the lib directory to support the transform functionality. Added org.jdom.EntityRef to replace org.jdom.Entity. Changed methods taking Entity to take EntityRef. Made org.jdom.input.SAXHandler a public class. It used to be package protected. This is helpful to classes that want to build JDOM from a SAX source, such as JDOMResult. Added org.jdom.input.JDOMFactory/DefaultJDOMFactory to support the builder factory model. Added org.jdom.adapters.JAXPDOMAdapter to contain all the logic for interacting with JAXP. Most people will never use this class. Added org.jdom.Text to the repository. It's not yet used. NEW METHODS ----------- Added a new detach() method to each of the classes Attribute, Comment, Element, EntityRef, and ProcessingInstruction. It removes the node from its parent. Added setName(String) and setNamespace(Namespace) to Element and Attribute. Added elt.setAttribute() method, to replace elt.addAttribute(). It replaces any existing attribute by the same name, instead of throwing an exception as addAttribute() did. Added elt.getContent() and elt.setContent() methods, to replace elt.getMixedContent() and elt.setMixedContent(). Did the same on Document. Added SAXBuilder.setExpandEntitities(boolean) method to indicate if entities should be expanded, or if EntityRef objects should appear within the document. Added two new Document constructors to support constructing with a list of content: Document(List) Document(List, DocType) Added elt.removeNamespaceDeclaration(Namespace). It removes a namespace declaration, the counterpart to addNamespaceDeclaration(Namespace). Added a new constructor in IllegalAddException to account for a Namespace illegally added: IllegalAddException(Element base, Namespace added, String reason) Added getDocument() method to DocType. Added a protected setDocument() method also. Added setFactory() method to SAXBuilder/DOMBuilder to support the factory build model. Added elt.getTextNormalize() to return a normalized string (external whitespace trimmed, internal whitespace reduced to a single space). The getTextTrim() method now does a true trim. Added a SAXBuilder.setIgnoringElementContentWhitespace(boolean) method with behavior that matches the method by the same name in JAXP's DocumentBuilderFactory. Setting the value to true causes ignorableWhitespace() to operate like a no-op. By default its value is false. Added getCause() to JDOMException, replacing getRootCause(). This new name matches JDK 1.4. Added setOmitDeclaration on XMLOutputter, replacing the now-deprecated setSuppressDeclaration(). Added elt.removeContent(CDATA) which was previously overlooked. Added protected methods in SAXBuilder to make it easier to extend: protected XMLReader createParser() protected SAXHandler createContentHandler() protected void configureContentHandler(SAXHandler) Added getDocument() method to Attribute. NEW SIGNATURES -------------- DOMAdapter methods now may throw Exception instead of IOException. DOMBuilder and DOMOutputter have the same API as always. Changed XMLOutputter's protected printXXX() methods to have a new signature without the "int indentLevel" final parameter. Didn't bother with deprecation. Changed XMLOutputter's printEntity() method to printEntityRef(). Made SAXBuilder's build(InputSource) method public. It used to be protected. REMOVED CLASSES --------------- Removed org.jdom.Entity; it's replaced by EntityRef. REMOVED METHODS --------------- Removed various methods that were previously deprecated in beta6: Document.addContent(Element) Namespace.getNamespace(String prefix, Element context) CDATA.setText(String) Removed Document's protected rootElement variable. DEPRECATED METHODS ------------------ Deprecated constructor Attribute(String name, String prefix, String uri, String value). Its parameter order was non-standard and it was not a useful method. Deprecated XMLOutputter's setIndentLevel() method. Having a global indent is better done with a stacked FilterOutputStream. The method is now empty. Deprecated XMLOutputter's setPadText() method. It's not needed with the current output mechanism. The method is now empty. Deprecated Element's getCopy(String) and getCopy(String, Namespace). These can better be done now with a clone() and setName()/setNamespace(). Deprecated elt.addAttribute(). It's replaced by elt.setAttribute(). Deprecated getMixedContent() and setMixedContent() on Element and Document. They're replaced by getContent() and setContent() versions. Deprecated getSerializedForm() methods on all objects, and moved the logic into XMLOutputter. Deprecated the various xxxProcessingInstruction() methods in Document: List getProcessingInstructions() List getProcessingInstructions(String target) ProcessingInstruction getProcessingInstruction(String target) boolean removeProcessingInstruction(String target) boolean removeProcessingInstructions(String target) Document setProcessingInstructions(List pis) Deprecated the SAXHandler constructor SAXHandler(Document document) since now the handler constructs the document itself. Deprecated elt.hasMixedContent() because it's of little use and its behavior isn't well defined. Deprecated getRootCause() on JDOMException in favor of getCause(). This new name matches JDK 1.4. Deprecated XMLOutputter's setSuppressDeclaration() in favor of setOmitDeclaration() to better match setOmitEncoding(). Deprecated elt.addAttribute(String name, String prefix, String value). Instead, setAttribute() should be used. ENHANCEMENTS ------------ Clarified and improved many, many javadocs. Performance enhancement for files with namespaces. This improves build times on one test from 13000ms to 580ms. Added support for the DOM DocumentType object when constructing documents using DOMOutputter. Added a check that only one element is allowed in the document list as the root. Added informational XML files in the jdom.jar META-INF directory storing things like the version, credits, description, etc. These can be accessed with a "java -jar jdom.jar" command which uses JDOM to read the info about JDOM. Added JDOM version info to the MANIFEST.MF so servlets and such can depend on it using http://java.sun.com/j2se/1.3/docs/guide/extensions/versioning.html Made elt.setMixedContent() check object types and parentage, and set parentage. For the JDK 1.1 build, added a replace target so @throws is replaced by @exception, which is the old JDK 1.1 javadoc keyword. Improved XMLOutputter internals so it no longer uses list.get(i) and instead uses an Iterator. Should lighten the burden on outputting large documents. Added CVS $Id: CHANGES.txt,v 1.8 2002/03/12 07:35:58 jhunter Exp $ variable to the top of each file for better tracking. Changed pi.getValue("nonexistant") to return null instead of "". Also made it so that any parse error aborts and clears the parse results. Created a new implementations of clone() without any constructor calls. Revamped XMLOutputter's output logic to better match expectations. Changed XMLOutputter flushing logic so output() methods handle their own flush() at the end of writing so user flush() calls should no longer be necessary. Made elt.setMixedContent() and doc.setMixedContent() appear atomic, even in case of failure. Optimized attr.getQualifiedName() implementation for speed. Added logic to setAttribute() to ensure well-formedness by verifying the attribute namespace prefix doesn't collide with an existing prefix on that element (either on the element's own ns, an additional ns, or another attribute's ns). Added logic to addNamespaceDeclaration() to ensure the prefix doesn't collide with an existing prefix on the element. Changed DocType.equals() to check for equivalency and not reference equality. Now two DocTypes are equals() if their constituent strings are equals(). This makes general sense because if you want to compare the doctypes of two docs you want to do an equivalency check. Added a private CVS_ID variable to the core classes containing RCS variables. This allows you to examine the compiled class to determine the source from which it was compiled. See jdom-contrib's Ident.java. Performance optimization in setAttribute() so that removeAttribute() on a pre-existing attribute is only called when necessary, as determined by an earlier scan through the attributes. This was submitted by Phil Nelson who says it gave an 8% time savings during a fresh build. Integrated the factory model for SAXBuilder. See the new classes DefaultJDOMFactory and JDOMFactory. Changed Element.getTextTrim() behavior to truly be only a trim(). It used to do normalization. Changed Document and Element internal LinkedList implementation to ArrayList. This change of list gives us a remarkable reduction in memory sizes for all large documents tested, and gives a speed boost too. Changed Element parentage so only one variable is used for the parent. It may be of type Element or Document depending on where the elt is placed in the tree. This saves one instance variable's worth of memory for each element in the tree. Added a new line after the DocType always, for better formatting. Made the SAXHandler smart enough to ignore xmlns attributes. They shouldn't appear when SAXHandler is used with SAXBuilder but sometimes appear with driven by a different parser, such as with JDOMResult. Made note that elt.getAdditionalNamespaces() returns an unmodifiable list, and made the implementation enforce the rule. This change allows Namespace.equals() to be implemented to compare URIs instead of resorting to ==, and more importantly it avoids having XMLOutputter trigger a new List object creation for every element with an empty additional namespace list (which is 99.9% of elements). Refactored SAXBuilder to make it easier to extend. * The parser is created in a separate createParser() method, and configured in a separate configureParser() method. * The content handler is created in a separate createContentHandler() method, and configured in a separate configureContentHandler() method. Improved builder exception handling to if anything in the build process throws a JDOMException, we no longer wrap it in another JDOMException; we just rethrow as-is. Made XMLOutputter expose its NamespaceStack using an inner class, so subclassers could have access to the stack. BUG FIXES --------- Fixed bug where Element.clone() didn't copy over PIs. Made DOMOutputter check if there was a pre-existing root element on a new document, and if so call replaceChild() instead of appendChild(). This is necessary for Xerces 1.3 where new documents are created with a default element. Fixed a bug where Attr output(Attribute) wasn't using JAXP. Improved the logic by which ProcessingInstruction parses attribute-style values. The old logic was confused by whitespace, nested quotes, etc. Added sanity check in DOMBuilder to ignores null NodeList and Node entries. Per the DOM2 spec neither should ever be null, but that doesn't mean some DOM implementations don't return null. Fixed bug in Namespace.getNamespace() where the lookup for a pre-existing identical namespaces would fail even if there was a pre-existing identical namespace. This caused new Namespaces to be created on all Namespace.getNamespace() calls! Fixed bug where elt.clone() would concatenate adjacent strings. Fixed bug in elt.hasChildren() where the logic could be confused if there was a subclass of Element in the tree. Fixed the Javadoc on Element.getAdditionalNamespaces() to say it returns an empty list if empty. It used to say null. Empty is consistent with JDOM elsewhere. Fixed bug where adding a null to a setMixedContent() method would cause an NPE while constructing the error message. Fixed bug in SAXHandler where namespaces weren't being removed from the available list, causing memory bloat. Fixed DOMBuilder so it works better on non-namespace-aware documents. Now if getLocalName() returns null we look for a specific tagname/attname. Added ignorableWhitespace() method to SAXHandler to capture ignorable whitespace. It can be turned off with builder.setIgnoringElementContentWhitespace(true). Changed Namespace.equals() to check equivalency based only on URI. It used to be both URI and prefix. This new behavior is more in line with standard XML. It's unlikely but possible that existing code might break because of this, if any code puts Namespace objects into a collection and doesn't expect namespaces with different prefixes to be treated identically. No deprecation is possible though. Also fixed behavior of Namespace.hashCode() to depend solely on the URI. Fixed bug where DOMOutputter creates nodes with "" as their node.getNamespaceURI() even if the node is not in a namespace. Changed attribute value escaping to not escape single-quotes because it's not necessary as attribute values are always surrounded by double-quotes. Made sure XMLOutputter doesn't print the newline after the decl if the decl is suppressed. Fixed SAXOutputter to declare namespaces using start/endPrefixMapping methods. Also added optional ability for SAXOutputter to report namespace declarations (the xmlns: attributes) if setReportNamespaceDeclarations() is true. Fixed performance bug where namespaces were continuously being added to the availableNamespaces list unnecessarily, causing roughly as many entries to be added as there were elements with namespaces. In simple testing, memory usage for representing a namespace-intensive file went from 1.4 Megs to 460K. Fixed addFirst() and addLast() in PartialList to work correctly. Fixed a bug in PartialList where addAll() added *before* the last element instead of after. Made PartialList's addAll() method work OK if the backing list is non-empty while the PartialList is empty. Fixed build scripts to work OK on Windows with spaces in directory paths. NEW ARCHIVES ------------ Added new *searchable* mailing list archives at http://www.servlets.com/archive/servlet/SummarizeList?listName=jdom-interest * * * * * * * * * * Beta6 from Beta5 * * * * * * * * * * NEW CLASSES ----------- Added new class org.jdom.input.BuilderErrorHandler as a default error handler for JDOM builders. It ignores warnings but throws on errors and fatal errors. Added a Crimson adapter CrimsonDOMAdapter.java, to support the parser slated to come with JAXP 1.1. NEW METHODS ----------- Added parentage for Attribute, Comment, Element, Entity, and PI! They all now have getParent() methods. All but Attribute have getDocument() methods also. The addContent() and addAttribute() methods now check parentage and don't allow an item to be added if it's already held by another. Added to Element the method Namespace getNamespace(String prefix). It returns the Namespace in scope with the given prefix. It helps with attributes whose values include namespaces, like . Added DOMBuilder.setValidation(boolean) to set the validate flag after construction, to match SAXBuilder. Added DOMOutputter.output(Attribute) methods. Added XMLOutputter.setExpandEmptyElements() to choose between and . Many new XMLOutputter methods for outputting document fragments. SAXBuilder now has a setXMLFilter() method to allow setting of XMLFilter objects to operate during the build. Added to Element a hasChildren() method. Added various removeContent() methods on Element. They were deprecated and scheduled for removal, but they're now being kept. Added various removeContent() methods on Document. These are brand new. NEW SIGNATURES -------------- Made clone() methods no longer final. Made toString() methods no longer final. Changed all outputter output() signatures to throw JDOMException in case of problem. Changed DOMAdapter signature so getDocument(String filename, ...) is now getDocument(File filename, ...) to match the standard builder model. I did not do a deprecation because no one should be using this internal API directly, and if they are, I want to hear from them. REMOVED METHODS --------------- Removed all methods marked deprecated in beta5. DEPRECATED METHODS ------------------ Marked Namespace.getNamespace(String prefix, Element context) deprecated because it had been replaced by the more elegant elt.getNamespace(String prefix). Marked Document.addContent(Element) deprecated because there can be only one element and it's properly set with setMixedContent(). Marked CDATA.setText() as deprecated. This is because CDATA doesn't have parentage, and without parentage an object should be immutable. ENHANCEMENTS ------------ Added JAXP 1.1 support to SAXBuilder, DOMBuilder, and DOMOutputter. The default parser for all these is now the JAXP parser, with a fallback of Xerces if JAXP isn't available. Added improved Verifier checks of well-formedness throughout all of JDOM. Among the most likely to be noticed: - Added Verifier detection of wrongly places "xmlns" attributes. - Added check in Attribute that a namespace with "" prefix must be NO_NAMESPACE. - Added Verifier checks so CDATA text cannot contain ">>]" Upgraded provided parser to Xerces 1.2. Improved SAXBuilder and DOMBuilder to be *much* smarter about namespaces. Most likely to be noticed: - DOMBuilder now keeps xmlns namespaces declaration location, and it now relies on the parser to handle namespaces (necessary for importing a document that has nodes moved around). Made SAXBuilder and DOMBuilder much more specific on error reporting. Brought DOMOutputter up to DOM Level 2 compliance. - Added logic to DOMOutputter to add xmlns attributes to the DOM tree where appropriate. Added SAXOutputter to generate SAX events. Improved documentation on clone() methods. Changed XMLOutputter.escape*Entities() to protected from private to help subclasses. Improved removeContent() to solve a Crimson performance problem regarding duplicate string entries. Added logic to prevent an element from being added as a child or descendent of itself. Optimized SAXBuilder list handling so retrievals and removes will most likely hit on their first try instead of their last try. Added Namespace output to Element.toString() to help debugging element namespace issues. Improved the Verifier.isXML*() methods to operate much faster. XMLOutputter now prints new lines after the declaration, even if newlines are turned off for the rest of the document. Made PI's getSerializedForm() smarter about spacing between target and data. Now if there is no data, there's no space added. Guarantee XMLOutputter prints a new line at the end of each document, for better formatting, esp when printing to System.out. Put samples in the "samples" package. BUG FIXES --------- Fixed bug in XMLOutputter where "additional namespace" declarations would be output even if they were already declared by an ancestor. Fixed bug where an element not in any namespace will still inherit the default namespace from an ancestor. Added fix to recognize implicit "xml" namespace during Namespace.getNamespace() call. Added fix so XMLOutputter no longer outputs XML_NAMESPACE. Fixed Element.getDocument() behavior to work reliably. Fixed Verifier to not see "xmlnsfoo" attributes as invalid. Fixed Verifier to allow attribute names xml:lang and xml:space as special cases. Improved all adapters to throw exceptions on error instead of printing stack traces. Fixed Element.clone() to be a true deep copy. Fixed bug in SAXBuilder that would throw an EmptyStackException if a PI appeared after the root element. Fixed bug in doc.setMixedContent(List) so it now stores the new data correctly. Made removeChildren() properly set parents to null, and to return true only if children were actually deleted. Changed SAXBuilder's endPrefixMapping(String, String) to be endPrefixMapping(String) as it should have been so we now get the callback and can remove namespaces. Fixed PartialList.addAll() to behave as specified.