com.bea.document.internal
Class Document

java.lang.Object
  com.bea.document.internal.Document

All Implemented Interfaces:

Cloneable, IDocument, Serializable

public class Document

extends Object

implements IDocument, Cloneable

The default implementation of the IDocument interface that uses XML for its serialized form. This class SHOULD be safe for multi-thread access, but has not been rigorously tested in this way.

See Also:

Serialized Form

Constructor Summary

Document()
Construct a blank document.

Document(Document doc)
Construct a new document from the given Xerces DOM Document.

Document(Element documentElement)
Construct a new document from the given DOM Element.

Document(File file)
Create a document by reading XML text previously saved to a file.

Document(File file, String encoding)
Construct a new document using the XML content previously saved to a file.

Document(IDocument doc)
Create a new document which is a deep copy of the given document.

Document(InputSource inputSource)
Construct a new document using the given SAX InputSource.

Document(Reader reader)
Construct a new document from the data available from the given Reader.

Document(String xml)
Construct a new document from the given XML.

Document(String xml, boolean deferParse)
Construct a new document from the given XML.

Method Summary

Attr	addAttribute(String parentPath, String attrName) Add a new attribute to the parent data element referred to by parentPath.
Attr	addAttribute(String parentPath, String attrName, String value) Add a new attribute to the parent data element referred to by parentPath.
void	addDocumentData(String parentPath, DocumentData value) Add the given value to the parent data element referred to by parentPath.
Element	addElement(String parentPath, String elementName) Add a new element to the parent data element referred to by parentPath.
Element	addElement(String parentPath, String elementName, String value) Add a new element to the parent data element referred to by parentPath.
void	addNode(String parentPath, Node node) Add a new node to the parent data element referred to by parentPath.
Object	clone() Clone this document
void	ensureNamespaceDeclaration() Ensure that the XML content has proper namespace declarations, and if not add a default namespace declaration.
static void	ensureNamespaceDeclaration(Reader in, SOMSchema schema, com.bea.document.internal.Document.PrefixInfo prefixInfo, Set globalElementNames, Writer out) Ensure that the given XML text has a namespace declaration attached to the given prefix.
void	ensureNoNamespaceDeclarations() Ensure that the XML content does not contain namespace declarations.
static void	ensureNoNamespaceDeclarations(Reader in, Writer out) Ensure that the XML content does not contain namespace declarations.
void	forceParsed() Force this document into the parsed state by using a DOM parser with the document's internal content.
void	fromXML(ContentHandler contentHandler) Parse the (unparsed) internal content of this document using a SAX parser and the given ContentHandler.
void	fromXML(File file) Retrieves an XML document previously saved to a file.
void	fromXML(File file, String encoding) Retrieves an XML document previously saved to a file.
void	fromXML(InputSource inputSource) Use the given SAX InputSource to import XML into this document (thus replacing any previous data elements in this document).
void	fromXML(Reader reader) Given an XML stream read from reader, import this representation into this document (thus replacing any previous data elements in this document).
void	fromXML(String xmlText) Given an XML string, import this representation into this document (thus replacing any previous data elements in this document).
static String	generateNamespacePrefix(String namespaceURI)
static String	generateNamespacePrefix(String namespaceURI, Map currentPrefixes)
boolean	getBooleanFrom(String nodeName) Return a boolean representing the given xpath.
boolean	getBooleanFromFirst(String nodeName) Return a boolean representing the value of the first element found with the given name.
Calendar	getDateFrom(String nodeName) Return a Calendar representing the value of the given xpath.
Calendar	getDateFromFirst(String nodeName) Return a Calendar representing the value of the first element found with the given name.
Calendar	getDateTimeFrom(String nodeName) Return a Calendar representing the value of the given xpath.
Calendar	getDateTimeFromFirst(String nodeName) Return a Calendar representing the value of the first element found with the given name.
Document	getDocument() Get the internal org.w3c.dom.Document object from this document.
DocumentData	getDocumentData(String path) Return an object which encapsulates the data that corresponds to the given path (XPath syntax).
IDocumentDefinition	getDocumentDefinition() Get the IDocumentDefinition for this document which describes the structure and usage of this type of document.
Element	getDocumentElement() Get the internal document element from this document.
String	getDocumentTypeName() Get the document type name for this document.
double	getDoubleFrom(String nodeName) Return a double representing the value of the given xpath.
double	getDoubleFromFirst(String nodeName) Return a double representing the value of the first element found with the given name.
String	getEncoding() Returns the Java encoding value for this document.
EntityResolver	getEntityResolver() Get the EntityResolver being used when unserializing documents.
String	getFirstNamespacePrefix() Get the first usable namespace prefix from this document.
static Set	getGlobalAttributeNames(SOMSchema schema)
static Set	getGlobalElementNames(SOMSchema schema)
int	getIntegerFrom(String nodeName) Return an int representing the value of the given xpath.
int	getIntegerFromFirst(String nodeName) Return an int representing the value of the first element found with the given name.
String	getPublicID() Get the public ID for this document.
String	getRawXML() Get the raw XML for this document.
String	getRootElementName() Get the root element name for this document definition.
String	getStringFrom(String nodeName) Return a string representing the value of the nodes found with the given xpath.
String	getStringFromFirst(String nodeName) Return a string representing the value of the first element found with the given name.
IDocument[]	getSubDocuments(String path) Get an array of sub-documents representing the nodes that are referred to by the path argument.
String	getSystemID() Get the system ID for this document.
Calendar	getTimeFrom(String nodeName) Return a Calendar representing the value of the given xpath.
Calendar	getTimeFromFirst(String nodeName) Return a Calendar representing the value of the first element found with the given name.
boolean	getValidating() Is this Document validating content in calls to fromXML()?
boolean	isParsed() Is this document's XML parsed? If so, the getDocument() method may be used to retrieve the document's parsed XML as a DOM.
static void	main(String[] args)
void	removeDocumentData(String path) Remove the data element referred to by path.
void	resetContextNode() Resets the context node to the document root element.
static String	serializeDocumentType(DocumentType docType)
static void	serializeDocumentType(Writer writer, DocumentType docType)
static String	serializeElement(Element elem)
static void	serializeElement(Writer writer, Element elem)
static void	serializeElement(Writer writer, int indent, int indentSize, Element elem)
void	setBooleanIn(String nodeName, boolean newValue) Set the node value of all data nodes found for the given xpath to the string representation of the given newValue.
void	setBooleanInFirst(String nodeName, boolean newValue) Set the first element that matches the given XPath to the value given by newValue.
void	setContextNode(DocumentData data) Sets the context node for use in all queries to data.
void	setContextNode(Node node) Sets the context node for use in all queries to node.
void	setContextNode(String path) Sets the context node for use in all queries to path.
void	setDateIn(String nodeName, Calendar newValue) Set the node value of all data nodes found for the given xpath to the string representation of the given newValue.
void	setDateInFirst(String nodeName, Calendar newValue) Set the first element that matches the given XPath to the value given by newValue.
void	setDateTimeIn(String nodeName, Calendar newValue) Set the node value of all data nodes found for the given xpath to the string representation of the given newValue.
void	setDateTimeInFirst(String nodeName, Calendar newValue) Set the first element that matches the given XPath to the value given by newValue.
void	setDocumentData(String path, DocumentData value) Set the data element referred to by path to be value.
void	setDocumentDefinition(IDocumentDefinition docDef) Set the IDocumentDefinition for this document.
void	setDocumentElement(Element documentElement) Set the root document element of this document to the given DOM Element.
void	setDocumentTypeName(String typeName) Set the document type name for this document.
void	setDoubleIn(String nodeName, double newValue) Set the node value of all data nodes found for the given xpath to the string representation of the given newValue.
void	setDoubleInFirst(String nodeName, double newValue) Set the first element that matches the given XPath to the value given by newValue.
void	setEncoding(String encoding)
void	setEntityResolver(EntityResolver entityResolver) Set the EntityResolver to use when unserializing.
void	setIntegerIn(String nodeName, int newValue) Set the node value of all data nodes found for the given xpath to the string representation of the given newValue.
void	setIntegerInFirst(String nodeName, int newValue) Set the first element that matches the given XPath to the value given by newValue.
static void	setPerThreadEntityResolver(EntityResolver entityResolver) Convenience method to set the EntityResolver to use when unserializing.
void	setPublicID(String id) Set the public ID for this document.
void	setStringIn(String nodeName, String newValue) Set the node value of all data nodes found for the given xpath to the string representation of the given newValue.
void	setStringInFirst(String nodeName, String newValue) Set the first element that matches the given XPath to the value given by newValue.
void	setSystemID(String id) Set the system ID for this document.
void	setTimeIn(String nodeName, Calendar newValue) Set the node value of all data nodes found for the given xpath to the string representation of the given newValue.
void	setTimeInFirst(String nodeName, Calendar newValue) Set the first element that matches the given XPath to the value given by newValue.
void	setValidating(boolean validating) Set this Document to validate/not-validate during calls to fromXML.
byte[]	toByteXML()
String	toXML() Get the XML represented by this document as a String.
void	toXML(Writer writer) Get the XML represented by this document, and write it to the given Writer.
void	toXML(Writer writer, int indentSize, String encoding) Get the XML represented by this document, and write it to the given Writer using the given indentSize and character encoding.

