element.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: Element.java,v 1.5 2003/11/02 17:58:36 per_nyfelt Exp $
 */

package org.dom4j;

import java.util.Iterator;
import java.util.List;
import java.util.Map;

/** <p><code>Element</code> interface defines an XML element.
  * An element can have declared namespaces, attributes, child nodes and
  * textual content.</p>
  *
  * <p>Some of this interface is optional.
  * Some implementations may be read-only and not support being modified.
  * Some implementations may not support the parent relationship and methods
  * such as {@link #getParent} or {@link #getDocument}.</p>
  *
  *
  * @author <a href="mailto:[e-mail]">James Strachan</a>
  * @version $Revision: 1.5 $
  */
public interface Element extends Branch {

    // Name and namespace related methods
    //-------------------------------------------------------------------------

    /** <p>Returns the <code>QName</code> of this element which represents
      * the local name, the qualified name and the <code>Namespace</code>.</p>
      *
      * @return the <code>QName</code> associated with this element
      */
    public QName getQName();

    /** <p>Sets the <code>QName</code> of this element which represents
      * the local name, the qualified name and the <code>Namespace</code>.</p>
      *
      * @param qname is the <code>QName</code> to be associated with this element
      */
    public void setQName(QName qname);

    /** <p>Returns the <code>Namespace</code> of this element if one exists
      * otherwise <code>AbstractNamespace.NO_NAMESPACE</code> is returned.</p>
      *
      * @return the <code>Namespace</code> associated with this element
      */
    public Namespace getNamespace();



    /** <p>Returns the <code>QName</code> for the given qualified name, using
      * the namespace URI in scope for the given prefix of the qualified name
      * or the default namespace if the qualified name has no prefix.</p>
      *
      * @return the <code>QName</code> for the given qualified name
      */
    public QName getQName(String qualifiedName);


    /** <p>Returns the <code>Namespace</code> which is mapped to the given
      * prefix or null if it could not be found.</p>
      *
      * @return the <code>Namespace</code> associated with the given prefix
      */
    public Namespace getNamespaceForPrefix(String prefix);

    /** <p>Returns the <code>Namespace</code> which is mapped to the given
      * URI or null if it could not be found.</p>
      *
      * @return the <code>Namespace</code> associated with the given URI
      */
    public Namespace getNamespaceForURI(String uri);

    /** <p>Returns the namespace prefix of this element if one exists
      * otherwise an empty <code>String</code> is returned.</p>
      *
      * @return the prefix of the <code>Namespace</code> of this element
      * or an empty <code>String</code>
      */
    public String getNamespacePrefix();

    /** <p>Returns the URI mapped to the namespace of this element
      * if one exists otherwise an empty <code>String</code> is returned.</p>
      *
      * @return the URI for the <code>Namespace</code> of this element
      * or an empty <code>String</code>
      */
    public String getNamespaceURI();

    /** <p>Returns the fully qualified name of this element.
      * This will be the same as the value returned from {@link #getName}
      * if this element has no namespace attached to this element or an
      * expression of the form
      * <pre>
      * getNamespacePrefix() + ":" + getName()
      * </pre>
      * will be returned.
      *
      * @return the fully qualified name of the element.
      */
    public String getQualifiedName();


   /** <p>Returns any additional namespaces declarations for this element
      * other than namespace returned via the {@link #getNamespace()} method.
      * If no additional namespace declarations are present for this
      * element then an empty list will be returned.
      *
      * The list is backed by the element such that changes to the list will
      * be reflected in the element though the reverse is not the case.</p>
      *
      * @return a list of any additional namespace declarations.
      */
    public List additionalNamespaces();

   /** <p>Returns all the namespaces declared by this element.
      * If no namespaces are declared for this element then
      * an empty list will be returned.
      *
      * The list is backed by the element such that changes to the list will
      * be reflected in the element though the reverse is not the case.</p>
      *
      * @return a list of namespaces declared for this element.
      */
    public List declaredNamespaces();



    // Builder methods
    //-------------------------------------------------------------------------

    /** <p>Adds the attribute value of the given local name.
      * If an attribute already exists for the given name it will be replaced.
      * Attributes with null values are silently ignored.
      * If the value of the attribute is null then this method call will
      * remove any attributes with the given name.</p>
      *
      * @param name is the name of the attribute whose value is to be added
      * or updated
      * @param value is the attribute's value
      * @return this <code>Element</code> instance.
      */
    public Element addAttribute(String name, String value);

    /** <p>Adds the attribute value of the given fully qualified name.
      * If an attribute already exists for the given name it will be replaced.
      * Attributes with null values are silently ignored.
      * If the value of the attribute is null then this method call will
      * remove any attributes with the given name.</p>
      *
      * @param qName is the fully qualified name of the attribute
      * whose value is to be added or updated
      * @param value is the attribute's value
      * @return this <code>Element</code> instance.
      */
    public Element addAttribute(QName qName, String value);

