Coverage Report - org.simpleframework.xml.stream.InputNode
 
Classes in this File Line Coverage Branch Coverage Complexity
InputNode
N/A
N/A
1
 
 1  
 /*
 2  
  * InputNode.java July 2006
 3  
  *
 4  
  * Copyright (C) 2006, Niall Gallagher <niallg@users.sf.net>
 5  
  *
 6  
  * Licensed under the Apache License, Version 2.0 (the "License");
 7  
  * you may not use this file except in compliance with the License.
 8  
  * You may obtain a copy of the License at
 9  
  *
 10  
  *     http://www.apache.org/licenses/LICENSE-2.0
 11  
  *
 12  
  * Unless required by applicable law or agreed to in writing, software
 13  
  * distributed under the License is distributed on an "AS IS" BASIS,
 14  
  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or 
 15  
  * implied. See the License for the specific language governing 
 16  
  * permissions and limitations under the License.
 17  
  */
 18  
 
 19  
 package org.simpleframework.xml.stream;
 20  
 
 21  
 /**
 22  
  * The <code>InputNode</code> object represents an iterator for the
 23  
  * elements within an element. This allows the input node object to
 24  
  * become a self contained iterator for an element and its children.
 25  
  * Each child taken from the input node object, is itself an input
 26  
  * node, and can be used to explore its sub elements without having
 27  
  * any affect on its outer elements.
 28  
  *
 29  
  * @author Niall Gallagher
 30  
  */ 
 31  
 public interface InputNode extends Node {
 32  
 
 33  
    /**
 34  
     * This method is used to determine if this node is the root 
 35  
     * node for the XML document. The root node is the first node
 36  
     * in the document and has no sibling nodes. This is false
 37  
     * if the node has a parent node or a sibling node.
 38  
     * 
 39  
     * @return true if this is the root node within the document
 40  
     */
 41  
    boolean isRoot();
 42  
 
 43  
    /**
 44  
     * This is used to determine if this node is an element. This
 45  
     * allows users of the framework to make a distinction between
 46  
     * nodes that represent attributes and nodes that represent
 47  
     * elements. This is particularly useful given that attribute
 48  
     * nodes do not maintain a node map of attributes.
 49  
     *
 50  
     * @return this returns true if the node is an element node
 51  
     */ 
 52  
    boolean isElement();
 53  
    
 54  
    /**
 55  
     * This is used to acquire the namespace prefix for the node.
 56  
     * If there is no namespace prefix for the node then this will
 57  
     * return null. Acquiring the prefix enables the qualification
 58  
     * of the node to be determined. It also allows nodes to be
 59  
     * grouped by its prefix and allows group operations.
 60  
     * 
 61  
     * @return this returns the prefix associated with this node
 62  
     */
 63  
    String getPrefix();
 64  
    
 65  
    /**
 66  
     * This allows the namespace reference URI to be determined.
 67  
     * A reference is a globally unique string that allows the
 68  
     * node to be identified. Typically the reference will be a URI
 69  
     * but it can be any unique string used to identify the node.
 70  
     * This allows the node to be identified within the namespace.
 71  
     * 
 72  
     * @return this returns the associated namespace reference URI 
 73  
     */
 74  
    String getReference();
 75  
    
 76  
    /**
 77  
     * This provides the position of this node within the document.
 78  
     * This allows the user of this node to report problems with
 79  
     * the location within the document, allowing the XML to be
 80  
     * debugged if it does not match the class schema.
 81  
     *
 82  
     * @return this returns the position of the XML read cursor
 83  
     */         
 84  
    Position getPosition();
 85  
         
 86  
    /**
 87  
     * Provides an attribute from the element represented. If an
 88  
     * attribute for the specified name does not exist within the
 89  
     * element represented then this method will return null.
 90  
     *
 91  
     * @param name this is the name of the attribute to retrieve
 92  
     *
 93  
     * @return this returns the value for the named attribute
 94  
     */ 
 95  
    InputNode getAttribute(String name);
 96  
 
 97  
    /**
 98  
     * This returns a map of the attributes contained within the
 99  
     * element. If no elements exist within the element then this
 100  
     * returns an empty map. 
 101  
     * 
 102  
     * @return this returns a map of attributes for the element
 103  
     */  
 104  
    NodeMap<InputNode> getAttributes();
 105  
    
 106  
    /**
 107  
     * This is used to acquire the <code>Node</code> that is the
 108  
     * parent of this node. This will return the node that is
 109  
     * the direct parent of this node and allows for siblings to
 110  
     * make use of nodes with their parents if required.  
 111  
     *   
 112  
     * @return this returns the parent node for this node
 113  
     */
 114  
    InputNode getParent();
 115  
    
 116  
    /**
 117  
     * This is used to return the source object for this node. This
 118  
     * is used primarily as a means to determine which XML provider
 119  
     * is parsing the source document and producing the nodes. It
 120  
     * is useful to be able to determine the XML provider like this.
 121  
     * 
 122  
     * @return this returns the source of this input node
 123  
     */
 124  
    Object getSource();
 125  
    
 126  
    /**
 127  
     * This returns the next child element within this element if
 128  
     * one exists. If all children have been read, or if there are
 129  
     * no child elements for this element then this returns null.
 130  
     *
 131  
     * @return this returns an input node for the next child
 132  
     *
 133  
     * @exception Exception thrown if there was a parse error
 134  
     */ 
 135  
    InputNode getNext() throws Exception;  
 136  
    
 137  
    /**
 138  
     * This returns the next child in this element if that child
 139  
     * has the name provided. If the next child element in this
 140  
     * node does not have the name given then null is returned.
 141  
     * 
 142  
     * @param name this is the name of the next child element 
 143  
     * 
 144  
     * @return the next element if it has the name specified
 145  
     * 
 146  
     * @exception Exception thrown if there was a parse error
 147  
     */
 148  
    InputNode getNext(String name) throws Exception;
 149  
 
 150  
    /**
 151  
     * This method is used to skip all child elements from this
 152  
     * element. This allows elements to be effectively skipped such
 153  
     * that when parsing a document if an element is not required
 154  
     * then that element can be completely removed from the XML.
 155  
     *
 156  
     * @exception Exception thrown if there was a parse error
 157  
     */ 
 158  
    void skip() throws Exception;
 159  
    
 160  
    /**
 161  
     * This is used to determine if this input node is empty. An
 162  
     * empty node is one with no attributes or children. This can
 163  
     * be used to determine if a given node represents an empty
 164  
     * entity, with which no extra data can be extracted.
 165  
     * 
 166  
     * @return this returns true if the node is an empty element
 167  
     * 
 168  
     * @throws Exception thrown if there was a parse error
 169  
     */
 170  
    boolean isEmpty() throws Exception;
 171  
 }