com.bowstreet.util
Interface IXml

All Known Implementing Classes:

CustomDataRetriever, com.bowstreet.util.IXmlProxy

public interface IXml

Overview

The Factory uses XML as the primary complex data type. XML is read into Java and Java objects are built to represent this XML. In this way the XML can be easily manipulated from Java. On many systems such as browsers, this is called a "Document Object Model" or DOM for short. The Factory has its own "DOM" not very different than others that are out there, though it is specifically taylored to the internal data within the Factory.

IXml is the java interface to the internal data structure in the Factory runtime that represents XML elements. Factory authors can create, get and set the various pieces of XML data using the IXml interface and its companion XmlUtil class.

Data Conventions

The primary data structure that IXml manipulates is the "element". An element has a name (also called a "tag"), zero or more attributes, and content. An attribute has a name (a symbol) and a value (a string). The content of an element is comprised of zero or more children. Most children you'll encounter are themselves other elements and in fact this interface uses "child" and "children" to refer to the element children. The content of an element can also contain text nodes and CDATA nodes. Text nodes have a string of text which is their data. In IXml, the text nodes themselves are hidden, i.e. they are not made available as objects, so you'll be working with just the string of text within the text node. CDATA nodes are very much like text nodes with an extra bit that allows them to contain odd characters like angle brackets which will not be interpreted as XML structure.

Example

In the document below we will be doing operations on the XML data in this example:

 <boat color="red" weight="1200">
    The greatest little boat in the world
     <sail  area="48">
         really strong nylon
         <thread thickness="2" >
             doesn't stretch much
         </thread>
     </sail>
     <anchor material="iron"/>
 </boat> 

The example is comprised of one outer element whose name is "boat". It has two attributes named color and weight which have respective values of "red" and "1200". The boat element has one text child of "The greatest little boat in the world" and two element children named sail and anchor.

Notes

1. IXml is implemented by the TaggedData class. TaggedData contains many internal methods. The methods exposed with the IXml interface are the simplest way as well as the preferred way to manipulate TaggedData.
2. Any comments that might have been in an XML document read in are not preserved. If preserving comments is required then an alternative XML model such as DOM or JDOM needs to be used.

See Also:

XmlUtil for documentation on methods that can parse strings of XML and HTML into IXml objects., XmlTreeWalker

Method Summary

