You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
308 lines
11 KiB
308 lines
11 KiB
/* |
|
* 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; |
|
|
|
/** |
|
* <code>Branch</code> interface defines the common behaviour for Nodes which |
|
* can contain child nodes (content) such as XML elements and documents. This |
|
* interface allows both elements and documents to be treated in a polymorphic |
|
* manner when changing or navigating child nodes (content). |
|
* |
|
* @author <a href="mailto:jstrachan@apache.org">James Strachan </a> |
|
* @version $Revision: 1.32 $ |
|
*/ |
|
@SuppressWarnings("unused") |
|
public interface Branch extends Node { |
|
/** |
|
* Returns the <code>Node</code> at the specified index position. |
|
* |
|
* @param index the index of the node to return. |
|
* @return the <code>Node</code> at the specified position. |
|
* @throws IndexOutOfBoundsException if the index is out of range (index < 0 || index >= |
|
* {@link Branch#nodeCount()}). |
|
*/ |
|
Node node(int index) throws IndexOutOfBoundsException; |
|
|
|
/** |
|
* Returns the index of the given node if it is a child node of this branch |
|
* or -1 if the given node is not a child node. |
|
* |
|
* @param node the content child node to find. |
|
* @return the index of the given node starting at 0 or -1 if the node is |
|
* not a child node of this branch |
|
*/ |
|
int indexOf(Node node); |
|
|
|
/** |
|
* Returns the number of <code>Node</code> instances that this branch |
|
* contains. |
|
* |
|
* @return the number of nodes this branch contains |
|
*/ |
|
int nodeCount(); |
|
|
|
/** |
|
* Returns the element of the given ID attribute value. If this tree is |
|
* capable of understanding which attribute value should be used for the ID |
|
* then it should be used, otherwise this method should return null. |
|
* |
|
* @param elementID DOCUMENT ME! |
|
* @return DOCUMENT ME! |
|
*/ |
|
Element elementByID(String elementID); |
|
|
|
/** |
|
* Returns the content nodes of this branch as a backed {@link List}so that |
|
* the content of this branch may be modified directly using the |
|
* {@link List}interface. The <code>List</code> is backed by the |
|
* <code>Branch</code> so that changes to the list are reflected in the |
|
* branch and vice versa. |
|
* |
|
* @return the nodes that this branch contains as a <code>List</code> |
|
*/ |
|
List<Node> content(); |
|
|
|
/** |
|
* Returns an iterator through the content nodes of this branch |
|
* |
|
* @return an iterator through the content nodes of this branch |
|
*/ |
|
Iterator<Node> nodeIterator(); |
|
|
|
/** |
|
* Sets the contents of this branch as a <code>List</code> of |
|
* <code>Node</code> instances. |
|
* |
|
* @param content is the list of nodes to use as the content for this branch. |
|
*/ |
|
void setContent(List<Node> content); |
|
|
|
/** |
|
* Appends the content of the given branch to this branch instance. This |
|
* method behaves like the {@link |
|
* java.util.Collection#addAll(java.util.Collection)} method. |
|
* |
|
* @param branch is the branch whose content will be added to me. |
|
*/ |
|
void appendContent(Branch branch); |
|
|
|
/** |
|
* Clears the content for this branch, removing any <code>Node</code> |
|
* instances this branch may contain. |
|
*/ |
|
void clearContent(); |
|
|
|
/** |
|
* Returns a list of all the processing instructions in this branch. The |
|
* list is backed by this branch so that changes to the list will be |
|
* reflected in the branch but the reverse is not the case. |
|
* |
|
* @return a backed list of the processing instructions |
|
*/ |
|
List<ProcessingInstruction> processingInstructions(); |
|
|
|
/** |
|
* Returns a list of the processing instructions for the given target. The |
|
* list is backed by this branch so that changes to the list will be |
|
* reflected in the branch but the reverse is not the case. |
|
* |
|
* @param target DOCUMENT ME! |
|
* @return a backed list of the processing instructions |
|
*/ |
|
List<ProcessingInstruction> processingInstructions(String target); |
|
|
|
/** |
|
* DOCUMENT ME! |
|
* |
|
* @param target DOCUMENT ME! |
|
* @return the processing instruction for the given target |
|
*/ |
|
ProcessingInstruction processingInstruction(String target); |
|
|
|
/** |
|
* Sets all the processing instructions for this branch |
|
* |
|
* @param listOfPIs DOCUMENT ME! |
|
*/ |
|
void setProcessingInstructions(List<ProcessingInstruction> listOfPIs); |
|
|
|
/** |
|
* Adds a new <code>Element</code> node with the given name to this branch |
|
* and returns a reference to the new node. |
|
* |
|
* @param name is the name for the <code>Element</code> node. |
|
* @return the newly added <code>Element</code> node. |
|
*/ |
|
Element addElement(String name); |
|
|
|
/** |
|
* Adds a new <code>Element</code> node with the given {@link QName}to |
|
* this branch and returns a reference to the new node. |
|
* |
|
* @param qname is the qualified name for the <code>Element</code> node. |
|
* @return the newly added <code>Element</code> node. |
|
*/ |
|
Element addElement(QName qname); |
|
|
|
/** |
|
* Adds a new <code>Element</code> node with the given qualified name and |
|
* namespace URI to this branch and returns a reference to the new node. |
|
* |
|
* @param qualifiedName is the fully qualified name of the Element |
|
* @param namespaceURI is the URI of the namespace to use |
|
* @return the newly added <code>Element</code> node. |
|
*/ |
|
Element addElement(String qualifiedName, String namespaceURI); |
|
|
|
/** |
|
* Removes the processing instruction for the given target if it exists |
|
* |
|
* @param target DOCUMENT ME! |
|
* @return true if a processing instruction was removed else false |
|
*/ |
|
boolean removeProcessingInstruction(String target); |
|
|
|
/** |
|
* Adds the given <code>Node</code> or throws {@link IllegalAddException} |
|
* if the given node is not of a valid type. This is a polymorphic method |
|
* which will call the typesafe method for the node type such as |
|
* add(Element) or add(Comment). |
|
* |
|
* @param node is the given node to add |
|
*/ |
|
void add(Node node); |
|
|
|
/** |
|
* Adds the given <code>Comment</code> to this branch. If the given node |
|
* already has a parent defined then an <code>IllegalAddException</code> |
|
* will be thrown. |
|
* |
|
* @param comment is the comment to be added |
|
*/ |
|
void add(Comment comment); |
|
|
|
/** |
|
* Adds the given <code>Element</code> to this branch. If the given node |
|
* already has a parent defined then an <code>IllegalAddException</code> |
|
* will be thrown. |
|
* |
|
* @param element is the element to be added |
|
*/ |
|
void add(Element element); |
|
|
|
/** |
|
* Adds the given <code>ProcessingInstruction</code> to this branch. If |
|
* the given node already has a parent defined then an |
|
* <code>IllegalAddException</code> will be thrown. |
|
* |
|
* @param pi is the processing instruction to be added |
|
*/ |
|
void add(ProcessingInstruction pi); |
|
|
|
/** |
|
* Removes the given <code>Node</code> if the node is an immediate child |
|
* of this branch. If the given node is not an immediate child of this |
|
* branch then the {@link Node#detach()}method should be used instead. This |
|
* is a polymorphic method which will call the typesafe method for the node |
|
* type such as remove(Element) or remove(Comment). |
|
* |
|
* @param node is the given node to be removed |
|
* @return true if the node was removed |
|
*/ |
|
boolean remove(Node node); |
|
|
|
/** |
|
* Removes the given <code>Comment</code> if the node is an immediate |
|
* child of this branch. If the given node is not an immediate child of this |
|
* branch then the {@link Node#detach()}method should be used instead. |
|
* |
|
* @param comment is the comment to be removed |
|
* @return true if the comment was removed |
|
*/ |
|
boolean remove(Comment comment); |
|
|
|
/** |
|
* Removes the given <code>Element</code> if the node is an immediate |
|
* child of this branch. If the given node is not an immediate child of this |
|
* branch then the {@link Node#detach()}method should be used instead. |
|
* |
|
* @param element is the element to be removed |
|
* @return true if the element was removed |
|
*/ |
|
boolean remove(Element element); |
|
|
|
/** |
|
* Removes the given <code>ProcessingInstruction</code> if the node is an |
|
* immediate child of this branch. If the given node is not an immediate |
|
* child of this branch then the {@link Node#detach()}method should be used |
|
* instead. |
|
* |
|
* @param pi is the processing instruction to be removed |
|
* @return true if the processing instruction was removed |
|
*/ |
|
boolean remove(ProcessingInstruction pi); |
|
|
|
/** |
|
* Puts all <code>Text</code> nodes in the full depth of the sub-tree |
|
* underneath this <code>Node</code>, including attribute nodes, into a |
|
* "normal" form where only structure (e.g., elements, comments, processing |
|
* instructions, CDATA sections, and entity references) separates |
|
* <code>Text</code> nodes, i.e., there are neither adjacent |
|
* <code>Text</code> nodes nor empty <code>Text</code> nodes. This can |
|
* be used to ensure that the DOM view of a document is the same as if it |
|
* were saved and re-loaded, and is useful when operations (such as XPointer |
|
* lookups) that depend on a particular document tree structure are to be |
|
* used.In cases where the document contains <code>CDATASections</code>, |
|
* the normalize operation alone may not be sufficient, since XPointers do |
|
* not differentiate between <code>Text</code> nodes and |
|
* <code>CDATASection</code> nodes. |
|
* |
|
* @since DOM Level 2 |
|
*/ |
|
void normalize(); |
|
} |
|
|
|
/* |
|
* 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. |
|
*/
|
|
|