    /** Adds a new <code>Comment</code> node with the given text to this element.
      *
      * @param comment is the text for the <code>Comment</code> node.
      * @return this <code>Element</code> instance.
      */
    public Element addComment(String comment);


    /** Adds a new <code>CDATA</code> node with the given text to this element.
      *
      * @param cdata is the text for the <code>CDATA</code> node.
      * @return this <code>Element</code> instance.
      */
    public Element addCDATA(String cdata);

    /** Adds a new <code>Entity</code> node with the given name and text
      * to this element and returns a reference to the new node.
      *
      * @param name is the name for the <code>Entity</code> node.
      * @param text is the text for the <code>Entity</code> node.
      * @return this <code>Element</code> instance.
      */
    public Element addEntity(String name, String text);


    /** Adds a namespace to this element for use by its child content
      *
      * @param prefix is the prefix to use, which should not be null or blank
      * @param uri is the namespace URI
      * @return this <code>Element</code> instance.
      */
    public Element addNamespace(String prefix, String uri);

    /** Adds a processing instruction for the given target
      *
      * @param target is the target of the processing instruction
      * @param text is the textual data (key/value pairs) of the processing instruction
      * @return this <code>Element</code> instance.
      */
    public Element addProcessingInstruction(String target, String text);

    /** Adds a processing instruction for the given target
      *
      * @param target is the target of the processing instruction
      * @param data is a Map of the key / value pairs of the processing instruction
      * @return this <code>Element</code> instance.
      */
    public Element addProcessingInstruction(String target, Map data);

    /** Adds a new <code>Text</code> node with the given text to this element.
      *
      * @param text is the text for the <code>Text</code> node.
      * @return this <code>Element</code> instance.
      */
    public Element addText(String text);


    // Typesafe modifying methods
    //-------------------------------------------------------------------------


    /** Adds the given <code>Attribute</code> to this element.
      * If the given node already has a parent defined then an
      * <code>IllegalAddException</code> will be thrown.
      * Attributes with null values are silently ignored.
      * If the value of the attribute is null then this method call will
      * remove any attributes with the QName of this attribute.</p>
      *
      * @param attribute is the attribute to be added
      */
    public void add(Attribute attribute);


    /** Adds the given <code>CDATA</code> to this element.
      * If the given node already has a parent defined then an
      * <code>IllegalAddException</code> will be thrown.
      *
      * @param cdata is the CDATA to be added
      */
    public void add(CDATA cdata);

    /** Adds the given <code>Entity</code> to this element.
      * If the given node already has a parent defined then an
      * <code>IllegalAddException</code> will be thrown.
      *
      * @param entity is the entity to be added
      */
    public void add(Entity entity);

    /** Adds the given <code>Text</code> to this element.
      * If the given node already has a parent defined then an
      * <code>IllegalAddException</code> will be thrown.
      *
      * @param text is the text to be added
      */
    public void add(Text text);

    /** Adds the given <code>Namespace</code> to this element.
      * If the given node already has a parent defined then an
      * <code>IllegalAddException</code> will be thrown.
      *
      * @param namespace is the namespace to be added
      */
    public void add(Namespace namespace);

    /** Removes the given <code>Attribute</code> from this element.
      *
      * @param attribute is the attribute to be removed
      * @return true if the attribute was removed
      */
    public boolean remove(Attribute attribute);

    /** Removes the given <code>CDATA</code> if the node is
      * an immediate child of this element.
      *
      * If the given node is not an immediate child of this element
      * then the {@link Node#detach()} method should be used instead.
      *
      * @param cdata is the CDATA to be removed
      * @return true if the cdata was removed
      */
    public boolean remove(CDATA cdata);

    /** Removes the given <code>Entity</code> if the node is
      * an immediate child of this element.
      *
      * If the given node is not an immediate child of this element
      * then the {@link Node#detach()} method should be used instead.
      *
      * @param entity is the entity to be removed
      * @return true if the entity was removed
      */
    public boolean remove(Entity entity);

    /** Removes the given <code>Namespace</code> if the node is
      * an immediate child of this element.
      *
      * If the given node is not an immediate child of this element
      * then the {@link Node#detach()} method should be used instead.
      *
      * @param namespace is the namespace to be removed
      * @return true if the namespace was removed
      */
    public boolean remove(Namespace namespace);

    /** Removes the given <code>Text</code> if the node is
      * an immediate child of this element.
      *
      * If the given node is not an immediate child of this element
      * then the {@link Node#detach()} method should be used instead.
      *
      * @param text is the text to be removed
      * @return true if the text was removed
      */
    public boolean remove(Text text);


    // Text methods
    //-------------------------------------------------------------------------

    /** Returns the text value of this element without recursing through
      * child elements.
      * This method iterates through all {@link Text}, {@link CDATA} and
      * {@link Entity} nodes that this element contains
      * and appends the text values together.
      *
      * @return the textual content of this Element. Child elements are not navigated.
      */
    public String getText();

    /** @return the trimmed text value where whitespace is trimmed and
      * normalised into single spaces
      */
    public String getTextTrim();


    /** Returns the XPath string-value of this node.