void	addCDATASection(java.lang.String data) Create a new CDATA node and set its text to the argument.
void	addChildElement(IXml xml) Moves the specified element in the argument from its original parent to become the new last child of this element.
IXml	addChildElement(java.lang.String name) Create a new element with a name of the argument.
IXml	addChildElement(java.lang.String localname, java.lang.String prefix, java.lang.String namespaceURI) Add a child element to this element, with the specified localname, prefix (optionally null) and namespace URI See also IXml.addChildElement(String name) NS-Unaware method
IXml	addChildWithText(java.lang.String name, java.lang.String text) Similar to addChildElement.
void	addText(java.lang.String value) Creates a text node having the text of the first argument and makes it the new last child of this.
IXml	cloneElement() Creates a new unparented node whose attributes are the same as this node's attributes.
void	copyContent(IXml xml) Copy all the children of the xml argument (text and elements) and add them as children of this.
IXml	createPath(java.lang.String path) Ensures that the specified path of elements exist, creating elements if they do not.
void	declareNamespace(java.lang.String prefix, java.lang.String namespaceURI) Declare a namespace prefix to URI mapping on this element.
void	declareNamespaces(java.util.Map mappings) Declare a set of namespace prefix to URI mappings on this element.
IXml	findElement(java.lang.String path) Finds the specified element under this using an xpath like notation.
java.lang.String	getAttribute(java.lang.String name) Returns the value of the named attribute, or an empty string if the attribute does not exist on this.
java.lang.String	getAttribute(java.lang.String localName, java.lang.String namespaceURI) Get the value of the attribute on this element with this specified localname and associated with the specified namespace URI, without requiring prior knowledge of what ns prefix if any may be in use on the actual attribute.
java.util.Map	getAttributes() Returns the attributes of this element as a name-value pair Map.
java.util.List	getChildren() Returns a list of all of the children elements of this element.
java.util.List	getChildren(java.lang.String name) Returns a list of all of the element children of this element who's name matches the specified name.
java.util.List	getChildren(java.lang.String localName, java.lang.String namespaceURI) Get a (possibly empty) List of direct children elements of this element matching the specified localname and namespace URI, without requiring prior knowledge of what if any namespace prefix may be in use for the element.
IXml	getFirstChildElement() Returns the first child of this element
java.lang.String	getLocalName() Get the local name (without prefix) of this XML Element.
java.lang.String	getName() Returns the name of the XML tag for this element
java.lang.String	getNamespacePrefix() Get the namespace prefix associated with this XML Element, or empty String.
java.lang.String	getNamespaceURI() Get the namespace URI associated with this XML Element or null ONLY supported for XML created via namespace aware XML APIs and/or parser (eg, XmlUtil.parseXml(String), XmlUtil.parseXml(Reader), or XmlUtil.createXml(Object source) where source is JDOM or DOM object) Will return null if used on IXml element created with older namespace- unaware APIs such as XmlUtil.create("a:b") or IXml.addChild("y:z"); even though those older APIs "appear" to be creating a namespace qualified name.
IXml	getNextSiblingElement() Returns the next sibling of this element or null if this is the last child of its parent.
IXml	getParentElement() Gets the parent element of this element.
IXml	getPreviousSiblingElement() Returns the previous sibling of this element or null if this is the first child of its parent.
java.lang.String	getText() Returns the text from the first child text node of this element.
java.lang.String	getText(java.lang.String path) Finds the specified element and gets its first text value using an xpath like notation.
java.lang.Object	getUserObject() Returns the user object associated with this element.
java.lang.String	getValueOf(java.lang.String path) Returns the string value of the specified XSL Value-Of like expression.
void	insertBefore(IXml newChild, IXml refChild) Insert an existing node before the specified child.
void	moveContent(IXml xml) Remove the children from the IXml argument and add them to this IXml object.
void	removeAttribute(java.lang.String name) Removes the named attribute.
void	removeChildElement(IXml child) Removes the specified immediate child and makes it parentless.
void	removeChildElement(java.lang.String child) Removes the named immediate child from this element and makes the removed child parentless.
void	removeChildren() Removes all of the children from this element.
void	replaceChild(IXml newChild, IXml oldChild) Replace the old child with the new child.
void	setAttribute(java.lang.String name, java.lang.String value) Assigns or modifies the value of the specified attribute.
void	setAttribute(java.lang.String localName, java.lang.String prefix, java.lang.String namespaceURI, java.lang.String value) Set an attribute with the specified localname, prefix and namespaceURI.
void	setName(java.lang.String name) Renames this element with the specified name.
void	setText(java.lang.String value) Sets the first text node value for this element.
void	setText(java.lang.String path, java.lang.String value) Set the first text node value for the specified element path and create the path if it does not exist.
void	setUserObject(java.lang.Object userObject) The IXml interface allows you to associate an arbitrary Java object with an element.
java.lang.String	toString() Creates and returns a string of the IXml object in this.
void	writeHtml(java.io.Writer out) Writes out the XML data as proper HTML to the specified writer.
void	writeXml(java.io.Writer out) Writes out the XML data to the specified Writer character stream.

Method Detail

addCDATASection

void addCDATASection(java.lang.String data)

Create a new CDATA node and set its text to the argument. Make the new node be the new last child of this. CDATA stands for character data. You can include funny chars like angle brackets and ampersands in the text and they will used as is, not as XML structure.

Parameters:

data - The CDATA to add.

See Also:

addText(java.lang.String)

Example:

IXml example3 = XmlUtil.create("plane");
 example3.addCDATASection("some < & >'s");
 example3.getText(); =>  "some < & >'s"

addChildElement

void addChildElement(IXml xml)