Methods inherited from class java.lang.Object

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

Constructor Detail

Document

public Document()

Construct a blank document.

Document

public Document(String xml)
         throws DocumentParseException,
                DocumentException

Construct a new document from the given XML.

Document

public Document(String xml,
                boolean deferParse)
         throws DocumentParseException,
                DocumentException

Construct a new document from the given XML.

Document

public Document(File file)
         throws DocumentParseException,
                DocumentException

Create a document by reading XML text previously saved to a file. The data within this file will be interpreted according to the default XML encodings UTF-8 or UTF-16, or according to the encoding value specified in the XML declaration embedded in the XML text. The detection of the desired encoding is left up to the XML parser. It will auto-detect the encoding and proceed if it finds a supported encoding is in use. In general, if this method is used to populate an IDocument instance, the method getEncoding() on this instance will return null, as it is impossible for the instance to determine the actual encoding in use. This knowledge is restricted to the XML parser itself, and there is no standard mechanism for retrieving the encoding from the XML parser. If the encoding for the data in this file is know, it is recommended that you specify the encoding by using the fromXML(File, String) method instead.

Parameters:

file -

Throws:

DocumentParseException

DocumentException

See Also:

fromXML(File, String)

Document

public Document(File file,
                String encoding)
         throws DocumentParseException,
                DocumentException

