Functions for Manipulating XML

When writing ECMAScript to manipulate XML, you have access to several member functions designed to make the task easier. This topic describes the functions available with the extended ECMAScript available with WebLogic Workshop.

There may be cases when an element name conflicts with the name of a function listed in this topic. When that occurs, use syntax like that shown in the following example. In this example, the conflicting element name is preceding with a :: (double-colon).

    /*
     * Return the first <parent> element.
     * This avoids a conflict with the parent function.
     */
    var firstParent = xmlFamilies.kid.::parent[0];

# ECMAScript Functions for XML

Function | Description
--- | ---
xmlElement.appendChild(newChild) | Inserts a new child node after the existing children of the XML value.
xmlElement.attribute(attributeName) | Returns the value of the specified attribute.
xmlElement.attributes() | Returns a list of attributes for the specified element.
xmlElement.child(childIndex) | Returns the XML at the 0-based ordinal position specified by childIndex.
xmlElement.childIndex() | Returns the 0-based ordinal position of the XML value within its parent.
xmlElement.children() | Returns a list of the element's children.
xmlElement.copy() | Returns a copy of the specified element.
xmlElement.domNode() | Returns a org.w3c.dom.Node representation of xmlElement.
xmlElement.innerXML(newContent) | Replaces the entire contents of the XML value with new content.
xmlElement.length | Returns the length of a list XML elements.
xmlElement.namespaceURI() | Returns a string representing the namespace URI associated with xmlElement.
xmlElement.parent() | Returns the parent of the element.
xmlElement.prependChild(newChild) | Inserts a new child node before the existing children of the XML value.
xmlElement.tagName() | Returns the name of the element tag.
xmlElement.thisXML | Specifies the current XML, such as XML returned from an expression.
xmlElement.text() | Returns a string containing the value of all XML properties of xmlElement that are of type string.
xmlElement.toString() | Returns the element and its content as a string.
xmlElement.toXMLString() | Returns an XML encoded string representation of xmlElement.
xmlElement.xpath(xPathExpression) | Evaluates the XPath expression using the XML value as the context node.

Each of the functions listed in this topic is illustrated with an example based on the following XML variable.

    /* Declare an XML variable with a literal XML value. */
    var xmlEmployees = <employees>
        <employee id="111111111">
            <firstname>John</firstname>
            <lastname>Walton</lastname>
            <age>25</age>
        </employee>
        <employee id="222222222">
            <firstname>Sue</firstname>
            <lastname>Day</lastname>
            <age>32</age>
        </employee>
    </employees>;

# xmlElement.appendChild(newChild)

Inserts a new child element (specified by newChild) after the existing children of xmlElement.

The following example adds a <hobby> element to the end of the element assigned to xmlSue.

    var xmlSue = xmlEmployees..employee.(firstname == "Sue");
    xmlSue.appendChild(<hobby>snorkeling</hobby>);

# xmlElement.attribute(attributeName)

Returns the value of attributeName.

The following example returns a string containing Sue's ID number.

    var xmlEmployeeID = xmlEmployees.employees.employee.(firstname == "Sue").attribute("id");

Note that the attribute() function is an alternative to the .@ operator. Because you may pass it a variable rather than a literal value, the attribute() function is useful when the attribute in question is unknown until run time.

For more information about the .@ operator, see Accessing Attributes with the .@ Operator.

# xmlElement.attributes()

Returns a list of the attributes for xmlElement.

The following example returns the attributes for the <employee> element where the <name> value is "Sue"; its return value is "id".

    var suesAttributes = xmlEmployees..employee.(firstname == "Sue").attributes();

# xmlElement.child(childIndex)

Returns the XML at the 0-based ordinal position specified by childIndex.

The second line of code in the following example returns an XML type containing the information about Sue.

    var secondEmployeeIndex = xmlEmployees..employee.(firstname == "Sue").childIndex();
    var secondEmployee = xmlEmployees.employees.child(secondEmployeeIndex);

# xmlElement.childIndex()

Returns the ordinal position (within its parent) of xmlElement.

The following example returns the index of the <employee> element where the <name> element value is "John". Returns "0".

    var johnIndex = xmlEmployees..employee.(firstname == "John").childIndex();

Note that when the expression to the left of childIndex returns multiple items, childIndex returns -1, as in the following example:

    var nameIndex = xmlEmployees..employee.name.childIndex();

# xmlElement.children()

Returns an XMLList containing all of the children of xmlElement.

The following example returns the child elements of the first employee element in xmlEmployees. It returns "John, Walton, 25".

    var xmlEmps = xmlEmployees..employee[0].children();

# xmlElement.copy()

Returns a deep copy of xmlElement.

The following example adds data about Gladys, a new employee, to a list that already includes John and Sue.

