Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## com.bea.document
Interface IDocument

All Superinterfaces:
  Cloneable, Serializable

All Known Implementing Classes:
  Document

public interface IDocument
extends Serializable, Cloneable

An IDocument represents an XML document. An IDocument can provide its document type name (which may be used to refer to a description of its structure and usage). In addition, IDocuments are mutable, and provide methods for retrieving, modifying, adding and removing data elements. All IDocument objects are queryable and updatable using XPath strings. Also, all IDocument instances are serializable to XML and unserializable from XML. IDocument objects should implement the java.io.Serializable interface.

An example of the usage of an IDocument follows. In this example, we are attempting to create an XML document that looks like this...

       <?xml version="1.0"?>
       <!DOCTYPE Person>
       <Person name="Bob">
         <Home squareFeet="2000"/>
         <Goal>My goal is to elliminate war and poverty</Goal>
         <Family>
           <Child name="Jimmy">
             <Stats sex="male" hair="brown" eyes="blue"/>
           </Child>
           <Child name="Susie">
             <Stats sex="female" hair="blonde" eyes="brown"/>
           </Child>
         </Family>
       </Person>

To construct this document, we would use the following code...

       // Create a blank IDocument (you will get xml header and DOCTYPE for free)
       IDocument person = DocumentFactory.createDocument();
       // Add <Person>
       person.addElement("", "Person");
       // Add <Person name="Bob">
       person.addAttribute("/Person", "name", "Bob");
       // Add <House/> under <Person>
       person.addElement("/Person", "House");
       // Add squareFeet="2000" to <House>
       person.addAttribute("/Person/House", "squareFeet", "2000");
       // Add <Goal>My goal is to elliminate war and poverty</Goal>
       // under <Person>
       person.addElement("/Person", "Goal", "My goal is to elliminate war and poverty");
       // Now add family
       person.addElement("/Person", "Family");
       // Add first child
       Element firstChild = person.addElement("/Person/Family", "Child");
       // Focus on first child
       person.setContextNode(firstChild);
       // Fill in statistics about first child. This add occurs relative to
       // the context node which we just set to firstChild.
       person.addElement("", "Stats");
       person.addAttribute("Stats", "sex", "male");
       person.addAttribute("Stats", "hair", "brown");
       person.addAttribute("Stats", "eyes", "blue");
       // Stop focusing on first child
       person.resetContextNode();
       // And second child
       Element secondChild = person.addElement("/Person/Family", "Child");
       // Focus on second child
       person.setContextNode(secondChild);
       // Fill in statistics about second child. This add occurs relative to
       // the context node which we just set to secondChild.
       person.addElement("", "Stats");
       person.addAttribute("Stats", "sex", "female");
       person.addAttribute("Stats", "hair", "blonde");
       person.addAttribute("Stats", "eyes", "brown");
       // Stop focusing on second child
       person.resetContextNode();

Note that if we already had the XML to represent this person, we could have used this code to create the IDocument...

       String personXML = ...get the XML from somewhere...
       IDocument person = DocumentFactory.createDocument(personXML);

To see the XML for this document, we use this code...

       System.out.println("The XML for person is: " + person.toXML());