Construct a new document using the XML content previously saved to a file. The data within this file will be interpreted according to the given encoding value.

Parameters:

file -

encoding - The Java encoding style for the content in the given file.

Throws:

DocumentParseException

DocumentException

Document

public Document(Reader reader)
         throws DocumentParseException,
                DocumentException

Construct a new document from the data available from the given Reader. This behaves similarly to the constructor taking an XML string. This method will NOT close the reader, this is left to the caller.

Document

public Document(Element documentElement)

Construct a new document from the given DOM Element. This element is 'cloned' so it may exist in a new document (this document).

Document

public Document(Document doc)

Construct a new document from the given Xerces DOM Document. This document is used 'as is' and the new Document object assumes ownership of the DOM document.

Document

public Document(InputSource inputSource)
         throws DocumentParseException,
                DocumentException

Construct a new document using the given SAX InputSource.

Document

public Document(IDocument doc)

Create a new document which is a deep copy of the given document.

Method Detail

clone

public Object clone()
             throws CloneNotSupportedException

Clone this document

Specified by:

clone in interface IDocument

Throws:

CloneNotSupportedException

addAttribute

public Attr addAttribute(String parentPath,
                         String attrName)
                  throws DocumentException

Description copied from interface: IDocument

Add a new attribute to the parent data element referred to by parentPath. The new attribute is given the name indicated by attrName and has a value of empty string.
Note that to add data to a new (empty) document, you should use a value of "" (empty string) or "/" for parentPath. Note also that a document only allows a single child of type element.

Specified by:

addAttribute in interface IDocument

Returns:

The DOM attribute created by this method.

Throws:

DocumentException

addAttribute

public Attr addAttribute(String parentPath,
                         String attrName,
                         String value)
                  throws DocumentException

Description copied from interface: IDocument

Add a new attribute to the parent data element referred to by parentPath. The new attribute is given the name indicated by attrName and has a value of value.
Note that to add data to a new (empty) document, you should use a value of "" (empty string) or "/" for parentPath. Note also that a document only allows a single child of type element.

Specified by:

addAttribute in interface IDocument

Returns:

The DOM attribute created by this method.

Throws:

DocumentException

addElement

public Element addElement(String parentPath,
                          String elementName)
                   throws DocumentException

Description copied from interface: IDocument

Add a new element to the parent data element referred to by parentPath. The new element is given the name indicated by elementName, and has no children (text or otherwise).
Note that to add data to a new (empty) document, you should use a value of "" (empty string) or "/" for parentPath. Note also that a document only allows a single child of type element.

Specified by:

addElement in interface IDocument

Returns:

The DOM element created by this method.

Throws:

DocumentException

addElement

public Element addElement(String parentPath,
                          String elementName,
                          String value)
                   throws DocumentException

Description copied from interface: IDocument

Add a new element to the parent data element referred to by parentPath. The new element is given the name indicated by elementName, and has a single text node child with the value given by value.
Note that to add data to a new (empty) document, you should use a value of "" (empty string) or "/" for parentPath. Note also that a document only allows a single child of type element.

Specified by:

addElement in interface IDocument

Returns:

The DOM element created by this method.

Throws:

DocumentException

addNode

public void addNode(String parentPath,
                    Node node)
             throws DocumentException

Description copied from interface: IDocument

Add a new node to the parent data element referred to by parentPath. The new node is first 'cloned', then added to the parent data element.
Note that to add data to a new (empty) document, you should use a value of "" (empty string) or "/" for parentPath. Note also that a document only allows a single child of type element.

Specified by:

addNode in interface IDocument

Throws:

DocumentException

addDocumentData

public void addDocumentData(String parentPath,
                            DocumentData value)
                     throws DocumentException

Description copied from interface: IDocument

Add the given value to the parent data element referred to by parentPath. The data element referred to by parentPath must be of type NODESET. If the value is of any other type than NODESET, a Text node is added having the value object's string value. If the value is of type NODESET, all data elements in the node set are appended to the parent's list of children.
Note that to add data to a new (empty) document, you should use a value of "" (empty string) or "/" for parentPath. Note also that a document only allows a single child of type element.

Specified by:

addDocumentData in interface IDocument

Throws:

DocumentException

ensureNamespaceDeclaration

public void ensureNamespaceDeclaration()
                                throws DocumentParseException,
                                       DocumentException

Ensure that the XML content has proper namespace declarations, and if not add a default namespace declaration. The 'proper' namespace is the one defined in the schema for this document (if any). If no document definition has been attached to this document, this method is a no-op.

Specified by:

ensureNamespaceDeclaration in interface IDocument

Throws:

DocumentParseException - if this method is forced to parse raw XML and the parse fails.

DocumentException - if any other error occurs setting the namespace.

getGlobalElementNames

public static Set getGlobalElementNames(SOMSchema schema)

getGlobalAttributeNames

public static Set getGlobalAttributeNames(SOMSchema schema)

generateNamespacePrefix

public static String generateNamespacePrefix(String namespaceURI)

generateNamespacePrefix

public static String generateNamespacePrefix(String namespaceURI,
                                             Map currentPrefixes)

ensureNamespaceDeclaration