Moves the specified element in the argument from its original parent to become the new last child of this element. Note that an element can have only one parent so if you want to leave the original under its existing parent yet also get the effect of having its data be a child of this, then you can clone the argument before passing it to addChildElement. Beware though that modifying either the original child element or it's clone will not affect the other.

Parameters:

xml - The IXml to add as an immediate child.

See Also:

addChildWithText

Example:

Move the argument into example1.
 example1.addChildElement(XmlUtil.create("motor"));

 Put a copy of the argument into example1.
 example1.addChildElement(an_elt.cloneElement());

addChildElement

IXml addChildElement(java.lang.String name)

Create a new element with a name of the argument. Make this new element the last child of this.

Parameters:

name - The name of the new immediate child to create.

Returns:

IXml reference to the new element.

See Also:

addChildWithText

Example:

example1.addChildElement("motor");
 example1.findElement("motor");  => the new element

addChildElement

IXml addChildElement(java.lang.String localname,
                     java.lang.String prefix,
                     java.lang.String namespaceURI)

Add a child element to this element, with the specified localname, prefix (optionally null) and namespace URI See also IXml.addChildElement(String name) NS-Unaware method

Parameters:

localname - for the new child element

prefix - associated with the namespace for the child elem (or null)

namespaceURI - for the namespace associated with the child

Returns:

IXml reference to the child element.

Throws:

XmlDOMException - if localname contains a colon ':' character

addChildWithText

IXml addChildWithText(java.lang.String name,
                      java.lang.String text)

Similar to addChildElement. In addition to creating a new child element and making it the new last child of this, a new text node is created containing the text of the second argument. This text node is made to be the child of the first new element created.

Parameters:

name - The name of the new immediate child element to create.

text - The text of the new child.

Returns:

The reference to the new child element.

See Also:

addChildElement

Example:

example1.addChildWithText("motor", "out of gas");
 example1.getText("boat/motor"); => "out of gas"

addText

void addText(java.lang.String value)

Creates a text node having the text of the first argument and makes it the new last child of this. If the last node of this is a text node, addText may, as an optimization, append the given string onto the end of the last text node. Beware: If this has a child text node followed by a child element node, and you perform an addText on this, then that new text will not be returned, even as the end of another string, by calling getText on this.

Parameters:

value - The text to add

See Also:

setText, getText

Example:

IXml example2 = XmlUtil.create("car");
 example2.addText("rent-a-wreck reject");
 example2.getText(); => "rent-a-wreck reject"
 example2.addText(" but still runs");
 example2.getText(); => "rent-a-wreck reject but still runs"
 example2.addChildElement("radio");
 example2.addText(" downhill");
 example2.getText();  =>  "rent-a-wreck reject but still runs"
 Note that we did not get "rent-a-wreck reject but still runs downhill"
 because of the interspersed "radio" child element.

cloneElement

IXml cloneElement()

Creates a new unparented node whose attributes are the same as this node's attributes. The children of this node are cloned and the clones are made to be children of the new node. Note - Any User Objects attached to cloned nodes will not be cloned, but will be copied by reference to the new node structure.

Returns:

The cloned XML element

Example:

example1.cloneElement();

copyContent

void copyContent(IXml xml)

Copy all the children of the xml argument (text and elements) and add them as children of this.

Parameters:

xml - The element to be copied.

See Also:

moveContent

Example:

example1.copyContent(some_ixml_object_to_copy);

createPath

IXml createPath(java.lang.String path)

Ensures that the specified path of elements exist, creating elements if they do not. If the path already exists within this, then createPath will do nothing.

Parameters:

path - The element path to build up

Returns:

The last element created, in this case the element named "new".

Example:

Below we create an element with name "foo", child "bar" and grandchild "new".
 foo becomes a new last child of "this".
 The bottom element, "new", is returned.
 example1.createPath("foo/bar/new");
 leaves us with a modified example1 of:
 <boat ...>
  ...
   <foo>
     <bar>
       <new/>
     </bar>
   </foo>
 </boat>

declareNamespace

void declareNamespace(java.lang.String prefix,
                      java.lang.String namespaceURI)

