net.sourceforge.jsxe.dom
Class XMLDocument

java.lang.Object
  extended bynet.sourceforge.jsxe.dom.XMLDocument
Direct Known Subclasses:
DocumentBuffer

public class XMLDocument
extends Object

The XMLDocument class represents an XML document as a tree structure that has nodes, implemented as AdapterNodes, as well as text. Methods are provided to allow user objects to interact with the XML document as text or as a tree structure seamlessly.

Version:
$Id: XMLDocument.java 903 2006-06-06 19:29:32Z ian_lewis $
Author:
Ian Lewis (IanLewis@member.fsf.org)
See Also:
AdapterNode

Field Summary
static String ENCODING
          The property key for the encoding of this XML document
static String FORMAT_XML
          The property key for the boolean property specifying that the XML text should be formatted to look pleasing to the eye.
static String INDENT
          The property key for the property defining the size of a tab when the document is displayed as text or otherwise.
static String IS_USING_SOFT_TABS
          The property key for the property defining whether to serialize using soft tabs (tabs replaced by the number of spaces specified in the INDENT property).
static String IS_VALIDATING
          The property key for the property defining whether to validate the document with a DTD or Schema
static String LINE_SEPARATOR
          The property key for the property defining what line separator to use when serializing a document.
static String WS_IN_ELEMENT_CONTENT
          The property key for the boolean property specifying if whitespace is allowed in element content.
 
Constructor Summary
XMLDocument(URI uri, InputStream reader)
          Creates a new XMLDocument for a document that can be read by the given Reader.
XMLDocument(URI uri, InputStream reader, EntityResolver resolver)
          Creates a new XMLDocument for a document that can be read by the given Reader.
XMLDocument(URI uri, InputStream reader, EntityResolver resolver, Properties properties)
          Creates a new XMLDocument for a document that can be read by the given Reader.
 
Method Summary
 void addXMLDocumentListener(XMLDocumentListener listener)
          Registers a change listener with the XMLDocument
 boolean checkWellFormedness()
          Checks the wellformedness of the document and throws appropriate exceptions based on the errors encountered during parsing.
 boolean entityDeclared(String entityName)
          Determines if the entity was declared by the DTD/Schema.
protected  void fireStructureChanged(AdapterNode location)
          Called when the structure of the document has changed.
 AdapterNode getAdapterNode()
          Returns the AdapterNode object for the root of the XML document.
 List getAllowedEntities()
          Get the entities defined for this document.
protected  HashMap getCompletionInfoMappings()
          Gets the namespace uri to CompletionInfo Mappings for this document.
 AdapterNode getDocType()
          Returns the document type node for this XMLDocument or null if there is none.
 Document getDocumentCopy()
          Gets a copy of the underlying Document object.
 ElementDecl getElementDecl(String name)
          Gets an element declaration for a qualified name.
 EntityDecl getEntityDecl(String name)
          Gets the entity declaration with the given name
 List getErrors()
          Gets a list of non-fatal errors that were encountered when the document was parsed last.
 int getLength()
          Gets the total number of characters in the document.
 Properties getProperties()
          Gets all properties associated with this document.
 String getProperty(String key)
          Gets a property for the key given.
 String getProperty(String key, String defaultValue)
          Gets a property for the key given or returns the default value if there is no property for the given key.
 AdapterNode getRootElementNode()
          A convenience method that returns the root element node of the document.
 Segment getSegment(int start, int length)
          Gets the text at a specified location in the document.
 String getText(int start, int length)
          Gets the text at a specified location in the document.
 URI getURI()
          Gets the URI for the location of this document.
 void insertText(int offset, String text)
          Inserts text into the document at the specified location
 boolean isValid()
          Returns true if the document is valid i.e.
 boolean isWellFormed()
          Indicates if the document is well formed.
 AdapterNode newAdapterNode(AdapterNode parent, Node node)
          Factory method that creates a new AdapterNode object wrapping the Node object and AdapterNode object wrapping the Node's parent Node object.
 AdapterNode newAdapterNode(AdapterNode parent, String name, String value, short type)
          Creates a new AdapterNode in this document.
 void parseDocument()
          Parses the document with the current options.
 void parseWithoutUpdate()
          Parses the document without updating the DOM.
 void removeText(int offset, int length)
          Removes text at the specifed character offset.
 void removeXMLDocumentListener(XMLDocumentListener listener)
          Unregisters a change listener from this document
 void serialize(OutputStream out)
          Writes the XML document to the output stream specified.
 String serializeNodeToString(AdapterNode node)
          Serializes a child node to a string using the properties specified in this XMLDocument object.
 void setEntityResolver(EntityResolver resolver)
          Sets the EntityResolver object that is used when resolving external entities.
protected  void setModel(InputStream stream)
          Sets up the XMLDocument given a Reader.
 String setProperty(String key, String value)
          Sets a property of the XMLDocument
 void setURI(URI uri)
          Sets the URI for the location of this document.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