public static void ensureNamespaceDeclaration(Reader in,
                                              SOMSchema schema,
                                              com.bea.document.internal.Document.PrefixInfo prefixInfo,
                                              Set globalElementNames,
                                              Writer out)
                                       throws DocumentException

Ensure that the given XML text has a namespace declaration attached to the given prefix. This is done using an efficient (yet complete) SAX parse of the document.

Parameters:

in - The Reader instance that will read the XML text to check.

schema - The SOMSchema that controls the content for this document.

prefixInfo - Prefix to mapping info (can be blank via no-arg ctor).

globalElementNames - A set of names to be treated as global element names (prefixed at all times).

out - The Writer instance that will write the modified XML text.

Throws:

DocumentParseException - if this method is forced to parse raw XML and the parse fails.

DocumentException - if any other error occurs adding the namespace.

ensureNoNamespaceDeclarations

public void ensureNoNamespaceDeclarations()
                                   throws DocumentParseException,
                                          DocumentException

Ensure that the XML content does not contain namespace declarations. If it does, this method will strip any such declarations and any namespace prefixes that refer to them.

Specified by:

ensureNoNamespaceDeclarations in interface IDocument

Throws:

DocumentParseException - if this method is forced to parse raw XML and the parse fails.

DocumentException - if any other error occurs removing the namespace.

ensureNoNamespaceDeclarations

public static void ensureNoNamespaceDeclarations(Reader in,
                                                 Writer out)
                                          throws DocumentParseException,
                                                 DocumentException

Ensure that the XML content does not contain namespace declarations. If it does, this method will strip any such declarations and any namespace prefixes that refer to them.

Throws:

DocumentParseException - if this method is forced to parse raw XML and the parse fails.

DocumentException - if any other error occurs removing the namespace.

getFirstNamespacePrefix

public String getFirstNamespacePrefix()
                               throws DocumentParseException,
                                      DocumentException

Get the first usable namespace prefix from this document. This is useful when trying to construct XPath expressions to fetch its contents.

Specified by:

getFirstNamespacePrefix in interface IDocument

Returns:

The first namespace prefix defined on this doc, or null if none

Throws:

DocumentParseException - if we're forced to parse the doc, and fail.

DocumentException - if any other exception occurs getting the prefix.

forceParsed

public void forceParsed()
                 throws DocumentParseException,
                        DocumentException

Force this document into the parsed state by using a DOM parser with the document's internal content. This method is only valid when the isParsed() method returns false. Otherwise, this method is a no-op.

Specified by:

forceParsed in interface IDocument

Throws:

DocumentParseException

DocumentException

fromXML

public void fromXML(String xmlText)
             throws DocumentParseException,
                    DocumentException

Given an XML string, import this representation into this document (thus replacing any previous data elements in this document).

Specified by:

fromXML in interface IDocument

Throws:

DocumentParseException

DocumentException

fromXML

public void fromXML(File file)
             throws DocumentParseException,
                    DocumentException

Retrieves an XML document previously saved to a file. The data within this file will be interpreted according to the default XML encodings UTF-8 or UTF-16, or according to the encoding value specified in the XML declaration embedded in the XML text. The detection of the desired encoding is left up to the XML parser. It will auto-detect the encoding and proceed if it finds a supported encoding is in use. In general, if this method is used to populate an IDocument instance, the method getEncoding() on this instance will return null, as it is impossible for the instance to determine the actual encoding in use. This knowledge is restricted to the XML parser itself, and there is no standard mechanism for retrieving the encoding from the XML parser. If the encoding for the data in this file is know, it is recommended that you specify the encoding by using the fromXML(File, String) method instead.

Specified by:

fromXML in interface IDocument

Parameters:

file -

Throws:

DocumentParseException

DocumentException

See Also:

fromXML(File, String)

fromXML

public void fromXML(File file,
                    String encoding)
             throws DocumentParseException,
                    DocumentException

Retrieves an XML document previously saved to a file. The data within this file will be interpreted according to the given encoding value.

Specified by:

fromXML in interface IDocument

Parameters:

file -

encoding - The Java encoding style for the content in the given file.

Throws:

DocumentParseException

DocumentException

fromXML

public void fromXML(Reader reader)
             throws DocumentParseException,
                    DocumentException

Given an XML stream read from reader, import this representation into this document (thus replacing any previous data elements in this document). This method will NOT close the reader, this is left to the caller.

Specified by:

fromXML in interface IDocument

Throws:

DocumentParseException

DocumentException

fromXML

public void fromXML(InputSource inputSource)
             throws DocumentParseException,
                    DocumentException

Use the given SAX InputSource to import XML into this document (thus replacing any previous data elements in this document).

Specified by:

fromXML in interface IDocument

Throws:

DocumentParseException

DocumentException

fromXML

public void fromXML(ContentHandler contentHandler)
             throws DocumentParseException,
                    DocumentException

Parse the (unparsed) internal content of this document using a SAX parser and the given ContentHandler.

Specified by:

fromXML in interface IDocument

Throws:

DocumentParseException

DocumentException

getDocument

public Document getDocument()

Get the internal org.w3c.dom.Document object from this document. Note that users should have called isParsed() and got true before calling this method. Just in case the users are depending on old (pre-deferred-parse) behavior, we'll force the parse for them.

Specified by:

getDocument in interface IDocument

getDocumentData

public DocumentData getDocumentData(String path)
                             throws DocumentException