Declare a namespace prefix to URI mapping on this element. E.g., declareNamespace("abc", "urn:ABCCorpNS"); would add a prefix -> NS mapping for use within this element and children, and if/when this element were converted to a string for output, would result in an attribute of the form xmlns:abc="urn:ABCCorpNS" being added to the string form of this XML Element.

Parameters:

prefix -

namespaceURI -

Throws:

XmlDOMException - if prefix or namespaceURI arguments are null

declareNamespaces

void declareNamespaces(java.util.Map mappings)

Declare a set of namespace prefix to URI mappings on this element. Each entry in the Map defines a separate prefix to URI mapping to be added. "Adds" prefix to namespaceURI mappings to any existing on this element, to any that may already be defined on this element.

Parameters:

mappings - java.util.Map of prefix to namespace URI mappings

Throws:

XmlDOMException - if prefix or namespaceURI arguments are null

findElement

IXml findElement(java.lang.String path)

Finds the specified element under this using an xpath like notation.

Returns:

The found element, or null if none found.

Example:

Find the second instance of the child element of x2 that has
 a name of x3.
   IXml xmlTempData = xmlData.findElement("x1/x2/x3[1]");

 Find the first instance of an element named x3 beneath x2
 where the text value equals "y3".
   IXml xmlTempData = xmlData.findElement("x1/x2/[x3=y3]");

 Find the instance of x3 beneath x2 where the "name" attribute
 has a value of "junk".
   IXml xmlTempData = xmlData.findElement("x1/x2/x3[@name=junk]");

 Find the instance of x3 two levels below x1 where the second level
 element is unknown.
   IXml xmlTempData = xmlData.findElement("x1/*[1]/x3");

 Find the parent of x3 where a name attribute value equals "junk".
 This example will return the element named x2.
   IXml xmlTempData = xmlData.findElement("x1/x2/x3[@name=junk]/..");

 Find the instance of x2 that has an x1 parent and an x3
 child whose child text value equals "junk".
 Note the use of single quotes which must be used to not confuse the
 string "junk" with the whole argument that uses double quotes for delimiters.
   IXml xmlTempData = xmlData.findElement("x1/x2[x3='junk']");

 Find the instance of x3 that is a child of an x1 instance.
 The x1 instance to use is distinguished from other possible x1 instances
 because it is the first x1 instance that has an x2 child whose
 child text value equals "junk".  Here x2 and x3 are siblings, both of which
 are children of x1.
   IXml xmlTempData = xmlData.findElement("//x1[x2='junk']/x3");

 Find the first instance of x2 that is a descendant of x1. x2 can be
 an immediate child of x1 or at any level beneath it.
 IXml xmlTempData = xmlData.findElement("x1//x2");

 Note: The <i>begin</i> and <i>end</i> bracket characters ([ ]) are special characters
 that must not be used in the data section of the specified path.
 
 Warning: Using complex filters may not be as fast as using simple '/' notation(i.e. x1/x2/x3)

getAttribute

java.lang.String getAttribute(java.lang.String name)

Returns the value of the named attribute, or an empty string if the attribute does not exist on this.

Parameters:

name - The name of the attribute to get

Returns:

The value of the named attribute, or an empty string

See Also:

getAttributes, setAttribute, removeAttribute

Example:

example1.getAttribute("color");  => "red"

getAttribute

java.lang.String getAttribute(java.lang.String localName,
                              java.lang.String namespaceURI)

Get the value of the attribute on this element with this specified localname and associated with the specified namespace URI, without requiring prior knowledge of what ns prefix if any may be in use on the actual attribute. Useful when manipulating XML retrieved from a remote source where you know the Schema and Namespace URI(s) in use, but not necessarily what prefix(es) the originator of the XML may have used in the actual data. Only supported for attributes created with the parser, conversion from JDOM/DOM or via namespace aware setAttribute(lname, prefix, nsURI). Not intended for retrieving attributes created with the single argument IXml.setAttribute("a:b"); See also Namespace-Unaware IXml.getAttribute(String name); See also Namespace-Aware IXml.setAttribute(localname, prefix, nsURI);

