element.java

解决如何把XML应用到JAVA里问题

/*
 * 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.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.47 $
 */
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
     */
    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
     */
    void setQName(QName qname);

    /**
     * <p>
     * Returns the <code>Namespace</code> of this element if one exists
     * otherwise <code>Namespace.NO_NAMESPACE</code> is returned.
     * </p>
     * 
     * @return the <code>Namespace</code> associated with this element
     */
    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>
     * 
     * @param qualifiedName
     *            DOCUMENT ME!
     * 
     * @return the <code>QName</code> for the given qualified name
     */
    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>
     * 
     * @param prefix
     *            DOCUMENT ME!
     * 
     * @return the <code>Namespace</code> associated with the given prefix
     */
    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. If there is more than one
     * <code>Namespace</code> mapped to the URI, which of them will be
     * returned is undetermined.
     * </p>
     * 
     * @param uri
     *            DOCUMENT ME!
     * 
     * @return the <code>Namespace</code> associated with the given URI
     */
    Namespace getNamespaceForURI(String uri);

    /**
     * <p>
     * Returns the all namespaces which are mapped to the given URI or an empty
     * list if no such namespaces could be found.
     * </p>
     * 
     * @param uri
     *            DOCUMENT ME!
     * 
     * @return the namespaces associated with the given URI
     * 
     * @since 1.5
     */
    List getNamespacesForURI(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>
     */
    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>
     */
    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() + &quot;:&quot; + getName()
     * </pre>
     * 
     * will be returned.
     * </p>
     * 
     * @return the fully qualified name of the element.
     */
    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.
     */
    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.
     */
    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.
     */
    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.
     */
    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.
     */
    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.
     */
    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.
     */
    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.
     */
    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.
     */
    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.
     */
    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.
     */
    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.
     * 
     * <p>
     * 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
     */
    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
     */
    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
     */
    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
     */
    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
     */
    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
     */
    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
     */
    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
     */
    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
     */
    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
     */
    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. This method does not return null;
     */
    String getText();

    /**
     * DOCUMENT ME!
     * 
     * @return the trimmed text value where whitespace is trimmed and normalised