Description copied from interface: IDocument

Return an object which encapsulates the data that corresponds to the given path (XPath syntax). This object is NEVER null and has a type of either: MESSAGE_DATA_TYPE_XXX where XXX is:

BOOLEAN - call bool DocumentData.toBool()
NODESET - call org.w3c.NodeList DocumentData.toNodeSet()
NULL - null result
NUMBER - call double DocumentData.toNumber()
RTREEFRAG - call org.w3c.dom.DocumentFragment DocumentData.toRtree()
STRING - call String DocumentData.toStr()
UNKNOWN - unknown result

Specified by:

getDocumentData in interface IDocument

Throws:

DocumentException

getDocumentDefinition

public IDocumentDefinition getDocumentDefinition()

Description copied from interface: IDocument

Get the IDocumentDefinition for this document which describes the structure and usage of this type of document.

Specified by:

getDocumentDefinition in interface IDocument

getDocumentElement

public Element getDocumentElement()

Get the internal document element from this document.

Specified by:

getDocumentElement in interface IDocument

getDocumentTypeName

public String getDocumentTypeName()

Get the document type name for this document. The document type name refers to a named IDocumentDefinition. This class does not define how you would retrieve or store IDocumentDefinitions.

Specified by:

getDocumentTypeName in interface IDocument

getEncoding

public String getEncoding()

Returns the Java encoding value for this document. The encoding type (if found) is converted to Java encoding from Mime encoding if a translation is necessary. For example, if the document contains an encoding value of "UTF-8" this method would return "UTF8". If no encoding is specified for this document, this method returns null.

Specified by:

getEncoding in interface IDocument

setEncoding

public void setEncoding(String encoding)

getEntityResolver

public EntityResolver getEntityResolver()

Get the EntityResolver being used when unserializing documents. By default, this class uses a ClasspathEntityResolver with no registered PublicIds. If you wish to modify the behavior of the entity resolver invoke methods on the returned EntityResolver object.

Specified by:

getEntityResolver in interface IDocument

getRawXML

public String getRawXML()

Get the raw XML for this document. This method is not the same as toXML(), as it only returns the raw XML if the isParsed() method returns false. The toXML() method, by contrast, generates a new XML representation from the contents of the document.

Specified by:

getRawXML in interface IDocument

getPublicID

public String getPublicID()

Get the public ID for this document.

Specified by:

getPublicID in interface IDocument

getRootElementName

public String getRootElementName()

Get the root element name for this document definition.

Specified by:

getRootElementName in interface IDocument

getStringFromFirst

public String getStringFromFirst(String nodeName)
                          throws DocumentException

Return a string representing the value of the first element found with the given name. If nodeName does not start with a '/', the characters '//' are prepended to nodeName. If nodeName does not end with ']', the characters '[1]' are appended to nodeName. This method never returns null, even if no data is found corresponding to the XPath in nodeName. In this case, an empty String is returned.
If it is necessary to determine if the data was found in the document, use the getDocumentData method instead.

Specified by:

getStringFromFirst in interface IDocument

Throws:

DocumentException

See Also:

getDocumentData(String)

getIntegerFromFirst

public int getIntegerFromFirst(String nodeName)
                        throws DocumentException

Return an int representing the value of the first element found with the given name. This method is a convenience method that simply calls getStringFromFirst, and interprets the result as an Integer. If the resultant string value is not a valid integer value (including empty string), a DocumentException will result.

Specified by:

getIntegerFromFirst in interface IDocument

Throws:

DocumentException

See Also:

getStringFromFirst(String), getDocumentData(String)

getBooleanFromFirst

public boolean getBooleanFromFirst(String nodeName)
                            throws DocumentException

Return a boolean representing the value of the first element found with the given name. This method is a convenience method that simply calls getStringFromFirst, and interprets the result as a Boolean. If the resultant string value is 'true' or 'yes' (ignoring case), then true is returned. Otherwise, false is returned.
If it is necessary to determine if the data was found in the document, use the getDocumentData method instead.

Specified by:

getBooleanFromFirst in interface IDocument

Throws:

DocumentException

See Also:

getStringFromFirst(String), getDocumentData(String)

getDoubleFromFirst

public double getDoubleFromFirst(String nodeName)
                          throws DocumentException

Return a double representing the value of the first element found with the given name. This method is a convenience method that simply calls getStringFromFirst, and interprets the result as a Double. If the resultant string value is not a valid double value (including empty string), a DocumentException will result.

Specified by:

getDoubleFromFirst in interface IDocument

Throws:

DocumentException

See Also:

getStringFromFirst(String), getDocumentData(String)

getDateFromFirst

public Calendar getDateFromFirst(String nodeName)
                          throws DocumentException

Return a Calendar representing the value of the first element found with the given name. This method is a convenience method that simply calls getStringFromFirst, and interprets the result as a date (i.e. an element with XML schema datatype 'date'). If the resultant string value is not a valid date value (including empty string), a DocumentException will result.

Specified by:

getDateFromFirst in interface IDocument

Returns:

a java.util.Calendar; a Calendar is provided because it provides better control over date functionality than a java.util.Date object.

Throws:

DocumentException

See Also:

getStringFromFirst(String), getDocumentData(String)

getDateTimeFromFirst

public Calendar getDateTimeFromFirst(String nodeName)
                              throws DocumentException