Parameters:

localName - of the attribute

namespaceURI - associated with the attribute

Returns:

value of the attribute, or null if not found

getAttributes

java.util.Map getAttributes()

Returns the attributes of this element as a name-value pair Map. Use the java.util.Map interface to access the returned attributes.

Returns:

The attributes of this element, null (NOT an empty map) if no attributes

See Also:

getAttribute, setAttribute

Example:

Map my_atts = example1.getAttributes();
 my_atts.get("color"); => "red"

getChildren

java.util.List getChildren()

Returns a list of all of the children elements of this element. Text node children are ignored. Use the java.util.List interface to access the returned value.

Returns:

The List of child elements.

Example:

example1.getChildren().get(0) => the first child element of "this".

getChildren

java.util.List getChildren(java.lang.String name)

Returns a list of all of the element children of this element who's name matches the specified name. Use the java.util.List interface to access the returned value.

Returns:

The List of child elements.

Example:

example1.getChildren("sail").size() => 1

getChildren

java.util.List getChildren(java.lang.String localName,
                           java.lang.String namespaceURI)

Get a (possibly empty) List of direct children elements of this element matching the specified localname and namespace URI, without requiring prior knowledge of what if any namespace prefix may be in use for the element. Useful when manipulating XML retrieved from a remote source where you know the Schema and Namespace URI(s) in use, but not necessarily what prefix(es) the originator of the XML may have used in the actual data. Only supported for elements created with the parser, conversion from JDOM/DOM or via namespace aware addChildElement(lname, prefix, nsURI); Not intended for retrieving elements created with the single argument IXml.addChildElement("a:b"); method. See also Namespace-Unaware IXml.addChildElement(String name); See also Namespace-Unaware IXml.getChildren(String name); See also Namespace-Aware IXml.addChildElement(localname, prefix, nsURI);

Parameters:

localName - of the child(ren)

namespaceURI - associated with the attribute

Returns:

value of the attribute, or null if not found

getFirstChildElement

IXml getFirstChildElement()

Returns the first child of this element

Returns:

The element child, or null if none found.

See Also:

getPreviousSiblingElement, getNextSiblingElement

Example:

example1.getFirstChildElement().getName() => "sail"

getLocalName

java.lang.String getLocalName()

Get the local name (without prefix) of this XML Element. Works with both elements created with either new NS aware XmlUtil.create() and for elements created with the original single argument XmlUtil.create();

Returns:

String representation of localname (eg, "xyz" for element )

getName

java.lang.String getName()

Returns the name of the XML tag for this element

Returns:

The element tag name.

Example:

example1.getName(); => "boat"

getNamespacePrefix

java.lang.String getNamespacePrefix()

Get the namespace prefix associated with this XML Element, or empty String. Works with both elements created with either new NS aware XmlUtil.create() and for elements created with the original single argument XmlUtil.create();

Returns:

String representation of this element's prefix (optionally "" empty string)

getNamespaceURI

java.lang.String getNamespaceURI()

Get the namespace URI associated with this XML Element or null ONLY supported for XML created via namespace aware XML APIs and/or parser (eg, XmlUtil.parseXml(String), XmlUtil.parseXml(Reader), or XmlUtil.createXml(Object source) where source is JDOM or DOM object) Will return null if used on IXml element created with older namespace- unaware APIs such as XmlUtil.create("a:b") or IXml.addChild("y:z"); even though those older APIs "appear" to be creating a namespace qualified name.

Returns:

String rep of the namespace URI associated with this elem, or null

getNextSiblingElement

IXml getNextSiblingElement()

Returns the next sibling of this element or null if this is the last child of its parent.

Returns:

The reference to the next sibling element node, or null if none found.

See Also:

getFirstChildElement, getPreviousSiblingElement

Example:

example1.getFirstChildElement().getNextSiblingElement().getName() => "anchor"

getParentElement

IXml getParentElement()

Gets the parent element of this element.

Returns:

The parent element or null if no parent.

Example:

element1.getParentElement(); => null

getPreviousSiblingElement

