Coverage Report

Coverage Report - org.simpleframework.xml.stream.InputNode

Classes in this File

 /*
  * InputNode.java July 2006
  *
  * Copyright (C) 2006, Niall Gallagher <niallg@users.sf.net>
  *
  * This library is free software; you can redistribute it and/or
  * modify it under the terms of the GNU Lesser General Public
  * License as published by the Free Software Foundation.
  *
  * This library is distributed in the hope that it will be useful,
  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the 
  * GNU Lesser General Public License for more details.
  *
  * You should have received a copy of the GNU Lesser General 
  * Public License along with this library; if not, write to the 
  * Free Software Foundation, Inc., 59 Temple Place, Suite 330, 
  * Boston, MA  02111-1307  USA
  */
 
 package org.simpleframework.xml.stream;
 
 /**
  * The <code>InputNode</code> object represents an iterator for the
  * elements within an element. This allows the input node object to
  * become a self contained iterator for an element and its children.
  * Each child taken from the input node object, is itself an input
  * node, and can be used to exlpore its sub elements without having
  * any affect on its outer elements.
  *
  * @author Niall Gallagher
  */ 
 public interface InputNode extends Node {
 
    /**
     * This method is used to determine if this node is the root 
     * node for the XML document. The root node is the first node
     * in the document and has no sibling nodes. This is false
     * if the node has a parent node or a sibling node.
     * 
     * @return true if this is the root node within the document
     */
    public boolean isRoot();
 
    /**
     * This is used to determine if this node is an element. This
     * allows users of the framework to make a distinction between
     * nodes that represent attributes and nodes that represent
     * elements. This is particularly useful given that attribute
     * nodes do not maintain a node map of attributes.
     *
     * @return this returns true if the node is an element node
     */ 
    public boolean isElement();
    
    /**
     * This provides the position of this node within the document.
     * This allows the user of this node to report problems with
     * the location within the document, allowing the XML to be
     * debugged if it does not match the class schema.
     *
     * @return this returns the position of the XML read cursor
     */         
    public Position getPosition();
         
    /**
     * Provides an attribute from the element represented. If an
     * attribute for the specified name does not exist within the
     * element represented then this method will return null.
     *
     * @param name this is the name of the attribute to retrieve
     *
     * @return this returns the value for the named attribute
     */ 
    public InputNode getAttribute(String name);
 
    /**
     * This returns a map of the attributes contained within the
     * element. If no elements exist within the element then this
     * returns an empty map. 
     * 
     * @return this returns a map of attributes for the element
     */  
    public NodeMap getAttributes();
    
    /**
     * This is used to acquire the <code>Node</code> that is the
     * parent of this node. This will return the node that is
     * the direct parent of this node and allows for siblings to
     * make use of nodes with their parents if required.  
     *   
     * @return this returns the parent node for this node
     */
    public InputNode getParent();
    
    /**
     * This returns the next child element within this element if
     * one exists. If all children have been read, or if there are
     * no child elements for this element then this returns null.
     *
     * @return this returns an input node for the next child
     *
     * @exception Exception thrown if there was a parse error
     */ 
    public InputNode getNext() throws Exception;  
    
    /**
     * This returns the next child in this element if that child
     * has the name provided. If the next child element in this
     * node does not have the name given then null is returned.
     * 
     * @param name this is the name of the next child element 
     * 
     * @return the next element if it has the name specified
     * 
     * @exception Exception thrown if there was a parse error
     */
    public InputNode getNext(String name) throws Exception;
 
    /**
     * This method is used to skip all child elements from this
     * element. This allows elements to be effectively skipped such
     * that when parsing a document if an element is not required
     * then that element can be completely removed from the XML.
     *
     * @exception Exception thrown if there was a parse error
     */ 
    public void skip() throws Exception;
    
    /**
     * This is used to determine if this input node is empty. An
     * empty node is one with no attributes or children. This can
     * be used to determine if a given node represents an empty
     * entity, with which no extra data can be extracted.
     * 
     * @return this returns true if the node is an empty element
     * 
     * @throws Exception thrown if there was a parse error
     */
    public boolean isEmpty() throws Exception;
 }