Return a Calendar representing the value of the first element found with the given name. This method is a convenience method that simply calls getStringFromFirst, and interprets the result as a dateTime (i.e. an element with XML schema datatype 'dateTime'). If the resultant string value is not a valid dateTime value (including empty string), a DocumentException will result.

Specified by:

getDateTimeFromFirst in interface IDocument

Returns:

a java.util.Calendar; a Calendar is provided because it provides better control over date functionality than a java.util.Date object.

Throws:

DocumentException

See Also:

getStringFromFirst(String), getDocumentData(String)

getTimeFromFirst

public Calendar getTimeFromFirst(String nodeName)
                          throws DocumentException

Return a Calendar representing the value of the first element found with the given name. This method is a convenience method that simply calls getStringFromFirst, and interprets the result as a time (i.e. an element with XML schema datatype 'time'). If the resultant string value is not a valid time value (including empty string), a DocumentException will result.

Specified by:

getTimeFromFirst in interface IDocument

Returns:

a java.util.Calendar; a Calendar is provided because it provides better control over date functionality than a java.util.Date object. If the node does not exist, then null is returned.

Throws:

DocumentException

See Also:

getStringFromFirst(String), getDocumentData(String)

getDateFrom

public Calendar getDateFrom(String nodeName)
                     throws DocumentException

Return a Calendar representing the value of the given xpath. This method is a convenience method that simply calls getStringFrom, and interprets the result as a date (i.e. an element with XML schema datatype 'date'). If the resultant string value is not a valid date value (including empty string), a DocumentException will result.

Specified by:

getDateFrom in interface IDocument

Returns:

a java.util.Calendar; a Calendar is provided because it provides better control over date functionality than a java.util.Date object.

Throws:

DocumentException

See Also:

getStringFromFirst(String), getDocumentData(String)

getDateTimeFrom

public Calendar getDateTimeFrom(String nodeName)
                         throws DocumentException

Return a Calendar representing the value of the given xpath. This method is a convenience method that simply calls getStringFrom, and interprets the result as a dateTime (i.e. an element with XML schema datatype 'dateTime'). If the resultant string value is not a valid dateTime value (including empty string), a DocumentException will result.

Specified by:

getDateTimeFrom in interface IDocument

Returns:

a java.util.Calendar; a Calendar is provided because it provides better control over date functionality than a java.util.Date object.

Throws:

DocumentException

See Also:

getStringFromFirst(String), getDocumentData(String)

getTimeFrom

public Calendar getTimeFrom(String nodeName)
                     throws DocumentException

Return a Calendar representing the value of the given xpath. This method is a convenience method that simply calls getStringFrom, and interprets the result as a time (i.e. an element with XML schema datatype 'time'). If the resultant string value is not a valid time value (including empty string), a DocumentException will result.

Specified by:

getTimeFrom in interface IDocument

Returns:

a java.util.Calendar; a Calendar is provided because it provides better control over date functionality than a java.util.Date object. If the node does not exist, then null is returned.

Throws:

DocumentException

See Also:

getStringFromFirst(String), getDocumentData(String)

getStringFrom

public String getStringFrom(String nodeName)
                     throws DocumentException

Return a string representing the value of the nodes found with the given xpath. This method never returns null, even if no data is found corresponding to the XPath in nodeName. In this case, an empty String is returned.
If it is necessary to determine if the data was found in the document, use the getDocumentData method instead.

Specified by:

getStringFrom in interface IDocument

Throws:

DocumentException

See Also:

getDocumentData(String)

getIntegerFrom

public int getIntegerFrom(String nodeName)
                   throws DocumentException

Return an int representing the value of the given xpath. This method is a convenience method that simply calls getStringFrom, and interprets the result as an Integer. If the resultant string value is not a valid integer value (including empty string), a DocumentException will result.

Specified by:

getIntegerFrom in interface IDocument

Throws:

DocumentException

See Also:

getStringFrom(String), getDocumentData(String)

getBooleanFrom

public boolean getBooleanFrom(String nodeName)
                       throws DocumentException

Return a boolean representing the given xpath. This method is a convenience method that simply calls getStringFrom, and interprets the result as a Boolean. If the resultant string value is 'true' or 'yes' (ignoring case), then true is returned. Otherwise, false is returned.
If it is necessary to determine if the data was found in the document, use the getDocumentData method instead.

Specified by:

getBooleanFrom in interface IDocument

Throws:

DocumentException

See Also:

getStringFrom(String), getDocumentData(String)

getDoubleFrom

public double getDoubleFrom(String nodeName)
                     throws DocumentException

Return a double representing the value of the given xpath. This method is a convenience method that simply calls getStringFrom, and interprets the result as a Double. If the resultant string value is not a valid double value (including empty string), a DocumentException will result.

Specified by:

getDoubleFrom in interface IDocument

Throws:

DocumentException

See Also:

getStringFrom(String), getDocumentData(String)

getSubDocuments

public IDocument[] getSubDocuments(String path)
                            throws DocumentException

Get an array of sub-documents representing the nodes that are referred to by the path argument.

Specified by:

getSubDocuments in interface IDocument

Throws:

DocumentException

getSystemID

public String getSystemID()

Get the system ID for this document.

Specified by:

getSystemID in interface IDocument

getValidating

public boolean getValidating()

Is this Document validating content in calls to fromXML()?