Result: The XML held by newEmployee is added to the list of employees.

    /* Create a new variable from data from the first employee in the list. */
    var newEmployee = xmlEmployees..employee[0].copy();
    /* Assigned new values to the copy. */
    newEmployee.@id = "555555555";
    newEmployee.firstname = "Gladys";
    newEmployee.lastname = "Cravits";
    newEmployee.age = "43";
    /* Append the copy to the list of employees. */
    xmlEmployees..employees += newEmployee;

# xmlElement.domNode()

Returns a org.w3c.dom.Node representation of xmlElement.

A node is the primary data type for the W3C Document Object Model (DOM). The DOM defines a logical structure through which to access XML (and HTML) documents. In the DOM, a node represents a single node in the document tree. Xerces is a Java implementation of the DOM available through the Apache Project.

While the ECMAScript extensions offered with WebLogic Workshop are an alternative to accessing XML via the DOM, the domNode function is provided as a convenient way to create a DOM node. This might be useful, for example, if the script should return a DOM node.

For more information about the Node interface, see the Node Interface topic of the Apache Xalan documentation.

# xmlElement.innerXML(newContent)

Replaces the entire contents of xmlElement with newContent.

Note that this is not the same as reassigning the variable. In the example below, the root element represented by the variable (<employee>) remains intact, but its contents are replaced.

The following example replaces the entire contents of xmlSue with the specified elements. This effectively replaces Sue with Gladys, while keeping Sue's ID number.

    var xmlSue = xmlEmployees..employee.(firstname == "Sue");
    xmlSue.innerXML(<><firstname>Gladys</firstname><lastname>Cravits</lastname><age>43</age></>);

# xmlList.length

Returns the number of items in the list represented by xmlList.

For more on the XMLList data type, see Creating and Using XML Variables.

The following example returns the number of <employee> elements in xmlEmployees. Returns the number 2.

    var numberOfEmployees = xmlEmployees.length;

# xmlElement.namespaceURI()

Returns a string representing the namespace URI associated with xmlElement.

The following example returns the namespace URI associated with a SOAP message. Returns a string containing "http://schemas.xmlsoap.org/soap/envelope/”.

    var xmlStockMessage = <Envelope xmlns ="http://schemas.xmlsoap.org/soap/envelope/"
        encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
        <Body>
            <m:GetLastTradePrice xmlns:m="http://mycompany.com/stocks">
                <symbol>DIS</symbol>
            </m:GetLastTradePrice>
        </Body>
    </Envelope>;
    var ns = xmlStockMessage.Envelope.Body.namespaceURI();

# xmlElement.parent()

Returns the parent of xmlElement.

The following example find the employees whose age is under 30, then uses the parent function to return the entire element containing that person's data. It returns an XML type the element containing John's information.

    var ns = xmlEmployees..employee.(age <= "30").age;
    var emp = ns.parent();

# xmlElement.prependChild(newChild)

Inserts newChild before the existing children of xmlElement.

The following example adds a <prefix> element to the beginning of the element assigned to xmlSue. This code adds <prefix>Mr.</prefix> as the first child of the <employee> node containing information about John.

    var xmlJohn = xmlEmployees..employee.(firstname == "John");

    xmlJohn.prependChild(<prefix>Mr.</prefix>);

# xmlElement.tagName()

Returns the name of the tag for xmlElement.

The following example returns the name of the first child element of the first <employee> element. It returns a string containing "firstname".

    var childTags = xmlEmployees..employee[0].children();

    var firstChildTag = childTags[0].tagName();

# xmlElement.thisXML

Specifies the current XML, such as XML returned from an expression.

For more information, see Specifying the Current XML with the thisXML Property.

# xmlElement.text()

Returns a string containing the value of all XML properties of xmlElement that are of type string.

The following example finds the second child of the second <employee> element and returns its content. It returns a string containing "Sue".

    var ageXML = xmlEmployees..employee[1][1].text();

# xmlElement.toString()

Returns the XML and its contents as a string.

The following example returns a string representation of the first <employee> element.

    var johnText = xmlEmployees..employee[0].toString();

# xmlElement.toXMLString()

Returns an XML encoded string representation of xmlElement.

The following example returns a string representation of the first <employee> element.

    var johnText = xmlEmployees..employee[0].toXMLString();

# xmlElement.xpath(xPathExpression)

Evaluates the XPath expression (specified by xpathExpression) using xmlElement as the context node.

The following example uses an XPath expression to return the <employee> element where the <firstname> element value is "Sue". It returns an XMLList containing the element.

Result: Returns the <employee> element containing information about Sue.

    var xmlSue = xmlEmployees.xpath("//employee[firstname='Sue']")

Related Topics

Handling XML with ECMAScript Extensions

Summary of ECMAScript Language Extensions