Package com.sun.identity.install.tools.util.xml

Class XMLDocument

  • All Implemented Interfaces:
    IXMLUtilsConstants
    public class XMLDocument
extends Object
implements IXMLUtilsConstants
    Represents a simple XML document in memory that may be edited and stored. This implementation relies exlusively on the syntactic correctness of the underlying document such as balancing of quotes and delimiters etc. If an XML document meets these requirements, it can be used to instantiate this class and can then be edited using the public methods available in this class as well as in XMLElement class.

    The in-memroy XML representation does not include any meta information such as DOCTYPE tags, processing instructions, or any commets. Such tags are filtered out before the final in-memory representation of the XML document is constructed. However, when this document is saved, these meta information tags are re-inserted in the appropriate places so as to preserve the original format of the document in all respects possible. Even white spaces are preserved as far as possible.

    This implementation uses an adhoc scanner/parser and does not rely on any third party libraries.

    • Constructor Detail

      • XMLDocument

        public XMLDocument​(File file)
            throws Exception
        Creates an instance of XMLDocument using the specified File object. No checking is done to ensure the availablity and readability of the file passed in as the argument. It is expected that the caller has completed such checks and taken the necessary backups before creating this instance.
        Parameters:
        file - representing the XML document on file system.
        Throws:
        Exception - in case an error occurse during the parsing of this document.

    • Method Detail

      • getRootElement

        public XMLElement getRootElement()
        Returns the root element for the given XML document. This element represents the entire XML document in memory and can be used to traverse and edit various portions of the document.
        Returns:
        the root element of the XML tree

      • newElement

        public XMLElement newElement​(String name)
                      throws Exception
        A factory method used for the creation of new XML elements that can be added to this XML document at a later stage. When this method is called, a new XMLElement object is returned to the caller. However, this newly created element is still not attached to the document anywhere and it is the responsiblity of the caller to attach it in the appropriate location.
        Parameters:
        name - the name of the new element to be created
        Returns:
        the newly created element that can be added to the document
        Throws:
        Exception - in case the creation of the new element fails due to any reason

      • newCollapsedElement

        public XMLElement newCollapsedElement​(String name)
                               throws Exception
        A factory method used for the creation of new XML elements that can be added to this XML document at a later stage. When this method is called, a new XMLElement object is returned to the caller. However, this newly created element is still not attached to the document anywhere and it is the responsiblity of the caller to attach it in the appropriate location. Further, the element returned from this method is a collapsed element that is contained within a single bounded token.
        Parameters:
        name - the name of the new element to be created
        Returns:
        the newly created element that can be added to the document
        Throws:
        Exception - in case the creation of the new element fails due to any reason

      • newElementFromXMLFragment

        public XMLElement newElementFromXMLFragment​(String xmlFragment)
                                     throws Exception
        A factory method used for the creation of new XML elements that can be added to this XML document at a later stage. When this method is called, a new XMLElement object is returned to the caller. However, this newly created element is still not attached to the document anywhere and it is the responsiblity of the caller to attach it in the appropriate location. Note that the supplied parameter xmlFragement must be a valid well-formed xml element.
        Parameters:
        xmlFragment - the xml fragment which will be parsed into an element
        Returns:
        the newly created element that can be added to the document
        Throws:
        Exception - in case the creation of the new element fails due to any reason

      • newElement

        public XMLElement newElement​(String name,
                             String value)
                      throws Exception
        A factory method used for the creation of new XML elements that can be added to this XML document at a later stage. When this method is called, a new XMLElement object is returned to the caller. However, this newly created element is still not attached to the document anywhere and it is the responsiblity of the caller to attach it in the appropriate location.
        Parameters:
        name - the name of the new element to be created
        value - the value of the new element to be created
        Returns:
        the newly created element that can be added to the document
        Throws:
        Exception - in case the creation of the new element fails due to any reason

      • store

        public void store()
           throws Exception
        Stores the in-memory XML data to the file system.
        Throws:
        Exception - If the save operation did not succeed.

      • setIndentDepth

        public void setIndentDepth​(int spaces)
        Sets the number of spaces used for denoting one indent level. The default indent level is set to 4 spaces. However, this can be changed by calling this method anytime. This value comes into effect only when any new element is added to the XML document.
        Parameters:
        spaces - the number of spaces used to denote one level of indentation

      • setNoValueIndent

        public void setNoValueIndent()
        Sets a flag that is used by the document to indent value tokens when adding child elements that have value. The default behavior is to indent value tokens, but that can be changed to no indent by calling this method.

      • setValueIndent

        public void setValueIndent()
        Sets a flag that is used by the document to indent value tokens when adding child elements that have value. The default behavior is to indent value tokens, but changed by calling setNoValueIndent method, it can be reset back to its original state by calling this method.

      • getDoctypeString

        public String getDoctypeString()
        Returns the DOCTYPE string associated with the first DOCTYPE element present in this document. This method may return null if no DOCTYPE token is already present in the document.
        Returns:

      • updatedDoctypeString

        public void updatedDoctypeString​(String newDoctypeString)
                          throws Exception
        This methods provides a means to update the DOCTYPE element of the document with a new value as supplied in the argument. This method will throw an Exception if the given document does not contain a predefined DOCTYPE element.
        Parameters:
        newDoctypeString -
        Throws:
        Exception