IXml getPreviousSiblingElement()

Returns the previous sibling of this element or null if this is the first child of its parent. Warning: getPreviousSibling is not a fast operation.

Returns:

The previous sibling element node, or null if none found.

See Also:

getFirstChildElement, getNextSiblingElement

Example:

example1.getFirstChildElement().getPreviousSiblingElement() => null

getText

java.lang.String getText()

Returns the text from the first child text node of this element. If there are several text nodes immediately following the first text node then the returned string will be a concatenation of all the text from all of these nodes. However, if there are element nodes interspersed with text nodes, only the text from the first contiguous group of text nodes will be returned.

Returns:

The text or an empty string if no child text node exists.

See Also:

setText

Example:

example1.getText(); => "The greatest little boat in the world"

getText

java.lang.String getText(java.lang.String path)

Finds the specified element and gets its first text value using an xpath like notation. This is similar to getValueOf but can't be used to get attribute values. getText is also faster than getValueOf.

Returns:

The element text, or null if not found.

See Also:

findElement

Example:

example1.getText("sail");  => "really strong nylon"
 example1.getText("sail/thread");  => "doesn't stretch much"

getUserObject

java.lang.Object getUserObject()

Returns the user object associated with this element. Use getUserObject retrieve the attached object from this element. Note - When cloning nodes, the User Objects attached to cloned nodes will not be cloned, but will be copied by reference to the new node structure.

Returns:

The object associated with this element.

See Also:

setUserObject

Example:

example1.setUserObject(new Integer(486));
 example1.getUserObject().intValue(); => 486

getValueOf

java.lang.String getValueOf(java.lang.String path)

Returns the string value of the specified XSL Value-Of like expression.

Parameters:

path - The expression to be evaluated.

Returns:

The string value of the evaluated expression.

See Also:

findElement

Example:

example1.getValueOf("sail");  => "really strong nylon"
 example1.getValueOf("sail/@area"); => "48"
 example1.getValueOf("sail/thread");  => "doesn't stretch much"

insertBefore

void insertBefore(IXml newChild,
                  IXml refChild)

Insert an existing node before the specified child. If the refChild is null the newChild will be appended, i.e. made to be the new last child of this. newChild is moved from its previous location.

Parameters:

newChild - The new element to add.

refChild - The reference element to insert before.

See Also:

replaceChild

Example:

example1.insertBefore(XmlUtil.create("mast"), example1.getFirstChildElement());
 example1.getFirstChildElement(); => the new "mast" element.

moveContent

void moveContent(IXml xml)

Remove the children from the IXml argument and add them to this IXml object.
The end result on this object is the same as copyContents but, using moveContent, the input object is modified (it is not with copyContents.) This may be useful when you want the functionality of copyContent without the overhead of cloning the children.

Parameters:

xml - The IXml node to get the children from.

See Also:

copyContent

Example:

example1.moveContent(some_ixml_object_to_copy);

removeAttribute

void removeAttribute(java.lang.String name)

Removes the named attribute.

Parameters:

name - The name of the attribute to remove

See Also:

getAttribute, setAttribute

Example:

example1.removeAttribute("weight");
 example1.getAttribute("weight"); => ""

removeChildElement

void removeChildElement(IXml child)

Removes the specified immediate child and makes it parentless. If the child is NOT a child of this than an exception is thrown.

Parameters:

child - The immediate child to be removed.

Example:

IXml firstKid = example1.getFirstChildElement();
 example1.removeChildElement(firstKid);
 example1.getFirstChildElement(); => the element named "anchor".

removeChildElement

void removeChildElement(java.lang.String child)

Removes the named immediate child from this element and makes the removed child parentless. If no element named by the argument exists, this method does nothing and does not error.

Parameters:

child - The name of the immediate child to be removed.

Example:

example1.removeChildElement("sail");
 example1.getFirstChildElement(); => the element named "anchor".

removeChildren

void removeChildren()

Removes all of the children from this element.

See Also:

removeChildElement

Example:

example1.removeChildren();
 example1.getFirstChildElement(); => null

