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

Class XMLDocument

java.lang.Object

com.sun.identity.install.tools.util.xml.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.

Field Summary

Fields inherited from interface com.sun.identity.install.tools.util.xml.IXMLUtilsConstants

DOCTYPE, NEW_LINE, TOKEN_TYPE_BOUNDED, TOKEN_TYPE_COMMENT, TOKEN_TYPE_DOCTYPE, TOKEN_TYPE_META, TOKEN_TYPE_UNBOUNDED, TOKEN_TYPE_WHITESPACE

Constructor Summary

Constructors

Constructor and Description
XMLDocument(File file) Creates an instance of XMLDocument using the specified File object.

Method Summary

Modifier and Type	Method and Description
String	getDoctypeString() Returns the DOCTYPE string associated with the first DOCTYPE element present in this document.
XMLElement	getRootElement() Returns the root element for the given XML document.
XMLElement	newCollapsedElement(String name) A factory method used for the creation of new XML elements that can be added to this XML document at a later stage.
XMLElement	newElement(String name) A factory method used for the creation of new XML elements that can be added to this XML document at a later stage.
XMLElement	newElement(String name, String value) A factory method used for the creation of new XML elements that can be added to this XML document at a later stage.
XMLElement	newElementFromXMLFragment(String xmlFragment) A factory method used for the creation of new XML elements that can be added to this XML document at a later stage.
void	setIndentDepth(int spaces) Sets the number of spaces used for denoting one indent level.
void	setNoValueIndent() Sets a flag that is used by the document to indent value tokens when adding child elements that have value.
void	setValueIndent() Sets a flag that is used by the document to indent value tokens when adding child elements that have value.
void	store() Stores the in-memory XML data to the file system.
void	updatedDoctypeString(String newDoctypeString) This methods provides a means to update the DOCTYPE element of the document with a new value as supplied in the argument.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

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