Java tutorial
/* * 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; /** * <code>Node</code> 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 <a href="mailto:jstrachan@apache.org">James Strachan </a> * @version $Revision: 1.31 $ * * @see #supportsParent * @see #isReadOnly */ @SuppressWarnings("unused") 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; /** * <p> * <code>supportsParent</code> returns true if this node supports the * parent relationship. * </p> * * <p> * 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. * </p> * * @return true if this node supports the parent relationship or false it is * not supported */ boolean supportsParent(); /** * <p> * <code>getParent</code> returns the parent <code>Element</code> if * this node supports the parent relationship or null if it is the root * element or does not support the parent relationship. * </p> * * <p> * This method is an optional feature and may not be supported for all * <code>Node</code> implementations. * </p> * * @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(); /** * <p> * <code>setParent</code> sets the parent relationship of this node if the * parent relationship is supported or does nothing if the parent * relationship is not supported. * </p> * * <p> * This method should only be called from inside an <code>Element</code> * implementation method and is not intended for general use. * </p> * * @param parent * is the new parent of this node. */ void setParent(Element parent); /** * <p> * <code>getDocument</code> returns the <code>Document</code> that this * <code>Node</code> is part of if this node supports the parent * relationship. * </p> * * <p> * This method is an optional feature and may not be supported for all * <code>Node</code> implementations. * </p> * * @return the document of this node or null if this feature is not * supported or the node is not associated with a * <code>Document</code> */ Document getDocument(); /** * <p> * <code>setDocument</code> sets the document of this node if the parent * relationship is supported or does nothing if the parent relationship is * not supported. * </p> * * <p> * This method should only be called from inside a <code>Document</code> * implementation method and is not intended for general use. * </p> * * @param document * is the new document of this node. */ void setDocument(Document document); /** * <p> * <code>isReadOnly</code> returns true if this node is read only and * cannot be modified. Any attempt to modify a read-only <code>Node</code> * will result in an <code>UnsupportedOperationException</code> being * thrown. * </p> * * @return true if this <code>Node</code> is read only and cannot be * modified otherwise false. */ boolean isReadOnly(); /** * <p> * <code>hasContent</code> 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. * </p> * * @return true if this <code>Node</code> is a Branch with a nodeCount() * of one or more. */ boolean hasContent(); /** * <p> * <code>getName</code> 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. * </p> * * @return the XML name of this node */ String getName(); /** * <p> * Sets the text data of this node or this method will throw an * <code>UnsupportedOperationException</code> if it is read-only. * </p> * * @param name * is the new name of this node */ void setName(String name); /** * <p> * Returns the text of this node. * </p> * * @return the text for this node. */ String getText(); /** * <p> * Sets the text data of this node or this method will throw an * <code>UnsupportedOperationException</code> if it is read-only. * </p> * * @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 <a href="http://www.w3.org/TR/xpath">XPath * specification </a>. * * @return the text from all the child Text and Element nodes appended * together. */ String getStringValue(); /** * <p> * 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. * </p> * * @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); /** * <p> * 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. * </p> * * @return the XPath expression which will return a nodeset containing just * this node. */ String getUniquePath(); /** * <p> * 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. * </p> * * @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); /** * <p> * <code>asXML</code> returns the textual XML representation of this node. * </p> * * @return the XML representation of this node */ String asXML(); /** * <p> * <code>write</code> 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. * </p> * * @param writer * is the <code>Writer</code> 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(); /** * <p> * 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. * </p> * * <p> * This method is useful if you want to remove a node from its source * document and add it to another document. For example * </p> * <code> Node node = ...; Element someOtherElement = ...; * someOtherElement.add( node.detach() ); </code> * * @return the node that has been removed from its parent node if any and * its document if any. */ Node detach(); /** * <p> * <code>selectNodes</code> evaluates an XPath expression and returns the * result as a <code>List</code> of <code>Node</code> instances or * <code>String</code> instances depending on the XPath expression. * </p> * * @param xpathExpression * is the XPath expression to be evaluated * * @return the list of <code>Node</code> or <code>String</code> * instances depending on the XPath expression */ List<Node> selectNodes(String xpathExpression); /** * <p> * <code>selectObject</code> 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. * </p> * * @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); /** * <p> * <code>selectNodes</code> evaluates an XPath expression then sorts the * results using a secondary XPath expression Returns a sorted * <code>List</code> of <code>Node</code> instances. * </p> * * @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 <code>Node</code> instances sorted by the * comparisonXPathExpression */ List<Node> selectNodes(String xpathExpression, String comparisonXPathExpression); /** * <p> * <code>selectNodes</code> evaluates an XPath expression then sorts the * results using a secondary XPath expression Returns a sorted * <code>List</code> of <code>Node</code> instances. * </p> * * @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 <code>Node</code> instances sorted by the * comparisonXPathExpression */ List<Node> selectNodes(String xpathExpression, String comparisonXPathExpression, boolean removeDuplicates); /** * <p> * <code>selectSingleNode</code> evaluates an XPath expression and returns * the result as a single <code>Node</code> instance. * </p> * * @param xpathExpression * is the XPath expression to be evaluated * * @return the <code>Node</code> matching the XPath expression */ Node selectSingleNode(String xpathExpression); /** * <p> * <code>valueOf</code> 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 <a * href="http://www.w3.org/TR/xpath">XPath specification </a>. * </p> * * @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); /** * <p> * <code>numberValueOf</code> 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. * </p> * * @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); /** * <p> * <code>matches</code> returns true if evaluating the given XPath * expression on this node returns a non-empty node set containing this * node. * </p> * * <p> * 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... * </p> * <code>if ( node.selectSingleNode( "/some/path" ) != nulll )</code> * * @param xpathExpression * is an XPath expression * * @return true if this node is returned by the given XPath expression */ boolean matches(String xpathExpression); /** * <p> * <code>createXPath</code> creates an XPath object for the given * xpathExpression. The XPath object allows the variable context to be * specified. * </p> * * @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; /** * <p> * <code>asXPathResult</code> 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. * </p> * * @param parent * DOCUMENT ME! * * @return a <code>Node</code> which supports the parent relationship */ Node asXPathResult(Element parent); /** * <p> * <code>accept</code> is the method used in the Visitor Pattern. * </p> * * @param visitor * is the visitor in the Visitor Pattern */ void accept(Visitor visitor); /** * <p> * <code>clone</code> will return a deep clone or if this node is * read-only then clone will return the same instance. * </p> * * @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. */