replaceChild

void replaceChild(IXml newChild,
                  IXml oldChild)

Replace the old child with the new child. Beware: newChild is moved from its previous location so its original parent will now no longer have newChild as a child.

Parameters:

newChild - The new element to add.

oldChild - The reference element to be replaced.

See Also:

insertBefore

Example:

example1.replaceChild(XmlUtil.create("mast"), example1.getFirstChildElement());
 example1.getFirstChildElement(); => the "mast" element.
 Now the "sail" child of example1 is gone.

setAttribute

void setAttribute(java.lang.String name,
                  java.lang.String value)

Assigns or modifies the value of the specified attribute. If the attribute did not previously exist, it will be created.

Parameters:

name - The name of the attribute to set

value - The attribute value

See Also:

getAttribute, removeAttribute

Example:

example1.setAttribute("color", "blue");
 example1.getAttribute("color");  => "blue"

setAttribute

void setAttribute(java.lang.String localName,
                  java.lang.String prefix,
                  java.lang.String namespaceURI,
                  java.lang.String value)

Set an attribute with the specified localname, prefix and namespaceURI. Unlike XML elements which can be associated with a default namespace without an explicit prefix, Attributes associated with namespace MUST have prefixes. See also Namespace-Unaware IXml.setAttribute(String name); See also Namespace-Aware IXml.getAttribute(localname, nsURI);

Parameters:

localName - of the attribute

prefix - associated with the namespace

namespaceURI - associated with the attribute

value -

Throws:

XmlDOMException - if prefix==null && namespaceURI != null

setName

void setName(java.lang.String name)

Renames this element with the specified name.

Parameters:

name - The new element name.

Example:

example1.setName("car");  example1.getName(); => "car"

setText

void setText(java.lang.String value)

Sets the first text node value for this element. If there is already a text node beneath this then its old text is replaced. If there isn't already a text node, one is created and given the text of the argument.

Parameters:

value - The text value to set

See Also:

getText

Example:

example1.setText("A leaky bathtub");
 example1.getText();  => "A leaky bathtub"

setText

void setText(java.lang.String path,
             java.lang.String value)

Set the first text node value for the specified element path and create the path if it does not exist. Path can contain slashes but none of the other special syntax characters.

Parameters:

path - The path of the element to set the text on

value - The text value to set

See Also:

getText, findElement, createPath

Example:

example1.setText("sail/thread", "ripped rags");
 example1.getText("sail/thread"); => "ripped rags"

setUserObject

void setUserObject(java.lang.Object userObject)

The IXml interface allows you to associate an arbitrary Java object with an element. Use setUserObject to attach an object to this element. Note - When cloning nodes, the User Objects attached to cloned nodes will not be cloned, but will be copied by reference to the new node structure.

Parameters:

userObject - object to be associated.

See Also:

getUserObject

Example:

example1.setUserObject(new Integer(486));
 example1.getUserObject().intValue(); => 486

toString

java.lang.String toString()

Creates and returns a string of the IXml object in this. Uses the XML format as opposed to the HTML format.

Overrides:

toString in class java.lang.Object

Returns:

a string

See Also:

writeXml(java.io.Writer)

Example:

example1.toString() => "<boat ..."

writeHtml

void writeHtml(java.io.Writer out)
               throws java.io.IOException

Writes out the XML data as proper HTML to the specified writer.

Parameters:

out - The Writer character stream to output to.

Throws:

java.io.IOException

See Also:

writeXml

Example:

example1.writeHtml(some_writer_stream);

writeXml

void writeXml(java.io.Writer out)
              throws java.io.IOException

Writes out the XML data to the specified Writer character stream. Any comments that might have been in an XML document read in are not preserved (they're discarded during formation of the internal objects). If preserving comments is required then an alternative XML model such as DOM or JDOM needs to be used.

Parameters:

out - The Writer to output to.

Throws:

java.io.IOException

See Also:

writeHtml

Example:

StringWriter sw = new StringWriter();
 example1.writeHtml(sw);
 sw.toString(); => "<boat ...."