Java tutorial
/* * 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; /** * <code>Element</code> interface defines an XML element. An element can have * declared namespaces, attributes, child nodes and textual content. * <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}. * * @author <a href="mailto:jstrachan@apache.org">James Strachan </a> * @version $Revision: 1.47 $ */ @SuppressWarnings("unused") public interface Element extends Branch { // Name and namespace related methods // ------------------------------------------------------------------------- /** * Returns the <code>QName</code> of this element which represents the * local name, the qualified name and the <code>Namespace</code>. * * @return the <code>QName</code> associated with this element */ QName getQName(); /** * Sets the <code>QName</code> of this element which represents the local * name, the qualified name and the <code>Namespace</code>. * * @param qname is the <code>QName</code> to be associated with this element */ void setQName(QName qname); /** * Returns the <code>Namespace</code> of this element if one exists * otherwise <code>Namespace.NO_NAMESPACE</code> is returned. * * @return the <code>Namespace</code> associated with this element */ Namespace getNamespace(); /** * 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. * * @param qualifiedName DOCUMENT ME! * @return the <code>QName</code> for the given qualified name */ QName getQName(String qualifiedName); /** * Returns the <code>Namespace</code> which is mapped to the given prefix * or null if it could not be found. * * @param prefix DOCUMENT ME! * @return the <code>Namespace</code> associated with the given prefix */ Namespace getNamespaceForPrefix(String prefix); /** * 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. * * @param uri DOCUMENT ME! * @return the <code>Namespace</code> 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<Namespace> getNamespacesForURI(String uri); /** * Returns the namespace prefix of this element if one exists otherwise an * empty <code>String</code> is returned. * * @return the prefix of the <code>Namespace</code> of this element or an * empty <code>String</code> */ String getNamespacePrefix(); /** * Returns the URI mapped to the namespace of this element if one exists * otherwise an empty <code>String</code> is returned. * * @return the URI for the <code>Namespace</code> of this element or an * empty <code>String</code> */ 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 * <pre> * getNamespacePrefix() + ":" + getName() * </pre> * 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<Namespace> 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<Namespace> 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 <code>Element</code> 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 <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<String, String> 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. * * 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 <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 // ------------------------------------------------------------------------- /** * 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. * * @return the attributes that this element contains as a <code>List</code> */ List<Attribute> attributes(); /** * Sets the attributes that this element contains * * @param attributes DOCUMENT ME! */ void setAttributes(List<Attribute> 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<Attribute> 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 returned * @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 returned * @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<Element> 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<Element> 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<Element> elements(QName qName); /** * Returns an iterator over all this elements child elements. * * @return an iterator over the contained elements */ Iterator<Element> 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<Element> 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<Element> 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 <code>Element</code> 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 <code>Element</code> 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. */