node.java

Java的面向对象数据库系统的源代码

/*
 * Copyright 2001 (C) MetaStuff, Ltd. All Rights Reserved.
 *
 * This software is open source.
 * See the bottom of this file for the licence.
 *
 * $Id: Node.java,v 1.3 2003/06/10 16:18:32 per_nyfelt Exp $
 */

package org.dom4j;

import java.io.IOException;
import java.io.Writer;
import java.util.List;

/** <p><code>Node</code> defines the polymorphic behavior
  * for all XML nodes in a dom4j tree.</p>
  *
  * <p>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.</p>
  *
  * <p>A node may optionally support the parent relationship and may be
  * read only.</p>
  *
  * @see #supportsParent
  * @see #isReadOnly
  *
  * @author <a href="mailto:[e-mail]">James Strachan</a>
  * @version $Revision: 1.3 $
  */
public interface Node extends Cloneable {

    // W3C DOM complient node type codes

    /** Matches Element nodes */
    public static final short ANY_NODE = 0;
    /** Matches Element nodes */
    public static final short ELEMENT_NODE = 1;
    /** Matches elements nodes */
    public static final short ATTRIBUTE_NODE = 2;
    /** Matches elements nodes */
    public static final short TEXT_NODE = 3;
    /** Matches elements nodes */
    public static final short CDATA_SECTION_NODE = 4;
    /** Matches elements nodes */
    public static final short ENTITY_REFERENCE_NODE = 5;
    /** Matches elements nodes */
    //public static final short ENTITY_NODE = 6;
    /** Matches ProcessingInstruction */
    public static final short PROCESSING_INSTRUCTION_NODE = 7;
    /** Matches Comments nodes */
    public static final short COMMENT_NODE = 8;
    /** Matches Document nodes */
    public static final short DOCUMENT_NODE = 9;
    /** Matches DocumentType nodes */
    public static final 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: ????
    public static final short NAMESPACE_NODE = 13;

    /** Does not match any valid node */
    public static final short UNKNOWN_NODE = 14;

    /** The maximum number of node types for sizing purposes */
    public static final 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
      */
    public 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.
      */
    public 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.
      */
    public 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>
      */
    public 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.
      */
    public 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.
      */
    public 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.
      */
    public 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
      */
    public 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
     */
    public void setName(String name);

    /** <p>Returns the text of this node.</p>
      *
      * @return the text for this node.
      */
    public 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
     */
    public 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.
      */
    public 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.
      */
    public String getPath();

    /** <p>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.
      */
    public 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.
      */
    public 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.