Chapter 24. DOM Reference

Java binding

Public String getName( );

Java example

// Dump element attribute names
Attr attr;
    
for (int i = 0; i < elem.getAttributes().getLength( ); i++) {
    // temporarily alias the attribute
    attr = (Attr)elem.getAttributes( ).item(i);
    System.out.println(attr.getName( ));
    }

Java binding

public Element getOwnerElement( );

Java binding

public boolean getSpecified( );

Java example

// Dump element attribute names
for (int i = 0; i < elem.getAttributes().getLength( ); i++) {
    // temporarily alias the attribute
    attr = (Attr)elem.getAttributes( ).item(i);
    // only show attributes that were explicitly included in the XML 
    //source file
     // (i.e. ignore default attributes from the DTD.)
     if (attr.getSpecified( )) {
         System.out.println(attr.getName( ));
    }
}

Java bindings

public String getValue( );
public void setValue(String value);

Java example

// Make all attribute values lowercase
Attr attr;

for (int i = 0; i < elem.getAttributes().getLength( ); i++) {
    attr = (Attr)elem.getAttributes( ).item(i);
    attr.setValue(attr.getValue().toLowerCase( ));
}

Exceptions

NO_MODIFICATION_ALLOWED_ERR

Raised on a write attempt when the data attribute is read-only for this DOM object type.

DOMSTRING_SIZE_ERR

Raised if the read value that would be returned is too large to be contained by a DOMString type in the given implementation.

Java bindings

public String getData( ) throws DOMException;
public void setData(String data) throws DOMException;

Java example

// Quote the CharacterData node contents
CharacterData ndCD = 
 (CharacterData)doc.createTextNode("Unquoted text.");
...
ndCD.setData('\"' + ndCD.getData( ) + '\"');

Java binding

public long getLength( );

Java example

// Display the contents of a CharacterData node
CharacterData ndCD = (CharacterData)doc.createTextNode("This string has
 30 characters.");

System.out.println("The string \'" + ndCD.getData( ) + "\' has " 
            + Long.toString(ndCD.getLength( )) + " characters.");

Argument

arg: DOMString

The string to append.

Exception

NO_MODIFICATION_ALLOWED_ERR

Raised if this node is read-only.

Java binding

public void appendData(String arg) throws DOMException;

Java example

// Append to an existing string
// Create a new Text object and reference the CharacterData interface

CharacterData ndCD = (CharacterData)doc.createTextNode("The truth is ");
// flip a coin

ndCD.appendData((Math.random( ) < 0.5) ? "out there." : "in here.");
System.out.println(ndCD.getData( ));

Arguments

offset: unsigned long

The position in the data attribute to remove count characters.

count: unsigned long

The count of characters to remove. If the offset + count is >= the length attribute, the remainder, starting at position offset, is deleted.

Exceptions

INDEX_SIZE_ERR

Raised if the offset parameter is not a valid zero-based index into the data DOMString.

NO_MODIFICATION_ALLOWED_ERR

Raised if the node is read-only.

Java binding

public void deleteData(long offset, long count)
               throws DOMException;

Java example

// Create a new Text object and reference the CharacterData interface
CharacterData ndCD = (CharacterData)doc.createTextNode("The truth is
                      not out there.");

// change of heart
ndCD.deleteData(12, 4);

System.out.println(ndCD.getData( ));

Arguments

offset: unsigned long

The zero-based offset in the data attribute where the insertion is made.

arg: DOMString

The string to be inserted.

Exceptions

INDEX_SIZE_ERR

Raised if the offset parameter is not a valid, zero-based index into the data DOMString.

NO_MODIFICATION_ALLOWED_ERR

Raised if the node is read-only.

Java binding

public void insertData(long offset, String arg) throws
  DOMException;

Java example

// Insert data into a string
boolean fCynical = true;

// create a new Text object, and reference the CharacterData interface
CharacterData ndCD = (CharacterData)doc.createTextNode("The truth is
                      out there.");

...

// check for cynicism
if (fCynical) {
    ndCD.insertData(12, " not");
}

System.out.println(ndCD.getData( ));

Arguments

offset: long

The offset of the beginning of the replacement region.

count: long

The number of characters to replace. If offset + count is >= the length attribute, everything beyond the offset character position is replaced.

arg: DOMString

The replacement string.

The replaceData operation is the equivalent of the following code fragment:

cdNode.deleteData(offset, count);
     cdNode.insertData(offset, arg);

Exceptions

INDEX_SIZE_ERR

Raised if the offset parameter is not a valid, zero-based index into the data DOMString.

NO_MODIFICATION_ALLOWED_ERR

Raised if the node is read-only.

Java binding

public void replaceData(long offset, long count,
                        String arg) throws DOMException;

Java example

 // Create a new Text object and reference the CharacterData interface
CharacterData ndCD = (CharacterData)doc.createTextNode("The truth is
                      not out there.");

// replace the truth
String strFind = "truth";
String strReplace = "dog";
    
ndCD.replaceData(ndCD.getData().indexOf(strFind), strFind.length( ), 
                 strReplace);

System.out.println(ndCD.getData( ));

Arguments

offset: unsigned long

Zero-based, starting offset of the substring to return. A valid offset must be >= 0 and < the length attribute of the node.

count: unsigned long

Count of characters to return.

Exceptions

Java binding

public String substringData(unsigned long offset, unsigned long count)
                 throws DOMException;

Java example

// Get a reference to the CharacterData interface
CharacterData ndCD = (CharacterData)doc.createTextNode("The truth is
                      out there.");

// we only want the "truth"
String strTruth = ndCD.substringData(4, 5);

System.out.println("The substring is '" + strTruth + '\'');

Java binding

public DocumentType getDoctype( );

Java example

// Get the parsed DTD information for this document
DocumentType docType = docIn.getDoctype( );

if (docType == null) {
    System.out.println("warning: no DTD provided");
}

Java binding

public Element getDocumentElement( );

// Identify the root element
Element elRoot = docIn.getDocumentElement( );
System.out.println("This is a '" + elRoot.getTagName( ) + "' document.");

Java binding

public DOMImplementation getImplementation( );

Java example

// Ensure the support of DOM Level 1 XML
DOMImplementation di = doc.getImplementation( );
if (!di.hasFeature("XML", "1.0")) {
    return false;
}

Argument

name: DOMString

The name of the XML attribute.

Return value

The new Attr object.

Exception

Exceptions

Argument

data: DOMString

The text contained by the new CDATASection object.

Exception

NOT_SUPPORTED_ERR

Occurs if you try to call this method on an HTML document.

Java binding

public CDATASection createCDATASection(String data) throws DOMException;

Java example

// Use CDATASection to embed XML characters
CDATASection cds = doc.createCDATASection("
<xml_example>This is sample text.</xml_example>
");

Exceptions

Argument

name: DOMString

The name of the XML entity to be referenced. The name must match an XML entity declaration that is valid in the current document.

Exceptions

Arguments

target: DOMString

The target name of the processing instruction. This name identifies the application that will interpret the data portion of the instruction.

data: DOMString

The application-specific data for the resulting ProcessingInstruction node.

Exceptions

Argument

data: DOMString

The string that will be the contents of the new node.

Java binding

public Text createTextNode(String data);

Java example

// Create a new node that contains character data
Text txtDesc = doc.createTextNode("Character data contents for a new
                                  Element.");

Argument

tagName: DOMString

The name of the tag to use as a filter. The special name * matches any tag.

Java binding

public NodeList getElementsByTagName(String tagName);

Java example

// Get a list of all phone numbers in the document
NodeList nl = doc.getElementsByTagName("phone_number");

Arguments

namespaceURI: DOMString

The namespace URI of the elements to be matched. The special * value matches any namespace.

localName: DOMString

The local name part of the elements to be matched. The special value * matches any local name.

Java binding

public NodeList getElementsByTagNameNS(String namespaceURI,
                                       String localName);

Arguments

importedNode: Node

The node duplicated for use in the current document hierarchy.

deep: boolean

Whether to copy the single node given or the entire subtree of its children. For details, see the previous table.

Exception

Java binding

public Node importNode(Node importedNode, boolean deep)
    throws DOMException;

Java binding

public NamedNodeMap getEntities( );

Java example

// Dump the document entities
NamedNodeMap nnm = doc.getDoctype().getEntities( );

Entity ndEnt;
for (int i = 0; i < nnm.getLength( ); i++) {
    ndEnt = (Entity)nnm.item(i);

    System.out.println(ndEnt.getNodeName( ));

    if (ndEnt.getPublicId( ) != null) {
        System.out.println("\tPublic Identifier: " +
                           ndEnt.getPublicId( ));
    }

    if (ndEnt.getSystemId( ) != null) {
        System.out.println("\tSystem Identifier: " +
                           ndEnt.getSystemId( ));
    }

    if (ndEnt.getNotationName( ) != null) {
        System.out.println("\tNotation Name: " +
                           ndEnt.getNotationName( ));
    }
}

Java binding

public String getInternalSubset( );

Java binding

public String getName( );

Java example

// Display document type information
DocumentType dtDoc = doc.getDoctype( );

System.out.println("This is a " + dtDoc.getName( ) + " document.");

Java binding

public NamedNodeMap getNotations( );

Java example

// Dump the document notations
NamedNodeMap nnm = doc.getDoctype().getNotations( );
Notation ndNotation;
for (int i = 0; i < nnm.getLength( ); i++) {
    ndNotation = (Notation)nnm.item(i);

    System.out.println(ndNotation.getNodeName( ));
    if (ndNotation.getPublicId( ) != null) {
        System.out.println("\tPublic Identifier: " +
                           ndNotation.getPublicId( ));
    }
    if (ndNotation.getSystemId( ) != null) {
        System.out.println("\tSystem Identifier: " +
                           ndNotation.getSystemId( ));
    }
}

Java binding

public String getPublicId( );

Java binding

public String getSystemId( );

Java binding

public static final short INDEX_SIZE_ERR = 1;

Java binding

public static final short DOMSTRING_SIZE_ERR = 2;

Java binding

public static final short HIERARCHY_REQUEST_ERR = 3;

Java binding

public static final short WRONG_DOCUMENT_ERR = 4;

Java binding

public static final short INVALID_CHARACTER_ERR = 5;

Java binding

public static final short NO_DATA_ALLOWED_ERR = 6;

Java binding

public static final short NO_MODIFICATION_ALLOWED_ERR = 7;

Java binding

public static final short NOT_FOUND_ERR = 8;

Java binding

public static final short NOT_SUPPORTED_ERR = 9;

Java binding

public static final short INUSE_ATTRIBUTE_ERR = 10;

Java binding

public static final short INVALID_STATE_ERR = 11;

Java binding

public static final short SYNTAX_ERR = 12;

Java binding

public static final short INVALID_MODIFICATION_ERR = 13;

Java binding

public static final short NAMESPACE_ERR = 14;

Java binding

public static final short INVALID_ACCESS_ERR = 15;

Arguments

namespaceURI: DOMString

The namespace URI used to create the top-level document element. Can be null if no namespace is used.

qualifiedName: DOMString

The namespace-aware qualified name of the top-level document element to be created. The prefix given in this parameter is associated with the namespace URI given in the namespaceURI parameter.

doctype: DOMString

The document type definition object to be associated with the new document. If this parameter is not null, the DocumentType node's ownerDocument attribute is set to point to the new document object.

Exceptions

INVALID_CHARACTER_ERR

Indicates that the qualifiedName parameter has a malformed XML identifier.

NAMESPACE_ERR

Raised if an inconsistency exists between the values given for the namespaceURI and the qualifiedName parameters. Passing in a qualified name with a namespace prefix and not passing in a namespace URI is illegal. This can also be generated if a reserved namespace prefix, such as "xml", is given with an incorrect namespace URI.

WRONG_DOCUMENT_ERR

Raised if the DocumentType node passed in the doctype parameter is already associated with another document object. New DocumentType objects must be created using the new createDocumentType method of the DOMImplementation interface.

Java binding

public Document createDocument(String namespaceURI,
    String qualifiedName, DocumentType doctype) throws DOMException;

Arguments

qualifiedName: DOMString

The qualified name of the document type to be created.

publicId: DOMString

The external subset's public identifier.

systemId: DOMString

The system identifier (URI) of the external subset to be created.

Return value

A new DocumentType object with the ownerDocument attribute set to null.

Exceptions

INVALID_CHARACTER_ERR

Indicates that the qualifiedName parameter has a malformed XML identifier.

NAMESPACE_ERR

Raised if the qualified name is malformed.

Java binding

public DocumentType createDocumentType(String qualifiedName,
         String publicId, String systemId) throws DOMException;

Arguments

Java binding

public String getTagName( );

// Show the name of the root element tag
Element elem = doc.getDocumentElement( );
System.out.println("This is a " + elem.getTagName( ) + " document.");

Arguments

namespaceURI: DOMString

The namespace URI of the attribute to return.

localName: DOMString

The local name portion of the qualified attribute name to return.

Return value

Returns an empty string if no attribute is set and if no default attribute value was specified in the DTD.

Java binding

public String getAttributeNS(String namespaceURI, String localName);

Arguments

name: DOMString

Name of the attribute to retrieve.

Java binding

public Attr getAttributeNode(String name);

Java example

// Use the id attribute
Attr attr;

if ((attr = elem.getAttributeNode("id")) == null) {
    System.out.println("warning: element " + elem.getTagName( ) + 
                       ": no id attribute provided.");
}

Arguments

namespaceURI: DOMString

Namespace URI of the target attribute.

localName: DOMString

Local name of the target attribute. The local name is the part of the name to the right of the : in a qualified name.

Java binding

public Attr getAttributeNodeNS(String namespaceURI, String localName);

Argument

name: DOMString

The name of the tag to use as a filter. The special name * matches any tag.

Java binding

public NodeList getElementsByTagName(String name);

Java example

// Find every address element in the document
Element elem = doc.getDocumentElement( );
NodeList nlAddrs = elem.getElementsByTagName("address");

Arguments

namespaceURI: DOMString

The namespace URI of elements to be matched. The special * value matches any namespace.

localName: DOMString

The local name part of elements to be matched. The special value * matches any local name.

Java binding

public NodeList getElementsByTagNameNS(String namespaceURI,
                                       String localName);

Argument

name: DOMString

The name of the attribute to be identified.

Java binding

public boolean hasAttribute(String name);

Arguments

namespaceURI: DOMString

The namespace URI of the attribute to be identified.

localName: DOMString

The local name of the attribute to be identified.

Java binding

public boolean hasAttribute(String namespaceURI, String localName);

NOTE: This method was moved to the Node interface as part of the DOM Level 2 specification. It is still accessible from the Element interface, as it inherits from the Node interface.

Java binding

public void normalize( );

Java example

// Merge all adjacent text nodes below this element
elem.normalize( );

Argument

name: DOMString

Name of the attribute to remove.

Exception

NO_MODIFICATION_ALLOWED_ERR

Raised if the element is read-only.

Java binding

public void removeAttribute(String name) throws DOMException;

Java example

// Remove the unique ID
...
elem.removeAttribute("id");
...

Arguments

namespaceURI: DOMString

Namespace URI of the target attribute.

localName: DOMString

Local name part of the target attribute. The local name is the part to the right of the final : in a qualified name.

Exception

NO_MODIFICATION_ALLOWED_ERR

Raised if the element is read-only.

Java binding

public void removeAttributeNS(String namespaceURI, String localName)
               throws DOMException;

Argument

oldAttr: Attr

The attribute node to remove.

Exceptions

NO_MODIFICATION_ALLOWED_ERR

Raised if the node is read-only.

NOT_FOUND_ERR

Raised if no attribute name matching the oldAttr parameter is found in the map.

Java binding

public Attr removeAttributeNode(Attr oldAttr) throws DOMException;

Java example

// Find and remove temporary attributes
Attr attr;

if ((attr = elem.getAttributeNode("temp")) != null) {
    // remove it
    elem.removeAttributeNode(attr);
}

Arguments

name: DOMString

The attribute name to set or modify.

value: DOMString

The new attribute value.

Exceptions

INVALID_CHARACTER_ERR

Indicates that the attribute name you passed in doesn't represent a valid XML attribute name.

NO_MODIFICATION_ALLOWED_ERR

Raised if the element is read-only.

Java binding

public void setAttribute(String name, String value) throws DOMException;

Java example

// Check for the name attribute
if (elem.getAttribute("name") == "") {
    // oh well, set a reasonable default
    elem.setAttribute("name", elem.getTagName( ));
}

Arguments

namespaceURI: DOMString

The namespace URI of the attribute value to set.

qualifiedName: DOMString

The qualified name (including namespace prefix) of the new value to set.

value: DOMString

The new attribute value.

Exceptions

Argument

newAttr: Attr

The new Attr object to set.

Exceptions

WRONG_DOCUMENT_ERR

Raised if the newAttr node was created in a document different than the parent node.

NO_MODIFICATION_ALLOWED_ERR

Raised if the new parent node is read-only.

INUSE_ATTRIBUTE_ERR

Raised if another Element already uses the new Attr node. Each element must have a distinct Attr object.

Java binding

public Attr setAttributeNode(Attr newAttr) throws DOMException;

Java example

// Make sure you have an id attribute to work with
Attr attr;

if ((attr = elem.getAttributeNode("id")) == null) {
    // add a default, unique id
    attr = doc.createAttribute("id");

    elem.setAttributeNode(attr);

    // continue processing
}

Argument

newAttr: Attr

The new Attr object to set.

Exceptions

Java binding

public Attr setAttributeNodeNS(Attr newAttr) throws DOMException;

Java binding

public String getNotationName( );

Java example

// Find out if it's a parsed entity
boolean fParsedEnt = ndEnt.getNotationName( ) == null;

Java binding

public String getPublicId( );

Java example

// Locate the my_entity entity declaration
Entity ndEnt = (Entity)doc.getDoctype().getEntities( ).getNamedItem("my_
entity");
    
// if my_entity type was found and there is a public-ID (URL)...
if (ndEnt != null && ndEnt.getPublicId( ) != null) {
    try {
        // ...get the URL protocol
        URL urlSys = new URL(ndEnt.getPublicId( ));
        System.out.println("Entity " + ndEnt.getNodeName( ) +
                           ": protocol " + urlSys.getProtocol( ));
    } catch (MalformedURLException e) {
    }
}

Java binding

public String getSystemId( );

Java example

// Get the Public ID or System ID for this entity
Entity ndEnt = (Entity)doc.getDoctype().getEntities( ).getNamedItem("my_ entity");

String strURL = ndEnt.getPublicId( );
    
// if can't find the public URL
if (strURL == null) {
    // find the system URL
    strURL = ndEnt.getSystemId( );
}

Java binding

public long getLength( );

Java example

// Iterate over the attribute list
for (int i = 0; i < nnm.getLength( ); i++) {
    ...
}

Argument

name: DOMString

Name of the node to retrieve.

Java binding

public Node getNamedItem(String name);

Java example

// Check to see if an ID attribute exists
// in this map, and add it if necessary
// nnm was created by getting the attributes
// from an element
if (nnm.getNamedItem("id") == null) {
    // get the document
    Document doc = elem.getOwnerDocument( );
    // create a new attribute Node
    Attr attrID = doc.createAttribute("id");

    // set the attribute value
    attrID.appendChild(doc.createTextNode(makeUniqueID(elem)));
    // ... and add it to the NamedNodeMap
    nnm.setNamedItem(attrID);
}

Arguments

namespaceURI: DOMString

Namespace URI of the node to retrieve.

localName: DOMString

Local name of the node to retrieve.

Java binding

public Node getNamedItemNS(String namespaceURI, String localName);

Argument

index: unsigned long

Zero-based index of the list of the node to return.

Java binding

public Node item(long index);

Java example

// Remove the last attribute from the list
if (nnm.getLength( ) > 0) {
    nnm.removeNamedItem(nnm.item(nnm.getLength()-1).getNodeName( ));
}

Argument

name: DOMString

The nodeName value of the node to be removed.

Exception

NOT_FOUND_ERR

Raised if no node matching the name parameter is found in the map.

Java binding

public Node removeNamedItem(String name) throws DOMException;

Java example

// Remove the ID node attribute
NamedNodeMap nnm = elem.getAttributes( );

if (nnm.removeNamedItem("id") == null) {
    System.err.println("no ID attribute found");
}

Arguments

namespaceURI: DOMString

Namespace URI of the node to retrieve.

localName: DOMString

Local name of the node to retrieve.

Exception

NOT_FOUND_ERR

Raised if no node matching the namespaceURI and localName parameter is found in the map.

Java binding

public Node removeNamedItemNS(String namespaceURI, String localName);

Argument

arg: Node

The Node object to be stored in the map. The values of the namespaceURI and localName properties are used as the lookup key. If another node with identical values for these two properties exists, the new node replaces it.

Exceptions

Java binding

public Node setNamedItemNS(Node arg) throws DOMException;

Java binding

public NamedNodeMap getAttributes( );

// List the attributes of an Element node
NamedNodeMap nnm = doc.getDocumentElement().getAttributes( );

if (nnm != null) {

    for (int i = 0; i < nnm.getLength( ); i++) {
        // print the attribute and value
        System.out.println(nnm.item(i).getNodeName( ) + " = \"" +
                           nnm.item(i).getNodeValue( ) + "\"");
    }
}

Java binding

public NodeList getChildNodes( );

Java example

// List the text contents of an element
NodeList nlChildren = elem.getChildNodes( );
Node ndChild;

for (int iNode = 0; iNode < nlChildren.getLength( ); iNode++) {
    ndChild = nlChildren.item(iNode);

    if (ndChild.getNodeType( ) == Node.TEXT_NODE) {
        System.out.println(ndChild.getNodeValue( ));
    }
}   

Dynamic Tree References   Throughout the DOM, several places return lists or collections of nodes that represent the current state of the document tree. These references are all live; any modifications to the document hierarchy, made by inserting or removing nodes, are reflected in the list immediately.   Whether due to multithreading or unforeseen side effects of procedure calls, the contents of the list being used could change. To reduce the likelihood of difficult-to-find bugs resulting from stale values, request values (such as the length of a list) directly from the NodeList or NamedNodeMap objects. This option is safer than storing values in intermediate variables.

Java binding

public Node getFirstChild( );

Java example

// List the contents of a node
for (Node nd = ndDump.getFirstChild( ); nd != null;
     nd = nd.getNextSibling( )) {
    if (nd.getNodeValue( ) != null) {
        System.out.println(nd.getNodeValue( ));
    }
}

Java binding

public Node getLastChild( );

Java example

// List the value of a node in reverse order
for (Node nd = ndDump.getLastChild( ); nd != null;
     nd = nd.getPreviousSibling( )) {
    if (nd.getNodeValue( ) != null) {
        System.out.println(nd.getNodeValue( ));
    }
}

Java binding

public String getLocalName( );

Java binding

public String getNamespaceURI( );

Java binding

public Node getNextSibling( );

Java example

// List the contents of a node
for (Node nd = ndDump.getFirstChild( ); nd != null;
     nd = nd.getNextSibling( )) {
    if (nd.getNodeValue( ) != null) {
        System.out.println(nd.getNodeValue( ));
    }
}

Java binding

public String getNodeName( );

// Print the document root tag name
Node ndDoc = (Node)doc.getDocumentElement( );
System.out.println("Document root element type: " + ndDoc.getNodeName( ));

Java binding

public short getNodeType( );

Java example

// Check to see if a node is an Element type node
public boolean isElement(Node nd) {
    return nd.getNodeType( ) == Node.ELEMENT_NODE;
}

Exceptions

NO_MODIFICATION_ALLOWED_ERR

Indicates the nodeValue attribute is read-only for this DOM object type.

DOMSTRING_SIZE_ERR

This exception is raised if the value that would be returned is too large to be contained by a DOMString type in the given implementation.

Java bindings

public String getNodeValue( ) throws DOMException;
public void setNodeValue(String nodeValue) throws DOMException;

Java example

// If this node is a text node, make the value lowercase
if (nd.getNodeType( ) == Node.TEXT_NODE) {
    // make it lowercase
    nd.setNodeValue(nd.getNodeValue().toLowerCase( ));
}

Java binding

public Document getOwnerDocument( );

Java example

// Add my two cents
Document doc = elem.getOwnerDocument( );
Text txtAdd = doc.createTextNode("My $.02");
elem.appendChild(txtAdd);

Java binding

Node getParentNode( );

Java example

// Unlink an element from the document tree
elem.getParentNode( ).removeChild(elem);

Exceptions

Java binding

public Node getPreviousSibling( );

Java example

// List the value of a node in reverse order
for (Node nd = ndDump.getLastChild( ); nd != null;
     nd = nd.getPreviousSibling( )) {
    if (nd.getNodeValue( ) != null) {
        System.out.println(nd.getNodeValue( ));
    }
}

Argument

newchild: Node

The node to append. If the node is a DocumentFragment node, the children of newchild are appended in sequence to the end of the node's child list.

Exceptions

HIERARCHY_REQUEST_ERR

Raised if the insert operation violates at least one document structure rule. For instance, the node doesn't allow children or doesn't allow children of the newchild node type. This exception is also raised if the operation creates a circular reference (i.e., it tries to insert a node's parent as a node's child).

WRONG_DOCUMENT_ERR

Raised if the newchild node is created in a different document than that of the new parent node.

NO_MODIFICATION_ALLOWED_ERR

Raised if the new parent node is read-only.

Java binding

public Node appendChild(Node newChild) throws DOMException;

Java example

// Move the first child to the end of the child node list
if (elem.getFirstChild( ) != null) {
    elem.appendChild( elem.getFirstChild( ) );
}

Argument

deep: boolean

If true, child nodes are copied to the cloned node. If false, only the original node is copied.

Java binding

public Node cloneNode(boolean deep);

Java example

// Make a copy of this element and all children
elem.cloneNode(true);

Java binding

public boolean hasAttributes( );

Java binding

public boolean hasChildNodes( );

Arguments

newchild: Node

The new node to insert.

refchild: Node

The node that follows the new node in the child list, or null, if the new node is inserted at the end of the child list.

Exceptions

HIERARCHY_REQUEST_ERR

Raised if the insert operation would violate at least one document structure rule. For instance, the node doesn't allow children or doesn't allow children of the newchild node type. This exception is also raised if the operation creates a circular reference (i.e., it tries to insert a node's parent as a node's child).

WRONG_DOCUMENT_ERR

Raised if the newchild node was created in a document different than that of the new parent node.

NO_MODIFICATION_ALLOWED_ERR

Raised if the new parent node is read-only.

NOT_FOUND_ERR

Raised if the node pointed to by refchild is not a child of the node performing the insert.

Java binding

public Node insertBefore(Node newChild, Node refChild)
               throws DOMException;

Java example

// Insert a new node at the head of the child list of a parent node
ndParent.insertBefore(ndNew, ndParent.getFirstChild( ));

Java binding

public void normalize( );

Argument

oldchild: Node

The node to be removed.

Exceptions

NO_MODIFICATION_ALLOWED_ERR

Raised if the parent node is read-only.

NOT_FOUND_ERR

Raised if the oldchild node is not a child of this node.

Java binding

public Node removeChild(Node oldChild) throws DOMException;

Java example

// Unlink an element and all its children
// from the document tree
elem.getParentNode( ).removeChild(elem);

Arguments

newchild: Node

The node to be inserted.

oldchild: Node

The node being replaced.

Exceptions

Java binding

public Node replaceChild(Node newChild, Node oldChild)
               throws DOMException;

Java example

// Replace an old node with a new one
ndOld.getParentNode( ).replaceChild(ndNew, ndOld);

Java binding

public long getLength( );

Argument

index: unsigned long

Zero-based index into the list of the Node to return.

Java binding

public Node item(long index);

Write exception

NO_MODIFICATION_ALLOWED_ERR

Raised if the node is read-only.

Java bindings

public String getData( );
public void setData(String data) throws DOMException;

Java example

// Check the application's data attribute
if (pi.getTarget( ) == "MY_APPLICATION") {
    // check the data attribute for my own application-specific info
    if (pi.getData( ) == "CHECK_SIBLINGS") {
        // check the siblings
        ...
    }

    pi.setData("SIBLINGS_CHECKED");
}

Java binding

public String getTarget( );

// Check to see if your application is targeted
if (pi.getTarget( ) == "MY_APPLICATION") {
    // do my application-specific processing here
}

Argument

offset (unsigned long)

Zero-based offset where the split occurs.

Exceptions

INDEX_SIZE_ERR

Raised if the offset given is < 0 and >= the length attribute.

NO_MODIFICATION_ALLOWED_ERR

Raised if the element is read-only.

Java binding

public Text splitText(long offset) throws DOMException;

Java example

// Make one Text node
long = doc.createTextNode("This text is split.");

// and split it
Text ndSplit = ndText.splitText(9);