Specified by:

getValidating in interface IDocument

isParsed

public boolean isParsed()

Is this document's XML parsed? If so, the getDocument() method may be used to retrieve the document's parsed XML as a DOM. If not, the getRawXML() method may be used to retrieve the unparsed XML.

Specified by:

isParsed in interface IDocument

removeDocumentData

public void removeDocumentData(String path)
                        throws DocumentException

Description copied from interface: IDocument

Remove the data element referred to by path. The data element referred to by path must be of type NODESET.

Specified by:

removeDocumentData in interface IDocument

Throws:

DocumentException

resetContextNode

public void resetContextNode()

Description copied from interface: IDocument

Resets the context node to the document root element. All calls to getDocumentData (direct or indirect) will be relative to the document root element.

Specified by:

resetContextNode in interface IDocument

See Also:

setContextNode(Node)

serializeDocumentType

public static String serializeDocumentType(DocumentType docType)
                                    throws DocumentException

Throws:

DocumentException

serializeDocumentType

public static void serializeDocumentType(Writer writer,
                                         DocumentType docType)
                                  throws IOException

Throws:

IOException

serializeElement

public static String serializeElement(Element elem)
                               throws DocumentException

Throws:

DocumentException

serializeElement

public static void serializeElement(Writer writer,
                                    Element elem)
                             throws IOException,
                                    DocumentException

Throws:

IOException

DocumentException

serializeElement

public static void serializeElement(Writer writer,
                                    int indent,
                                    int indentSize,
                                    Element elem)
                             throws IOException,
                                    DocumentException

Throws:

IOException

DocumentException

setContextNode

public void setContextNode(String path)
                    throws DocumentException

Description copied from interface: IDocument

Sets the context node for use in all queries to path. This path must refer to a node set. If the path refers to a node set of more than one node, the context node is set to the first node in the node set.
From this point on, until resetContextNode() is called, all calls to getDocumentData (direct or indirect) will be relative to the new context node. This can be very useful if adding large numbers of elements to the same parent, or if adding elements to a very deeply nested parent, or adding elements to a parent in a very large document.

Specified by:

setContextNode in interface IDocument

Throws:

DocumentException

setContextNode

public void setContextNode(DocumentData data)
                    throws DocumentException

Description copied from interface: IDocument

Sets the context node for use in all queries to data. This data must be a node set. If the node set contains more than one node, the context node is set to the first node in the node set.
From this point on, until resetContextNode() is called, all calls to getDocumentData (direct or indirect) will be relative to the new context node. This can be very useful if adding large numbers of elements to the same parent, or if adding elements to a very deeply nested parent, or adding elements to a parent in a very large document.

Specified by:

setContextNode in interface IDocument

Throws:

DocumentException

See Also:

setContextNode(String)

setContextNode

public void setContextNode(Node node)

Description copied from interface: IDocument

Sets the context node for use in all queries to node. From this point on, until resetContextNode() is called, all calls to getDocumentData (direct or indirect) will be relative to the new context node. This can be very useful if adding large numbers of elements to the same parent, or if adding elements to a very deeply nested parent, or adding elements to a parent in a very large document.

Specified by:

setContextNode in interface IDocument

See Also:

setContextNode(DocumentData)

setDocumentData

public void setDocumentData(String path,
                            DocumentData value)
                     throws DocumentException

Description copied from interface: IDocument

Set the data element referred to by path to be value. The type of the data element referred to by path must be compatible with the type of the data element specified by value. Valid combinations (target vs. source) are given below:

Target Type Source Type Notes

NODESET NODESET Number of nodes must match
NODESET STRING Target replaced by Text with value's string val
NODESET BOOLEAN Target replaced by Text with value's string val
NODESET NUMBER Target replaced by Text with value's string val

Specified by:

setDocumentData in interface IDocument

Throws:

DocumentException

setDocumentDefinition

public void setDocumentDefinition(IDocumentDefinition docDef)

Description copied from interface: IDocument

Set the IDocumentDefinition for this document.

Specified by:

setDocumentDefinition in interface IDocument

setDocumentElement

public void setDocumentElement(Element documentElement)

Set the root document element of this document to the given DOM Element. This element is cloned so it may exist in a new document (this document).

Specified by:

setDocumentElement in interface IDocument

setDocumentTypeName

public void setDocumentTypeName(String typeName)

Set the document type name for this document. The document type refers to a named IDocumentDefinition. This class does not define how you would retrieve or store IDocumentDefinitions.

Specified by:

setDocumentTypeName in interface IDocument

setEntityResolver

public void setEntityResolver(EntityResolver entityResolver)

Set the EntityResolver to use when unserializing. By default, this class uses an instance of ClasspathEntityResolver with no registered PublicIds.

Specified by:

setEntityResolver in interface IDocument

setPerThreadEntityResolver

public static void setPerThreadEntityResolver(EntityResolver entityResolver)

Convenience method to set the EntityResolver to use when unserializing. This method just calls the DocumentProcessors.setPerThreadEntityResolver. This sets the entity resolver that will be used for all objects in the current thread, and does not set a per-object entity resolver. By default, PerThreadDocumentProcessors uses an instance of ClasspathEntityResolver with no registered PublicIds.

setPublicID

public void setPublicID(String id)

Set the public ID for this document.

Specified by:

