|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
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.
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 |
public Object clone() throws CloneNotSupportedException
CloneNotSupportedException
public String getRootElementName()
public boolean isParsed()
public void forceParsed() throws DocumentParseException, DocumentException
DocumentParseException
DocumentException
public Document getDocument()
public String getRawXML()
public Element getDocumentElement()
public String getSystemID()
public void setSystemID(String id)
public String getPublicID()
public void setPublicID(String id)
public EntityResolver getEntityResolver()
public void setDocumentElement(Element documentElement)
public void setEntityResolver(EntityResolver entityResolver)
public IDocumentDefinition getDocumentDefinition()
public void setDocumentDefinition(IDocumentDefinition docDef)
public String getDocumentTypeName()
public void setDocumentTypeName(String typeName)
public void ensureNamespaceDeclaration() throws DocumentParseException, DocumentException
DocumentParseException
- if this method is forced to parse raw XML
and the parse fails.
DocumentException
- if any other error occurs setting the namespace.public void ensureNoNamespaceDeclarations() throws DocumentParseException, DocumentException
DocumentParseException
- if this method is forced to parse raw XML
and the parse fails.
DocumentException
- if any other error occurs removing the namespace.public String getFirstNamespacePrefix() throws DocumentParseException, DocumentException
DocumentParseException
- if we're forced to parse the doc, and fail.
DocumentException
- if any other exception occurs getting the prefix.public String getEncoding()
public void setContextNode(String path) throws DocumentException
DocumentException
public void setContextNode(DocumentData data) throws DocumentException
DocumentException
setContextNode(String)
public void setContextNode(Node node)
setContextNode(DocumentData)
public void resetContextNode()
setContextNode(Node)
public String getStringFromFirst(String nodeName) throws DocumentException
DocumentException
getDocumentData(String)
public int getIntegerFromFirst(String nodeName) throws DocumentException
DocumentException
getStringFromFirst(String)
,
getDocumentData(String)
public boolean getBooleanFromFirst(String nodeName) throws DocumentException
DocumentException
getStringFromFirst(String)
,
getDocumentData(String)
public double getDoubleFromFirst(String nodeName) throws DocumentException
DocumentException
getStringFromFirst(String)
,
getDocumentData(String)
public Calendar getDateFromFirst(String nodeName) throws DocumentException
DocumentException
getStringFromFirst(String)
,
getDocumentData(String)
public Calendar getDateTimeFromFirst(String nodeName) throws DocumentException
DocumentException
getStringFromFirst(String)
,
getDocumentData(String)
public Calendar getTimeFromFirst(String nodeName) throws DocumentException
DocumentException
getStringFromFirst(String)
,
getDocumentData(String)
public boolean getValidating()
public String getStringFrom(String nodeName) throws DocumentException
DocumentException
getDocumentData(String)
public int getIntegerFrom(String nodeName) throws DocumentException
DocumentException
getStringFrom(String)
,
getDocumentData(String)
public boolean getBooleanFrom(String nodeName) throws DocumentException
DocumentException
getStringFrom(String)
,
getDocumentData(String)
public double getDoubleFrom(String nodeName) throws DocumentException
DocumentException
getStringFrom(String)
,
getDocumentData(String)
public Calendar getDateFrom(String nodeName) throws DocumentException
DocumentException
getStringFromFirst(String)
,
getDocumentData(String)
public Calendar getDateTimeFrom(String nodeName) throws DocumentException
DocumentException
getStringFromFirst(String)
,
getDocumentData(String)
public Calendar getTimeFrom(String nodeName) throws DocumentException
DocumentException
getStringFromFirst(String)
,
getDocumentData(String)
public IDocument[] getSubDocuments(String path) throws DocumentException
DocumentException
public DocumentData getDocumentData(String path) throws DocumentException
DocumentException
public void setStringInFirst(String nodeName, String newValue) throws DocumentException
DocumentException
public void setIntegerInFirst(String nodeName, int newValue) throws DocumentException
DocumentException
public void setBooleanInFirst(String nodeName, boolean newValue) throws DocumentException
DocumentException
public void setDoubleInFirst(String nodeName, double newValue) throws DocumentException
DocumentException
public void setDateInFirst(String nodeName, Calendar newValue) throws DocumentException
DocumentException
public void setDateTimeInFirst(String nodeName, Calendar newValue) throws DocumentException
DocumentException
public void setTimeInFirst(String nodeName, Calendar newValue) throws DocumentException
DocumentException
public void setValidating(boolean validating)
public void setStringIn(String nodeName, String newValue) throws DocumentException
DocumentException
public void setIntegerIn(String nodeName, int newValue) throws DocumentException
DocumentException
public void setBooleanIn(String nodeName, boolean newValue) throws DocumentException
DocumentException
public void setDoubleIn(String nodeName, double newValue) throws DocumentException
DocumentException
public void setDateIn(String nodeName, Calendar newValue) throws DocumentException
DocumentException
public void setDateTimeIn(String nodeName, Calendar newValue) throws DocumentException
DocumentException
public void setTimeIn(String nodeName, Calendar newValue) throws DocumentException
DocumentException
public void setDocumentData(String path, DocumentData value) throws DocumentException
DocumentException
public Attr addAttribute(String parentPath, String attrName) throws DocumentException
DocumentException
public Attr addAttribute(String parentPath, String attrName, String value) throws DocumentException
DocumentException
public Element addElement(String parentPath, String elementName) throws DocumentException
DocumentException
public Element addElement(String parentPath, String elementName, String value) throws DocumentException
DocumentException
public void addNode(String parentPath, Node node) throws DocumentException
DocumentException
public void addDocumentData(String parentPath, DocumentData value) throws DocumentException
DocumentException
public void removeDocumentData(String path) throws DocumentException
DocumentException
public String toXML() throws DocumentException
DocumentException
toXML(java.io.Writer)
,
toXML(java.io.Writer, int, String)
public void toXML(Writer writer) throws IOException, DocumentException
IOException
DocumentException
public void toXML(Writer writer, int indentSize, String encoding) throws IOException, DocumentException
IOException
DocumentException
public void fromXML(String xmlText) throws DocumentParseException, DocumentException
DocumentParseException
DocumentException
public void fromXML(File file) throws DocumentParseException, DocumentException
file
-
DocumentParseException
DocumentException
fromXML(File, String)
public void fromXML(File file, String encoding) throws DocumentParseException, DocumentException
file
- encoding
- The Java encoding style for the content in the given file.
DocumentParseException
DocumentException
public void fromXML(Reader reader) throws IOException, DocumentParseException, DocumentException
IOException
DocumentParseException
DocumentException
public void fromXML(InputSource inputSource) throws DocumentParseException, DocumentException
DocumentParseException
DocumentException
public void fromXML(ContentHandler contentHandler) throws DocumentParseException, DocumentException
DocumentParseException
DocumentException
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |