XDA API

XDA

The org.ten60.netkernel.xml.xda package in the ext_xml_core module contains an XPath based API for processing XML. It is a compromise between a low-level XML API and a fully declarative approach to XML processing.

The philosophy of the XDA API is to use XPath expressions as the addressing model for low-level document manipulation operations. This is very convenient for rapid development and allows code to be much more readily modified and maintained when changes to the XML data model are made. In addition the XDA XPath model supports iterators, which allows iterations over a sub-tree to be performed.

IXDAReadOnly

The XDA API is two-part. The IXDAReadOnly interface allows XDA objects to be interogated but not changed. This is very useful and would be nice to see enforced in low-level document models.

Abstraction

The XDA API is abstracted from any underlying document object model. It is initially implemented on top of DOM with the DOMXDA implementation. Other implementations on alternative document models such as JDOM or even SAX (though this might be expensive!) could be developed.

Iterators

Iterators over an XML document can be created. An iterator is generally created with an XPath that targets multiple locations. The iterator then can be used to iterate over those locations. Take care to use relative XPath locations for any operations using the iterator since you should should not operate on Nodes that are part of the iterating set.

The IXDA interface is shown below. In general a method invoked with an XPath location which targets multiple target nodes will be applied to all nodes.

For those who are interested the STM language is a high-level declarative transform language implemented on top of XDA.

JavaDoc

IXDAReadOnly

    /** Evaluate the xpath against the document returning an IXPathResult
     * @exception XPathLocationException throw if the xpath is malformed
     */
    IXPathResult eval(String aTargetXPath) throws XPathLocationException;
    /** Evaluate and xpath against the document returning a boolean result
     * @exception XPathLocationException throw if the xpath is malformed
     */
    boolean isTrue(String aTargetXPath) throws XPathLocationException;
    /** Return the text that is contained at the element located using an XPath
     * @param aTargetXPath the xpath
     * @param aTrim if true trim whitespace from the String
     * @exception XPathLocationException throw if the xpath is malformed or
     * doesn't point to a single unique element
     * @return the string
     */
    String getText(String aTargetXPath, boolean aTrim)
        throws XPathLocationException;
    /** Return an iterator over all elements that match the an XPath
     * @param aTargetXPath the xpath
     * @exception XPathLocationException throw if the xpath is malformed
     * @return the iterator
     */
    IXDAReadOnlyIterator readOnlyIterator(String aTargetXPath)
        throws XPathLocationException;
    /** Serialize part of the document
     * @param aWriter the writer to write the serialized document to
     * @param aTargetXPath the xpath
     * @param indent true if the document should be re-indented
     * @exception XPathLocationException throw if the xpath is malformed or
     * doesn't point to a single unique element
     * @exception IOException throw if the writer cannot be written to
     */
    void serialize(Writer aWriter, String aTargetXPath, boolean indent)
        throws XPathLocationException, IOException;
    /** Serialize the whole document
     * @param aWriter the writer to write the serialized document to
     * @param indent true if the document should be re-indented
     * @exception IOException throw if the writer cannot be written to
     */
    void serialize(Writer aWriter, boolean indent)  throws IOException;

            

IXDA

/** Append fragment of source to this at a specified location or locations
 * @exception XPathLocationException throw if the xpath is malformed, xpaths don't result in well defined element
 * @exception XDOIncompatibilityException throw if the implementation doesn't support this operation
 */
void append(IXDAReadOnly aSource, String aSourceXPath, String aTargetXPath)
    throws XPathLocationException, XDOIncompatibilityException;
/** Insert fragment of source to this before specified location or locations
 * @exception XPathLocationException throw if the xpath is malformed, xpaths don't result in well defined element
 * @exception XDOIncompatibilityException throw if the implementation doesn't support this operation
 */
void insertBefore(IXDAReadOnly aSource, String aSourceXPath,  String aTargetXPath)
    throws XPathLocationException, XDOIncompatibilityException;