setPublicID in interface IDocument

setStringInFirst

public void setStringInFirst(String nodeName,
                             String newValue)
                      throws DocumentException

Set the first element that matches the given XPath to the value given by newValue.

Specified by:

setStringInFirst in interface IDocument

Throws:

DocumentException

setIntegerInFirst

public void setIntegerInFirst(String nodeName,
                              int newValue)
                       throws DocumentException

Set the first element that matches the given XPath to the value given by newValue.

Specified by:

setIntegerInFirst in interface IDocument

Throws:

DocumentException

setBooleanInFirst

public void setBooleanInFirst(String nodeName,
                              boolean newValue)
                       throws DocumentException

Set the first element that matches the given XPath to the value given by newValue.

Specified by:

setBooleanInFirst in interface IDocument

Throws:

DocumentException

setDoubleInFirst

public void setDoubleInFirst(String nodeName,
                             double newValue)
                      throws DocumentException

Set the first element that matches the given XPath to the value given by newValue.

Specified by:

setDoubleInFirst in interface IDocument

Throws:

DocumentException

setDateInFirst

public void setDateInFirst(String nodeName,
                           Calendar newValue)
                    throws DocumentException

Set the first element that matches the given XPath to the value given by newValue.

Specified by:

setDateInFirst in interface IDocument

Throws:

DocumentException

setDateTimeInFirst

public void setDateTimeInFirst(String nodeName,
                               Calendar newValue)
                        throws DocumentException

Set the first element that matches the given XPath to the value given by newValue.

Specified by:

setDateTimeInFirst in interface IDocument

Throws:

DocumentException

setTimeInFirst

public void setTimeInFirst(String nodeName,
                           Calendar newValue)
                    throws DocumentException

Set the first element that matches the given XPath to the value given by newValue.

Specified by:

setTimeInFirst in interface IDocument

Throws:

DocumentException

setStringIn

public void setStringIn(String nodeName,
                        String newValue)
                 throws DocumentException

Set the node value of all data nodes found for the given xpath to the string representation of the given newValue.

Specified by:

setStringIn in interface IDocument

Throws:

DocumentException

setIntegerIn

public void setIntegerIn(String nodeName,
                         int newValue)
                  throws DocumentException

Set the node value of all data nodes found for the given xpath to the string representation of the given newValue.

Specified by:

setIntegerIn in interface IDocument

Throws:

DocumentException

setBooleanIn

public void setBooleanIn(String nodeName,
                         boolean newValue)
                  throws DocumentException

Set the node value of all data nodes found for the given xpath to the string representation of the given newValue.

Specified by:

setBooleanIn in interface IDocument

Throws:

DocumentException

setDoubleIn

public void setDoubleIn(String nodeName,
                        double newValue)
                 throws DocumentException

Set the node value of all data nodes found for the given xpath to the string representation of the given newValue.

Specified by:

setDoubleIn in interface IDocument

Throws:

DocumentException

setDateIn

public void setDateIn(String nodeName,
                      Calendar newValue)
               throws DocumentException

Set the node value of all data nodes found for the given xpath to the string representation of the given newValue.

Specified by:

setDateIn in interface IDocument

Throws:

DocumentException

setDateTimeIn

public void setDateTimeIn(String nodeName,
                          Calendar newValue)
                   throws DocumentException

Set the node value of all data nodes found for the given xpath to the string representation of the given newValue.

Specified by:

setDateTimeIn in interface IDocument

Throws:

DocumentException

setTimeIn

public void setTimeIn(String nodeName,
                      Calendar newValue)
               throws DocumentException

Set the node value of all data nodes found for the given xpath to the string representation of the given newValue.

Specified by:

setTimeIn in interface IDocument

Throws:

DocumentException

setSystemID

public void setSystemID(String id)

Set the system ID for this document.

Specified by:

setSystemID in interface IDocument

setValidating

public void setValidating(boolean validating)

Set this Document to validate/not-validate during calls to fromXML.

Specified by:

setValidating in interface IDocument

toXML

public String toXML()
             throws DocumentException

Get the XML represented by this document as a String. No encoding will be indicated in the resultant XML string. If the user wishes to output the XML text in a given encoding, they should use the toXML(Writer) or toXML(Writer, int, String) method instead.

Specified by:

toXML in interface IDocument

Throws:

DocumentException

See Also:

toXML(java.io.Writer), toXML(java.io.Writer, int, String)

toByteXML

public byte[] toByteXML()
                 throws DocumentException

Throws:

DocumentException

toXML

public void toXML(Writer writer)
           throws IOException,
                  DocumentException

Get the XML represented by this document, and write it to the given Writer. This method will use the default indent size and UTF8 Java encoding value. The caller should be careful that the specified Writer actually writes characters as bytes encoded using the UTF8 Java encoding.

Specified by:

toXML in interface IDocument

Throws:

IOException

DocumentException

toXML

public void toXML(Writer writer,
                  int indentSize,
                  String encoding)
           throws IOException,
                  DocumentException

Get the XML represented by this document, and write it to the given Writer using the given indentSize and character encoding. The character encoding value must be given as a Java (not mime) encoding value. The caller should be careful that the specified Writer actually writes characters as bytes encoded using the given Java encoding.

Specified by:

toXML in interface IDocument

Throws:

IOException

DocumentException

main

public static void main(String[] args)