1		/*
2		* InputNode.java July 2006
3		*
4		* Copyright (C) 2006, Niall Gallagher <niallg@users.sf.net>
5		*
6		* This library is free software; you can redistribute it and/or
7		* modify it under the terms of the GNU Lesser General Public
8		* License as published by the Free Software Foundation.
9		*
10		* This library is distributed in the hope that it will be useful,
11		* but WITHOUT ANY WARRANTY; without even the implied warranty of
12		* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13		* GNU Lesser General Public License for more details.
14		*
15		* You should have received a copy of the GNU Lesser General
16		* Public License along with this library; if not, write to the
17		* Free Software Foundation, Inc., 59 Temple Place, Suite 330,
18		* Boston, MA 02111-1307 USA
19		*/
20
21		package org.simpleframework.xml.stream;
22
23		/**
24		* The <code>InputNode</code> object represents an iterator for the
25		* elements within an element. This allows the input node object to
26		* become a self contained iterator for an element and its children.
27		* Each child taken from the input node object, is itself an input
28		* node, and can be used to exlpore its sub elements without having
29		* any affect on its outer elements.
30		*
31		* @author Niall Gallagher
32		*/
33		public interface InputNode extends Node {
34
35		/**
36		* This method is used to determine if this node is the root
37		* node for the XML document. The root node is the first node
38		* in the document and has no sibling nodes. This is false
39		* if the node has a parent node or a sibling node.
40		*
41		* @return true if this is the root node within the document
42		*/
43		public boolean isRoot();
44
45		/**
46		* This is used to determine if this node is an element. This
47		* allows users of the framework to make a distinction between
48		* nodes that represent attributes and nodes that represent
49		* elements. This is particularly useful given that attribute
50		* nodes do not maintain a node map of attributes.
51		*
52		* @return this returns true if the node is an element node
53		*/
54		public boolean isElement();
55
56		/**
57		* This provides the position of this node within the document.
58		* This allows the user of this node to report problems with
59		* the location within the document, allowing the XML to be
60		* debugged if it does not match the class schema.
61		*
62		* @return this returns the position of the XML read cursor
63		*/
64		public Position getPosition();
65
66		/**
67		* Provides an attribute from the element represented. If an
68		* attribute for the specified name does not exist within the
69		* element represented then this method will return null.
70		*
71		* @param name this is the name of the attribute to retrieve
72		*
73		* @return this returns the value for the named attribute
74		*/
75		public InputNode getAttribute(String name);
76
77		/**
78		* This returns a map of the attributes contained within the
79		* element. If no elements exist within the element then this
80		* returns an empty map.
81		*
82		* @return this returns a map of attributes for the element
83		*/
84		public NodeMap getAttributes();
85
86		/**
87		* This is used to acquire the <code>Node</code> that is the
88		* parent of this node. This will return the node that is
89		* the direct parent of this node and allows for siblings to
90		* make use of nodes with their parents if required.
91		*
92		* @return this returns the parent node for this node
93		*/
94		public InputNode getParent();
95
96		/**
97		* This returns the next child element within this element if
98		* one exists. If all children have been read, or if there are
99		* no child elements for this element then this returns null.
100		*
101		* @return this returns an input node for the next child
102		*
103		* @exception Exception thrown if there was a parse error
104		*/
105		public InputNode getNext() throws Exception;
106
107		/**
108		* This returns the next child in this element if that child
109		* has the name provided. If the next child element in this
110		* node does not have the name given then null is returned.
111		*
112		* @param name this is the name of the next child element
113		*
114		* @return the next element if it has the name specified
115		*
116		* @exception Exception thrown if there was a parse error
117		*/
118		public InputNode getNext(String name) throws Exception;
119
120		/**
121		* This method is used to skip all child elements from this
122		* element. This allows elements to be effectively skipped such
123		* that when parsing a document if an element is not required
124		* then that element can be completely removed from the XML.
125		*
126		* @exception Exception thrown if there was a parse error
127		*/
128		public void skip() throws Exception;
129
130		/**
131		* This is used to determine if this input node is empty. An
132		* empty node is one with no attributes or children. This can
133		* be used to determine if a given node represents an empty
134		* entity, with which no extra data can be extracted.
135		*
136		* @return this returns true if the node is an empty element
137		*
138		* @throws Exception thrown if there was a parse error
139		*/
140		public boolean isEmpty() throws Exception;
141		}