To query the person's name and goal and number of kids, we use this code...

       System.out.println("The person's name: " + person.getStringFrom("/Person/@name");
       System.out.println("The person's goal: " + person.getStringFrom("/Person/Goal");
       System.out.println("Number of kids:    " + person.getIntegerFrom("count(/Person/Family/Child)");

To change the person's name and goal and second child's hair color, we use this code...

       person.setStringIn("/Person/@name", "BillyBob");
       person.setStringIn("/Person/Goal", "To ski 50 times this season");
       person.setStringIn("/Person/Family/Child[2]/@hair", "pink");
       System.out.println("The person's name: " + person.getStringFrom("/Person/@name");
       System.out.println("The person's goal: " + person.getStringFrom("/Person/Goal");
       System.out.println("Second childs hair:" + person.getStringFrom("/Person/Family/Child[2]/@hair");

To remove the person's goal, we use this code...

       person.removeDocumentData("/Person/Goal");

To get back the XML content from the document, we use this code...

       // Print the XML as a string
       System.out.println("Person XML: " + person.toXML());

       // Print the XML to a Writer (file)
       java.io.FileWriter fw = new java.io.FileWriter("myFile.xml");
       person.toXML(fw);

The default representation of the document represented by IDocument is a org.w3c.dom.Document (i.e. DOM). The IDocument may at times be in an unparsed state. This can happen if the IDocument was explicitly constructed this way (using DocumentFactory.createDocument(String, boolean) where the second arg is true. You can determine the internal state of an IDocument using the isParsed() method. If this returns true, then the content of the document has been parsed into a DOM, otherwise, the IDocument contains just the raw XML text.

In cases where an IDocument is in an unparsed state, you may want to parse the content using a SAX parsing scheme that allows you to build your own in-memory representation of the document (not DOM). The fromXML(ContentHandler) method is provided for this purpose, and allows you to parse the document's content manually using an implementation of the ContentHandler interface. Note that you could accomplish the same thing by getting the raw content from the IDocument, and creating/invoking your own SAX parser.

For more information see the W3C web site for XPath, XML, and DOM.

See Also:
  XML Path Language (XPath), Extensible Markup Language (XML), Document Object Model (DOM), `DocumentFactory`, `IDocumentDefinition`

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.
`void` | `ensureNoNamespaceDeclarations()` 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).
`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 org.w3c.Document contained in 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 element that acts as the document root element for 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 used when unserializing.
`String` | `getFirstNamespacePrefix()` Get the first usable namespace prefix from this document.
`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 tag name for this document.
`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 IDocument validating content in calls to fromXML()?
`boolean` | `isParsed()` Is this document's XML parsed.
`void` | `removeDocumentData(String path)` Remove the data element referred to by path.
`void` | `resetContextNode()` Resets the context node to the document root element.
`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 data element found with the given name to the string representation of the given 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 data element found with the given name to the string representation of the given 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 data element found with the given name to the string representation of the given 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 element that will act as the document root element for this document.
`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 data element found with the given name to the string representation of the given newValue.
`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 data element found with the given name to the string representation of the given newValue.
`void` | `setPublicID(String id)` Get the system 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 data element found with the given name to the string 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 data element found with the given name to the string representation of the given newValue.
`void` | `setValidating(boolean validating)` Set this IDocument to validate/not-validate during calls to fromXML.
`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 indent size and character encoding.

Method Detail

### clone

    public Object clone()
                 throws CloneNotSupportedException

  Clone this document. This is a 'deep' clone, and the returned object is independent and unrelated to the original document.

  Throws:
    `CloneNotSupportedException`

### getRootElementName

    public String getRootElementName()

  Get the root element tag name for this document. If the root element has not yet been established, the root element name is 'Unknown'.

### 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.

### 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.

  Throws:
    `DocumentParseException`
    `DocumentException`

### getDocument

    public Document getDocument()

  Get the org.w3c.Document contained in this document. This method only returns non-null if this document is in the 'parsed' state (as determined by the isParsed() method). If not, this method returns null, and the user must use the 'getRawXML()' method to retrieve the content for the document. The user can call the fromXML() method using the raw XML if they require immediate access to the parsed (DOM) content, and then use the getDocument() method.

### 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.

### getDocumentElement

    public Element getDocumentElement()

  Get the element that acts as the document root element for this document.

### getSystemID

    public String getSystemID()

  Get the system id for this document.

### setSystemID

    public void setSystemID(String id)

  Set the system id for this document.

### getPublicID

    public String getPublicID()

  Get the public id for this document.

### setPublicID

    public void setPublicID(String id)

  Get the system id for this document.

### getEntityResolver

    public EntityResolver getEntityResolver()

  Get the EntityResolver used when unserializing.

### setDocumentElement

    public void setDocumentElement(Element documentElement)

  Set the element that will act as the document root element for this document.

### setEntityResolver

    public void setEntityResolver(EntityResolver entityResolver)

  Set the EntityResolver to use when unserializing.

### getDocumentDefinition

    public IDocumentDefinition getDocumentDefinition()

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

### setDocumentDefinition

    public void setDocumentDefinition(IDocumentDefinition docDef)

  Set the IDocumentDefinition for this document.

### 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.

### 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.

### 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.

  Throws:
    `DocumentParseException` - if this method is forced to parse raw XML and the parse fails.
    `DocumentException` - if any other error occurs setting 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.

  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.

  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.

### 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.

### setContextNode

    public void setContextNode(String path)
                        throws DocumentException

  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.

  Throws:
    `DocumentException`

### setContextNode

    public void setContextNode(DocumentData data)
                        throws DocumentException

  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.

  Throws:
    `DocumentException`
  See Also:
    `setContextNode(String)`

### setContextNode

    public void setContextNode(Node node)

  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.

  See Also:
    `setContextNode(DocumentData)`

### resetContextNode

    public void resetContextNode()

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

  See Also:
    `setContextNode(Node)`

### 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.

  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.

  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.

  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.

  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.

  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)`

### 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.

  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)`

### 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.

  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)`

### getValidating

    public boolean getValidating()

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

### 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.

  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.

  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.

  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.

  Throws:
    `DocumentException`
  See Also:
    `getStringFrom(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.

  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)`

### 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.

  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)`

### 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.

  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)`

### 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.

  Throws:
    `DocumentException`

### getDocumentData

    public DocumentData getDocumentData(String path)
                                 throws DocumentException

  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

  Throws:
    `DocumentException`

### setStringInFirst

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

  Set the first data element found with the given name to the string given by newValue.

  Throws:
    `DocumentException`

### setIntegerInFirst

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

  Set the first data element found with the given name to the string representation of the given newValue.

  Throws:
    `DocumentException`

### setBooleanInFirst

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

  Set the first data element found with the given name to the string representation of the given newValue.

  Throws:
    `DocumentException`

### setDoubleInFirst

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

  Set the first data element found with the given name to the string representation of the given newValue.

  Throws:
    `DocumentException`

### setDateInFirst

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

  Set the first data element found with the given name to the string representation of the given newValue.

  Throws:
    `DocumentException`

### setDateTimeInFirst

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

  Set the first data element found with the given name to the string representation of the given newValue.

  Throws:
    `DocumentException`

### setTimeInFirst

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

  Set the first data element found with the given name to the string representation of the given newValue.

  Throws:
    `DocumentException`

### setValidating

    public void setValidating(boolean validating)

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

### 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.

  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.

  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.

  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.

  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.

  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.

  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.

  Throws:
    `DocumentException`

### setDocumentData

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

  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

  Throws:
    `DocumentException`

### addAttribute

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

  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.

  Returns:
    The DOM attribute created by this method.
  Throws:
    `DocumentException`

### addAttribute

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

  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.

  Returns:
    The DOM attribute created by this method.
  Throws:
    `DocumentException`

### addElement

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

  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.

  Returns:
    The DOM element created by this method.
  Throws:
    `DocumentException`

### addElement

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

  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.

  Returns:
    The DOM element created by this method.
  Throws:
    `DocumentException`

### addNode

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

  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.

  Throws:
    `DocumentException`

### addDocumentData

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

  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.

  Throws:
    `DocumentException`

### removeDocumentData

    public void removeDocumentData(String path)
                            throws DocumentException

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

  Throws:
    `DocumentException`

### 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.

  Throws:
    `DocumentException`
  See Also:
    `toXML(java.io.Writer)`, `toXML(java.io.Writer, int, String)`

### 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 a default indent size of 2 spaces, and a default Java character encoding of UTF8. The caller should be careful that the specified Writer actually writes characters as bytes encoded using the UTF8 Java encoding.

  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 indent size and character encoding. The specified encoding must be given as a valid Java encoding value (not a mime encoding value). For example to get an encoding value for UTF 8, you should specify encoding as "UTF8" and not the mime encoding value of "UTF-8". The caller should be careful that the specified Writer actually writes characters as bytes encoded using the specified Java encoding.

  Throws:
    `IOException`
    `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).

  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.

  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.

  Parameters:
    `file` -
    `encoding` - The Java encoding style for the content in the given file.
  Throws:
    `DocumentParseException`
    `DocumentException`

### fromXML

    public void fromXML(Reader reader)
                 throws IOException,
                        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.

  Throws:
    `IOException`
    `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).

  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.

  Throws:
    `DocumentParseException`
    `DocumentException`

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD