fine-third/fine-org-dom4j/src/main/java/org/dom4j/Element.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:jstrachan@apache.org">James Strachan </a>
 * @version $Revision$
 */
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
     *         into single spaces. This method does not return null.
     */
    String getTextTrim();

    /**
     * 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>. This method returns the string-value of all the
     * contained {@link Text},{@link CDATA},{@link Entity}and {@link
     * Element} nodes all appended together.
     * 
     * @return the text from all the child Text and Element nodes appended
     *         together.
     */
    String getStringValue();

    /**
     * Accesses the data of this element which may implement data typing
     * bindings such as XML Schema or Java Bean bindings or will return the same
     * value as {@link #getText}
     * 
     * @return DOCUMENT ME!
     */
    Object getData();

    /**
     * Sets the data value of this element if this element supports data binding
     * or calls {@link #setText}if it doesn't
     * 
     * @param data
     *            DOCUMENT ME!
     */
    void setData(Object data);

    // Attribute methods
    // -------------------------------------------------------------------------

    /**
     * <p>
     * Returns the {@link Attribute}instances this element contains as a backed
     * {@link List}so that the attributes may be modified directly using the
     * {@link List}interface. The <code>List</code> is backed by the
     * <code>Element</code> so that changes to the list are reflected in the
     * element and vice versa.
     * </p>
     * 
     * @return the attributes that this element contains as a <code>List</code>
     */
    List attributes();

    /**
     * Sets the attributes that this element contains
     * 
     * @param attributes
     *            DOCUMENT ME!
     */
    void setAttributes(List attributes);

    /**
     * DOCUMENT ME!
     * 
     * @return the number of attributes this element contains
     */
    int attributeCount();

    /**
     * DOCUMENT ME!
     * 
     * @return an iterator over the attributes of this element
     */
    Iterator attributeIterator();

    /**
     * Returns the attribute at the specified indexGets the
     * 
     * @param index
     *            DOCUMENT ME!
     * 
     * @return the attribute at the specified index where index &gt;= 0 and
     *         index &lt; number of attributes or throws an
     *         IndexOutOfBoundsException if the index is not within the
     *         allowable range
     */
    Attribute attribute(int index);

    /**
     * Returns the attribute with the given name
     * 
     * @param name
     *            DOCUMENT ME!
     * 
     * @return the attribute for the given local name in any namespace. If there
     *         are more than one attributes with the given local name in
     *         different namespaces then the first one is returned.
     */
    Attribute attribute(String name);

    /**
     * DOCUMENT ME!
     * 
     * @param qName
     *            is the fully qualified name
     * 
     * @return the attribute for the given fully qualified name or null if it
     *         could not be found.
     */
    Attribute attribute(QName qName);

    /**
     * <p>
     * This returns the attribute value for the attribute with the given name
     * and any namespace or null if there is no such attribute or the empty
     * string if the attribute value is empty.
     * </p>
     * 
     * @param name
     *            is the name of the attribute value to be returnd
     * 
     * @return the value of the attribute, null if the attribute does not exist
     *         or the empty string
     */
    String attributeValue(String name);

    /**
     * <p>
     * This returns the attribute value for the attribute with the given name
     * and any namespace or the default value if there is no such attribute
     * value.
     * </p>
     * 
     * @param name
     *            is the name of the attribute value to be returnd
     * @param defaultValue
     *            is the default value to be returned if the attribute has no
     *            value defined.
     * 
     * @return the value of the attribute or the defaultValue if the attribute
     *         has no value defined.
     */
    String attributeValue(String name, String defaultValue);

    /**
     * <p>
     * This returns the attribute value for the attribute with the given fully
     * qualified name or null if there is no such attribute or the empty string
     * if the attribute value is empty.
     * </p>
     * 
     * @param qName
     *            is the fully qualified name
     * 
     * @return the value of the attribute, null if the attribute does not exist
     *         or the empty string
     */
    String attributeValue(QName qName);

    /**
     * <p>
     * This returns the attribute value for the attribute with the given fully
     * qualified name or the default value if there is no such attribute value.
     * </p>
     * 
     * @param qName
     *            is the fully qualified name
     * @param defaultValue
     *            is the default value to be returned if the attribute has no
     *            value defined.
     * 
     * @return the value of the attribute or the defaultValue if the attribute
     *         has no value defined.
     */
    String attributeValue(QName qName, String defaultValue);

    /**
     * <p>
     * Sets the attribute value of the given local 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
     * 
     * @deprecated As of version 0.5. Please use {@link
     *             #addAttribute(String,String)} instead. WILL BE REMOVED IN
     *             dom4j-1.6 !!
     */
    void setAttributeValue(String name, String value);

    /**
     * <p>
     * Sets the attribute value of the given fully qualified 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
     * 
     * @deprecated As of version 0.5. Please use {@link
     *             #addAttribute(QName,String)} instead. WILL BE REMOVED IN
     *             dom4j-1.6 !!
     */
    void setAttributeValue(QName qName, String value);

    // Content methods
    // -------------------------------------------------------------------------

    /**
     * Returns the first element for the given local name and any namespace.
     * 
     * @param name
     *            DOCUMENT ME!
     * 
     * @return the first element with the given local name
     */
    Element element(String name);

    /**
     * Returns the first element for the given fully qualified name.
     * 
     * @param qName
     *            is the fully qualified name to search for
     * 
     * @return the first element with the given fully qualified name
     */
    Element element(QName qName);

    /**
     * <p>
     * Returns the elements contained in this element. If this element does not
     * contain any elements then this method returns an empty list. 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 all the elements in this element.
     */
    List elements();

    /**
     * <p>
     * Returns the elements contained in this element with the given local name
     * and any namespace. If no elements are found then this method returns an
     * empty list. 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>
     * 
     * @param name
     *            DOCUMENT ME!
     * 
     * @return a list of all the elements in this element for the given local
     *         name
     */
    List elements(String name);

    /**
     * <p>
     * Returns the elements contained in this element with the given fully
     * qualified name. If no elements are found then this method returns an
     * empty list. 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>
     * 
     * @param qName
     *            is the fully qualified name to search for
     * 
     * @return a list of all the elements in this element for the given fully
     *         qualified name.
     */
    List elements(QName qName);

    /**
     * Returns an iterator over all this elements child elements.
     * 
     * @return an iterator over the contained elements
     */
    Iterator elementIterator();

    /**
     * Returns an iterator over the elements contained in this element which
     * match the given local name and any namespace.
     * 
     * @param name
     *            DOCUMENT ME!
     * 
     * @return an iterator over the contained elements matching the given local
     *         name
     */
    Iterator elementIterator(String name);

    /**
     * Returns an iterator over the elements contained in this element which
     * match the given fully qualified name.
     * 
     * @param qName
     *            is the fully qualified name to search for
     * 
     * @return an iterator over the contained elements matching the given fully
     *         qualified name
     */
    Iterator elementIterator(QName qName);

    // Helper methods
    // -------------------------------------------------------------------------

    /**
     * DOCUMENT ME!
     * 
     * @return true if this element is the root element of a document and this
     *         element supports the parent relationship else false.
     */
    boolean isRootElement();

    /**
     * <p>
     * Returns true if this <code>Element</code> has mixed content. Mixed
     * content means that an element contains both textual data and child
     * elements.
     * </p>
     * 
     * @return true if this element contains mixed content.
     */
    boolean hasMixedContent();

    /**
     * <p>
     * Returns true if this <code>Element</code> has text only content.
     * </p>
     * 
     * @return true if this element is empty or only contains text content.
     */
    boolean isTextOnly();

    /**
     * Appends the attributes of the given element to me. This method behaves
     * like the {@link java.util.Collection#addAll(java.util.Collection)}
     * method.
     * 
     * @param element
     *            is the element whose attributes will be added to me.
     */
    void appendAttributes(Element element);

    /**
     * <p>
     * Creates a deep copy of this element The new element is detached from its
     * parent, and getParent() on the clone will return null.
     * </p>
     * 
     * @return a new deep copy Element
     */
    Element createCopy();

    /**
     * <p>
     * Creates a deep copy of this element with the given local name The new
     * element is detached from its parent, and getParent() on the clone will
     * return null.
     * </p>
     * 
     * @param name
     *            DOCUMENT ME!
     * 
     * @return a new deep copy Element
     */
    Element createCopy(String name);

    /**
     * <p>
     * Creates a deep copy of this element with the given fully qualified name.
     * The new element is detached from its parent, and getParent() on the clone
     * will return null.
     * </p>
     * 
     * @param qName
     *            DOCUMENT ME!
     * 
     * @return a new deep copy Element
     */
    Element createCopy(QName qName);

    String elementText(String name);

    String elementText(QName qname);

    String elementTextTrim(String name);

    String elementTextTrim(QName qname);

    /**
     * Returns a node at the given index suitable for an XPath result set. This
     * means the resulting Node will either be null or it will support the
     * parent relationship.
     * 
     * @param index
     *            DOCUMENT ME!
     * 
     * @return the Node for the given index which will support the parent
     *         relationship or null if there is not a node at the given index.
     */
    Node getXPathResult(int index);
}

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