ENCODING

public static final String ENCODING
The property key for the encoding of this XML document

See Also:
Constant Field Values

WS_IN_ELEMENT_CONTENT

public static final String WS_IN_ELEMENT_CONTENT
The property key for the boolean property specifying if whitespace is allowed in element content.

See Also:
Constant Field Values

FORMAT_XML

public static final String FORMAT_XML
The property key for the boolean property specifying that the XML text should be formatted to look pleasing to the eye.

See Also:
Constant Field Values

INDENT

public static final String INDENT
The property key for the property defining the size of a tab when the document is displayed as text or otherwise. Used when serializing the document using soft-tabs.

See Also:
Constant Field Values

IS_USING_SOFT_TABS

public static final String IS_USING_SOFT_TABS
The property key for the property defining whether to serialize using soft tabs (tabs replaced by the number of spaces specified in the INDENT property). Has a value of "true" if using soft tabs.

See Also:
Constant Field Values

IS_VALIDATING

public static final String IS_VALIDATING
The property key for the property defining whether to validate the document with a DTD or Schema

See Also:
Constant Field Values

LINE_SEPARATOR

public static final String LINE_SEPARATOR
The property key for the property defining what line separator to use when serializing a document. \n is always used for the internal text but this line separator is used when serializing using the serialize method.

See Also:
Constant Field Values
Constructor Detail

XMLDocument

public XMLDocument(URI uri,
                   InputStream reader)
            throws IOException
Creates a new XMLDocument for a document that can be read by the given Reader.

Parameters:
uri - the uri for the location of this document. Can be null.
reader - the Reader object to read the XML document from.
Throws:
IOException - if there was a problem reading the document

XMLDocument

public XMLDocument(URI uri,
                   InputStream reader,
                   EntityResolver resolver)
            throws IOException
Creates a new XMLDocument for a document that can be read by the given Reader.

Parameters:
reader - the Reader object to read the XML document from.
resolver - the EntityResolver to use when resolving external entities.
Throws:
IOException - if there was a problem reading the document

XMLDocument

public XMLDocument(URI uri,
                   InputStream reader,
                   EntityResolver resolver,
                   Properties properties)
            throws IOException
Creates a new XMLDocument for a document that can be read by the given Reader.

Parameters:
reader - the Reader object to read the XML document from.
resolver - the EntityResolver to use when resolving external entities.
Throws:
IOException - if there was a problem reading the document
Method Detail

checkWellFormedness

public boolean checkWellFormedness()
                            throws SAXParseException,
                                   SAXException,
                                   ParserConfigurationException,
                                   IOException
Checks the wellformedness of the document and throws appropriate exceptions based on the errors encountered during parsing.

Returns:
true if the document is well formed.
Throws:
SAXParseException - if there was a SAX error when parsing.
SAXException - if there was a problem with the SAX parser.
ParserConfigurationException - if the parser is not configured properly
IOException - if there was a problem reading the document

setProperty

public String setProperty(String key,
                          String value)
Sets a property of the XMLDocument

Parameters:
key - the key to the property
value - the value of the property
Returns:
the old value of the property

getDocumentCopy

public Document getDocumentCopy()
Gets a copy of the underlying Document object.

Returns:
a deep copy of the underlying document object

getDocType

public AdapterNode getDocType()
Returns the document type node for this XMLDocument or null if there is none.


getProperties

public Properties getProperties()
Gets all properties associated with this document.

Returns:
the document's properties

getProperty

public String getProperty(String key)
Gets a property for the key given.

Parameters:
key - the key to the properties list
Returns:
the value of the property for the given key.

getProperty

public String getProperty(String key,
                          String defaultValue)
Gets a property for the key given or returns the default value if there is no property for the given key.

Parameters:
key - the key to the properties list
defaultValue - the default value for the property requested
Returns:
the value of the property for the given key.

getRootElementNode

public AdapterNode getRootElementNode()
A convenience method that returns the root element node of the document.

Returns:
the root element node.

getAdapterNode

public AdapterNode getAdapterNode()
Returns the AdapterNode object for the root of the XML document.

Returns:
the root node as an AdapterNode

newAdapterNode

public AdapterNode newAdapterNode(AdapterNode parent,
                                  Node node)
Factory method that creates a new AdapterNode object wrapping the Node object and AdapterNode object wrapping the Node's parent Node object.

Parameters:
parent - the AdapterNode for the parent of the new node. Can be null.
node - the Node object that the new AdapterNode should wrap
Returns:
the new AdapterNode object

newAdapterNode

public AdapterNode newAdapterNode(AdapterNode parent,
                                  String name,
                                  String value,
                                  short type)
Creates a new AdapterNode in this document. This method is namespace aware.

Parameters:
parent - The parent of the node to create. Can be null.
name - the qualified name of the new node
value - the value of the new node to create
type - the type of node to create. Uses the types defined in the Node class.

getText

public String getText(int start,
                      int length)
               throws IOException