/** Insert fragment of source to this after specified location or locations
 * @exception XPathLocationException throw if the xpath is malformed, xpaths don't result in well defined element
 * @exception XDOIncompatibilityException throw if the implementation doesn't support this operation
 */
void insertAfter(IXDAReadOnly aSource, String aSourceXPath,  String aTargetXPath)
    throws XPathLocationException, XDOIncompatibilityException;
/** Apply namespace to target location or locations
 * @param prefix prefix for the namespace
 * @param uri uri for the namespace
 * @exception XPathLocationException throw if the xpath is malformed, xpaths don't result in well defined element
 * @exception XDOIncompatibilityException throw if the implementation doesn't support this operation
 */
void applyNS(String aTargetXPath, String prefix, String uri)
    throws XPathLocationException, XDOIncompatibilityException;
/** Remove namespace from target location or locations
 * @param prefix prefix for the namespace
 * @exception XPathLocationException throw if the xpath is malformed, xpaths don't result in well defined element
 * @exception XDOIncompatibilityException throw if the implementation doesn't support this operation
 */
void removeNS(String aTargetXPath, String prefix) throws XPathLocationException, XDOIncompatibilityException;
/** Rename elements at target location or locations
 * @param name the new element name
 * @exception XPathLocationException throw if the xpath is malformed, xpaths don't result in well defined element
 * @exception XDOIncompatibilityException throw if the implementation doesn't support this operation
 */
void rename(String aTargetXPath, String name) throws XPathLocationException, XDOIncompatibilityException;
/** Delete elements at target location or locations
 * @exception XPathLocationException throw if the xpath is malformed, xpaths don't result in well defined element
 * @exception XDOIncompatibilityException throw if the implementation doesn't support this operation
 */
void delete(String aTargetXPath) throws XPathLocationException, XDOIncompatibilityException;
/** Replace fragments of this with fragments from source at specified location or locations
 * @exception XPathLocationException throw if the xpath is malformed, xpaths don't result in well defined element
 * @exception XDOIncompatibilityException throw if the implementation doesn't support this operation
 */
void replace(IXDAReadOnly aSource, String aSourceXPath, String aTargetXPath)
    throws XPathLocationException, XDOIncompatibilityException;
/** Replace fragments of this with given text at specified location or locations
 * @param aText the text to place at locations
 * @exception XPathLocationException throw if the xpath is malformed, xpaths don't result in well defined element
 * @exception XDOIncompatibilityException throw if the implementation doesn't support this operation
 */
void replaceByText(String aTargetXPath, String aText)  throws XPathLocationException, XDOIncompatibilityException;
/** Moves a fragment from one location in this to another
 * @exception XPathLocationException throw if the xpath is malformed, xpaths don't result in well defined element
 * @exception XDOIncompatibilityException throw if the implementation doesn't support this operation
 */
void move(String aSourceXPath, String aTargetXPath) throws XPathLocationException, XDOIncompatibilityException;
/** Sets the text of the element or elements at the target location of this
 * @exception XPathLocationException throw if the xpath is malformed, xpaths don't result in well defined element
 * @exception XDOIncompatibilityException throw if the implementation doesn't support this operation
 */
void setText(String aTargetXPath, String aText) throws XPathLocationException, XDOIncompatibilityException;
/** Builds and appends a chain of elements to a location or locations within this
 * @param aNewRelativeXPath a simple xpath of form <code>a/b/c</code> to name a chain of elements
 * to append.
 * @param aOptionalValue a text value to assign to the leaf node, may be null
 * @exception XPathLocationException throw if the xpath is malformed, xpaths don't result in well defined element
 * @exception XDOIncompatibilityException throw if the implementation doesn't support this operation
 */
void appendPath(String aTargetXPath, String aNewRelativeXPath, String aOptionalValue)
    throws XPathLocationException, XDOIncompatibilityException;
/** Return an iterator over all elements match the xpath in this
 * @exception XPathLocationException throw if the xpath is malformed, xpaths don't result in well defined element
 */
IXDAIterator iterator(String aTargetXPath) throws XPathLocationException;