/* * Copyright 2001-2005 (C) MetaStuff, Ltd. All Rights Reserved. * * This software is open source. * See the bottom of this file for the licence. */ package org.dom4j; import java.io.IOException; import java.io.Writer; import java.util.List; /** *

* Node defines the polymorphic behavior for all XML nodes in a * dom4j tree. *

* *

* A node can be output as its XML format, can be detached from its position in * a document and can have XPath expressions evaluated on itself. *

* *

* A node may optionally support the parent relationship and may be read only. *

* * @author James Strachan * @version $Revision$ * * @see #supportsParent * @see #isReadOnly */ public interface Node extends Cloneable { // W3C DOM complient node type codes /** Matches Element nodes */ short ANY_NODE = 0; /** Matches Element nodes */ short ELEMENT_NODE = 1; /** Matches elements nodes */ short ATTRIBUTE_NODE = 2; /** Matches elements nodes */ short TEXT_NODE = 3; /** Matches elements nodes */ short CDATA_SECTION_NODE = 4; /** Matches elements nodes */ short ENTITY_REFERENCE_NODE = 5; /** Matches elements nodes */ // public static final short ENTITY_NODE = 6; /** Matches ProcessingInstruction */ short PROCESSING_INSTRUCTION_NODE = 7; /** Matches Comments nodes */ short COMMENT_NODE = 8; /** Matches Document nodes */ short DOCUMENT_NODE = 9; /** Matches DocumentType nodes */ short DOCUMENT_TYPE_NODE = 10; // public static final short DOCUMENT_FRAGMENT_NODE = 11; // public static final short NOTATION_NODE = 12; /** Matchs a Namespace Node - NOTE this differs from DOM */ // XXXX: ???? short NAMESPACE_NODE = 13; /** Does not match any valid node */ short UNKNOWN_NODE = 14; /** The maximum number of node types for sizing purposes */ short MAX_NODE_TYPE = 14; /** *

* supportsParent returns true if this node supports the * parent relationship. *

* *

* Some XML tree implementations are singly linked and only support downward * navigation through children relationships. The default case is that both * parent and children relationships are supported though for memory and * performance reasons the parent relationship may not be supported. *

* * @return true if this node supports the parent relationship or false it is * not supported */ boolean supportsParent(); /** *

* getParent returns the parent Element if * this node supports the parent relationship or null if it is the root * element or does not support the parent relationship. *

* *

* This method is an optional feature and may not be supported for all * Node implementations. *

* * @return the parent of this node or null if it is the root of the tree or * the parent relationship is not supported. */ Element getParent(); /** *

* setParent sets the parent relationship of this node if the * parent relationship is supported or does nothing if the parent * relationship is not supported. *

* *

* This method should only be called from inside an Element * implementation method and is not intended for general use. *

* * @param parent * is the new parent of this node. */ void setParent(Element parent); /** *

* getDocument returns the Document that this * Node is part of if this node supports the parent * relationship. *

* *

* This method is an optional feature and may not be supported for all * Node implementations. *

* * @return the document of this node or null if this feature is not * supported or the node is not associated with a * Document */ Document getDocument(); /** *

* setDocument sets the document of this node if the parent * relationship is supported or does nothing if the parent relationship is * not supported. *

* *

* This method should only be called from inside a Document * implementation method and is not intended for general use. *

* * @param document * is the new document of this node. */ void setDocument(Document document); /** *

* isReadOnly returns true if this node is read only and * cannot be modified. Any attempt to modify a read-only Node * will result in an UnsupportedOperationException being * thrown. *

* * @return true if this Node is read only and cannot be * modified otherwise false. */ boolean isReadOnly(); /** *

* hasContent returns true if this node is a Branch (either * an Element or a Document) and it contains at least one content node such * as a child Element or Text node. *

* * @return true if this Node is a Branch with a nodeCount() * of one or more. */ boolean hasContent(); /** *

* getName returns the name of this node. This is the XML * local name of the element, attribute, entity or processing instruction. * For CDATA and Text nodes this method will return null. *

* * @return the XML name of this node */ String getName(); /** *

* Sets the text data of this node or this method will throw an * UnsupportedOperationException if it is read-only. *

* * @param name * is the new name of this node */ void setName(String name); /** *

* Returns the text of this node. *

* * @return the text for this node. */ String getText(); /** *

* Sets the text data of this node or this method will throw an * UnsupportedOperationException if it is read-only. *

* * @param text * is the new textual value of this node */ void setText(String text); /** * Returns the XPath string-value of this node. The behaviour of this method * is defined in the XPath * specification . * * @return the text from all the child Text and Element nodes appended * together. */ String getStringValue(); /** *

* Returns the XPath expression which will return a node set containing the * given node such as /a/b/@c. No indexing will be used to restrict the * path if multiple elements with the same name occur on the path. *

* * @return the XPath expression which will return a nodeset containing at * least this node. */ String getPath(); /** * Returns the relative XPath expression which will return a node set * containing the given node such as a/b/@c. No indexing will be used to * restrict the path if multiple elements with the same name occur on the * path. * * @param context * is the parent context from which the relative path should * start. If the context is null or the context is not an * ancestor of this node then the path will be absolute and start * from the document and so begin with the '/' character. * * @return the XPath expression relative to the given context which will * return a nodeset containing at least this node. */ String getPath(Element context); /** *

* Returns the XPath expression which will return a nodeset of one node * which is the current node. This method will use the XPath index operator * to restrict the path if multiple elements with the same name occur on the * path. *

* * @return the XPath expression which will return a nodeset containing just * this node. */ String getUniquePath(); /** *

* Returns the relative unique XPath expression from the given context which * will return a nodeset of one node which is the current node. This method * will use the XPath index operator to restrict the path if multiple * elements with the same name occur on the path. *

* * @param context * is the parent context from which the path should start. If the * context is null or the context is not an ancestor of this node * then the path will start from the document and so begin with * the '/' character. * * @return the XPath expression relative to the given context which will * return a nodeset containing just this node. */ String getUniquePath(Element context); /** *

* asXML returns the textual XML representation of this node. *

* * @return the XML representation of this node */ String asXML(); /** *

* write writes this node as the default XML notation for * this node. If you wish to control the XML output (such as for pretty * printing, changing the indentation policy etc.) then please use {@link * org.dom4j.io.XMLWriter} or its derivations. *

* * @param writer * is the Writer to output the XML to * * @throws IOException * DOCUMENT ME! */ void write(Writer writer) throws IOException; /** * Returns the code according to the type of node. This makes processing * nodes polymorphically much easier as the switch statement can be used * instead of multiple if (instanceof) statements. * * @return a W3C DOM complient code for the node type such as ELEMENT_NODE * or ATTRIBUTE_NODE */ short getNodeType(); /** * DOCUMENT ME! * * @return the name of the type of node such as "Document", "Element", * "Attribute" or "Text" */ String getNodeTypeName(); /** *

* Removes this node from its parent if there is one. If this node is the * root element of a document then it is removed from the document as well. *

* *

* This method is useful if you want to remove a node from its source * document and add it to another document. For example *

* Node node = ...; Element someOtherElement = ...; * someOtherElement.add( node.detach() ); * * @return the node that has been removed from its parent node if any and * its document if any. */ Node detach(); /** *

* selectNodes evaluates an XPath expression and returns the * result as a List of Node instances or * String instances depending on the XPath expression. *

* * @param xpathExpression * is the XPath expression to be evaluated * * @return the list of Node or String * instances depending on the XPath expression */ List selectNodes(String xpathExpression); /** *

* selectObject evaluates an XPath expression and returns the * result as an {@link Object}. The object returned can either be a {@link * List} of one or more {@link Node}instances or a scalar object like a * {@link String}or a {@link Number}instance depending on the XPath * expression. *

* * @param xpathExpression * is the XPath expression to be evaluated * * @return the value of the XPath expression as a {@link List}of {@link * Node} instances, a {@link String}or a {@link Number}instance * depending on the XPath expression. */ Object selectObject(String xpathExpression); /** *

* selectNodes evaluates an XPath expression then sorts the * results using a secondary XPath expression Returns a sorted * List of Node instances. *

* * @param xpathExpression * is the XPath expression to be evaluated * @param comparisonXPathExpression * is the XPath expression used to compare the results by for * sorting * * @return the list of Node instances sorted by the * comparisonXPathExpression */ List selectNodes(String xpathExpression, String comparisonXPathExpression); /** *

* selectNodes evaluates an XPath expression then sorts the * results using a secondary XPath expression Returns a sorted * List of Node instances. *

* * @param xpathExpression * is the XPath expression to be evaluated * @param comparisonXPathExpression * is the XPath expression used to compare the results by for * sorting * @param removeDuplicates * if this parameter is true then duplicate values (using the * comparisonXPathExpression) are removed from the result List. * * @return the list of Node instances sorted by the * comparisonXPathExpression */ List selectNodes(String xpathExpression, String comparisonXPathExpression, boolean removeDuplicates); /** *

* selectSingleNode evaluates an XPath expression and returns * the result as a single Node instance. *

* * @param xpathExpression * is the XPath expression to be evaluated * * @return the Node matching the XPath expression */ Node selectSingleNode(String xpathExpression); /** *

* valueOf evaluates an XPath expression and returns the * textual representation of the results the XPath string-value of this * node. The string-value for a given node type is defined in the XPath specification . *

* * @param xpathExpression * is the XPath expression to be evaluated * * @return the string-value representation of the results of the XPath * expression */ String valueOf(String xpathExpression); /** *

* numberValueOf evaluates an XPath expression and returns * the numeric value of the XPath expression if the XPath expression results * in a number, or null if the result is not a number. *

* * @param xpathExpression * is the XPath expression to be evaluated * * @return the numeric result of the XPath expression or null if the result * is not a number. */ Number numberValueOf(String xpathExpression); /** *

* matches returns true if evaluating the given XPath * expression on this node returns a non-empty node set containing this * node. *

* *

* This method does not behave like the <xsl:if> element - if you want * that behaviour, to evaluate if an XPath expression matches something, * then you can use the following code to be equivalent... *

* if ( node.selectSingleNode( "/some/path" ) != nulll ) * * @param xpathExpression * is an XPath expression * * @return true if this node is returned by the given XPath expression */ boolean matches(String xpathExpression); /** *

* createXPath creates an XPath object for the given * xpathExpression. The XPath object allows the variable context to be * specified. *

* * @param xpathExpression * is the XPath expression to be evaluated * * @return an XPath object represeting the given expression * * @throws InvalidXPathException * if the XPath expression is invalid */ XPath createXPath(String xpathExpression) throws InvalidXPathException; /** *

* asXPathResult returns a version of this node which is * capable of being an XPath result. The result of an XPath expression * should always support the parent relationship, whether the original XML * tree was singly or doubly linked. If the node does not support the parent * relationship then a new node will be created which is linked to its * parent and returned. *

* * @param parent * DOCUMENT ME! * * @return a Node which supports the parent relationship */ Node asXPathResult(Element parent); /** *

* accept is the method used in the Visitor Pattern. *

* * @param visitor * is the visitor in the Visitor Pattern */ void accept(Visitor visitor); /** *

* clone will return a deep clone or if this node is * read-only then clone will return the same instance. *

* * @return a deep clone of myself or myself if I am read only. */ Object clone(); } /* * Redistribution and use of this software and associated documentation * ("Software"), with or without modification, are permitted provided that the * following conditions are met: * * 1. Redistributions of source code must retain copyright statements and * notices. Redistributions must also contain a copy of this document. * * 2. Redistributions in binary form must reproduce the above copyright notice, * this list of conditions and the following disclaimer in the documentation * and/or other materials provided with the distribution. * * 3. The name "DOM4J" must not be used to endorse or promote products derived * from this Software without prior written permission of MetaStuff, Ltd. For * written permission, please contact dom4j-info@metastuff.com. * * 4. Products derived from this Software may not be called "DOM4J" nor may * "DOM4J" appear in their names without prior written permission of MetaStuff, * Ltd. DOM4J is a registered trademark of MetaStuff, Ltd. * * 5. Due credit should be given to the DOM4J Project - http://www.dom4j.org * * THIS SOFTWARE IS PROVIDED BY METASTUFF, LTD. AND CONTRIBUTORS ``AS IS'' AND * ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE * ARE DISCLAIMED. IN NO EVENT SHALL METASTUFF, LTD. OR ITS CONTRIBUTORS BE * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE * POSSIBILITY OF SUCH DAMAGE. * * Copyright 2001-2005 (C) MetaStuff, Ltd. All Rights Reserved. */