Gets the text at a specified location in the document. This method method should be used sparingly as changes to the properties of this document or the tree structure could change the location of text within the document.

Parameters:
start - the starting index of the text to retrieve
length - the length of the text needed
Returns:
the text requested
Throws:
IOException

getSegment

public Segment getSegment(int start,
                          int length)
                   throws IOException
Gets the text at a specified location in the document. This method method should be used sparingly as changes to the properties of this document or the tree structure could change the location of text within the document.

Parameters:
start - the starting index of the text to retrieve
length - the length of the text needed
Returns:
the segment representing the text requested
Throws:
IOException

getLength

public int getLength()
Gets the total number of characters in the document.

Returns:
the length of the document

getErrors

public List getErrors()
Gets a list of non-fatal errors that were encountered when the document was parsed last. These are normally validation errors.

Returns:
a list of Exception objects.
Since:
jsXe 0.4 pre3

isWellFormed

public boolean isWellFormed()
                     throws IOException
Indicates if the document is well formed.

Returns:
true of the document is well formed
Throws:
IOException - if there was a problem checking the wellformedness

isValid

public boolean isValid()
                throws IOException
Returns true if the document is valid i.e. The document structure is well-formed and conforms to a DTD/Schema.

Returns:
true if the IS_VALIDATING property is true and the document is valid. false otherwise.
Throws:
IOException - if there was a problem checking the validity of the document
Since:
jsXe 0.4 pre1

entityDeclared

public boolean entityDeclared(String entityName)
Determines if the entity was declared by the DTD/Schema.

Parameters:
entityName - the name of the entity
Returns:
true if the entity was declared in this document
Since:
jsXe 0.4 pre1

getElementDecl

public ElementDecl getElementDecl(String name)
Gets an element declaration for a qualified name.

Since:
jsXe 0.4 pre1

getEntityDecl

public EntityDecl getEntityDecl(String name)
Gets the entity declaration with the given name


getAllowedEntities

public List getAllowedEntities()
Get the entities defined for this document.

Returns:
a list of EntityDecl objects

serialize

public void serialize(OutputStream out)
               throws IOException,
                      UnsupportedEncodingException
Writes the XML document to the output stream specified.

Parameters:
out - the output stream to write the document to.
Throws:
IOException - if there was a problem writing the document
UnsupportedEncodingException - if the encoding specified in the properties is not supported.

serializeNodeToString

public String serializeNodeToString(AdapterNode node)
Serializes a child node to a string using the properties specified in this XMLDocument object.

Parameters:
node - the node to serialize
Returns:
the serialized version of the node given

setEntityResolver

public void setEntityResolver(EntityResolver resolver)
Sets the EntityResolver object that is used when resolving external entities.

Parameters:
resolver - the entity resolver

setURI

public void setURI(URI uri)
Sets the URI for the location of this document.

Parameters:
uri - the uri specifying the location of this document. Can be null.
Since:
jsXe 0.4 pre4

getURI

public URI getURI()
Gets the URI for the location of this document.

Returns:
the uri specifying the location of this document. Can be null.
Since:
jsXe 0.4 pre4

insertText

public void insertText(int offset,
                       String text)
                throws IOException
Inserts text into the document at the specified location

Parameters:
offset - the character offset where the text should be inserted
text - the text to insert
Throws:
IOException - if the text could not be inserted

removeText

public void removeText(int offset,
                       int length)
                throws IOException
Removes text at the specifed character offset.

Parameters:
offset - the character offset where the text is removed form
length - the length of the text segment to remove
Throws:
IOException - if the text could not be removed

setModel

protected void setModel(InputStream stream)
                 throws IOException
Sets up the XMLDocument given a Reader. The existing content is thrown out and the document read in through the reader is used.

Throws:
IOException

addXMLDocumentListener

public void addXMLDocumentListener(XMLDocumentListener listener)
Registers a change listener with the XMLDocument

Parameters:
listener - the listener to register with this document

removeXMLDocumentListener

public void removeXMLDocumentListener(XMLDocumentListener listener)
Unregisters a change listener from this document

Parameters:
listener - the listener to unregister

fireStructureChanged

protected void fireStructureChanged(AdapterNode location)
Called when the structure of the document has changed. This may be called in the event that specs that will alter how the document is serialized or parsed are changed.

Parameters:
location - the location of the change. null if unknown

getCompletionInfoMappings

protected HashMap getCompletionInfoMappings()
Gets the namespace uri to CompletionInfo Mappings for this document.


parseDocument

public void parseDocument()
                   throws SAXParseException,
                          SAXException,
                          ParserConfigurationException,
                          IOException
Parses the document with the current options. After this is called m_adapterNode and m_parsedMode must be updated.

Throws:
SAXParseException
SAXException
ParserConfigurationException
IOException
Since:
jsXe 0.4 pre1

parseWithoutUpdate

public void parseWithoutUpdate()
Parses the document without updating the DOM. This method does, however, update completion info and parse errors.