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

* Element interface defines an XML element. An element can have * declared namespaces, attributes, child nodes and textual content. *

* *

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

* * @author James Strachan * @version $Revision$ */ public interface Element extends Branch { // Name and namespace related methods // ------------------------------------------------------------------------- /** *

* Returns the QName of this element which represents the * local name, the qualified name and the Namespace. *

* * @return the QName associated with this element */ QName getQName(); /** *

* Sets the QName of this element which represents the local * name, the qualified name and the Namespace. *

* * @param qname * is the QName to be associated with this element */ void setQName(QName qname); /** *

* Returns the Namespace of this element if one exists * otherwise Namespace.NO_NAMESPACE is returned. *

* * @return the Namespace associated with this element */ Namespace getNamespace(); /** *

* Returns the QName 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. *

* * @param qualifiedName * DOCUMENT ME! * * @return the QName for the given qualified name */ QName getQName(String qualifiedName); /** *

* Returns the Namespace which is mapped to the given prefix * or null if it could not be found. *

* * @param prefix * DOCUMENT ME! * * @return the Namespace associated with the given prefix */ Namespace getNamespaceForPrefix(String prefix); /** *

* Returns the Namespace which is mapped to the given URI or * null if it could not be found. If there is more than one * Namespace mapped to the URI, which of them will be * returned is undetermined. *

* * @param uri * DOCUMENT ME! * * @return the Namespace associated with the given URI */ Namespace getNamespaceForURI(String uri); /** *

* Returns the all namespaces which are mapped to the given URI or an empty * list if no such namespaces could be found. *

* * @param uri * DOCUMENT ME! * * @return the namespaces associated with the given URI * * @since 1.5 */ List getNamespacesForURI(String uri); /** *

* Returns the namespace prefix of this element if one exists otherwise an * empty String is returned. *

* * @return the prefix of the Namespace of this element or an * empty String */ String getNamespacePrefix(); /** *

* Returns the URI mapped to the namespace of this element if one exists * otherwise an empty String is returned. *

* * @return the URI for the Namespace of this element or an * empty String */ String getNamespaceURI(); /** *

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

     * getNamespacePrefix() + ":" + getName()
     *
* * will be returned. *

* * @return the fully qualified name of the element. */ String getQualifiedName(); /** *

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

* * @return a list of any additional namespace declarations. */ List additionalNamespaces(); /** *

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

* * @return a list of namespaces declared for this element. */ List declaredNamespaces(); // Builder methods // ------------------------------------------------------------------------- /** *

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

* * @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 Element instance. */ Element addAttribute(String name, String value); /** *

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

* * @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 Element instance. */ Element addAttribute(QName qName, String value); /** * Adds a new Comment node with the given text to this * element. * * @param comment * is the text for the Comment node. * * @return this Element instance. */ Element addComment(String comment); /** * Adds a new CDATA node with the given text to this element. * * @param cdata * is the text for the CDATA node. * * @return this Element instance. */ Element addCDATA(String cdata); /** * Adds a new Entity 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 Entity node. * @param text * is the text for the Entity node. * * @return this Element 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 Element 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 Element 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 Element instance. */ Element addProcessingInstruction(String target, Map data); /** * Adds a new Text node with the given text to this element. * * @param text * is the text for the Text node. * * @return this Element instance. */ Element addText(String text); // Typesafe modifying methods // ------------------------------------------------------------------------- /** * Adds the given Attribute to this element. If the given * node already has a parent defined then an * IllegalAddException 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. *

* * @param attribute * is the attribute to be added */ void add(Attribute attribute); /** * Adds the given CDATA to this element. If the given node * already has a parent defined then an IllegalAddException * will be thrown. * * @param cdata * is the CDATA to be added */ void add(CDATA cdata); /** * Adds the given Entity to this element. If the given node * already has a parent defined then an IllegalAddException * will be thrown. * * @param entity * is the entity to be added */ void add(Entity entity); /** * Adds the given Text to this element. If the given node * already has a parent defined then an IllegalAddException * will be thrown. * * @param text * is the text to be added */ void add(Text text); /** * Adds the given Namespace to this element. If the given * node already has a parent defined then an * IllegalAddException will be thrown. * * @param namespace * is the namespace to be added */ void add(Namespace namespace); /** * Removes the given Attribute 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 CDATA 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 Entity 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 Namespace 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 Text 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 XPath * specification . 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 // ------------------------------------------------------------------------- /** *

* 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 List is backed by the * Element so that changes to the list are reflected in the * element and vice versa. *

* * @return the attributes that this element contains as a List */ 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 >= 0 and * index < 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); /** *

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

* * @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); /** *

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

* * @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); /** *

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

* * @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); /** *

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

* * @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); /** *

* Sets the attribute value of the given local name. *

* * @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); /** *

* Sets the attribute value of the given fully qualified name. *

* * @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); /** *

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

* * @return a list of all the elements in this element. */ List elements(); /** *

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

* * @param name * DOCUMENT ME! * * @return a list of all the elements in this element for the given local * name */ List elements(String name); /** *

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

* * @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(); /** *

* Returns true if this Element has mixed content. Mixed * content means that an element contains both textual data and child * elements. *

* * @return true if this element contains mixed content. */ boolean hasMixedContent(); /** *

* Returns true if this Element has text only content. *

* * @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); /** *

* Creates a deep copy of this element The new element is detached from its * parent, and getParent() on the clone will return null. *

* * @return a new deep copy Element */ Element createCopy(); /** *

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

* * @param name * DOCUMENT ME! * * @return a new deep copy Element */ Element createCopy(String name); /** *

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

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