001/*
002 * InputNode.java July 2006
003 *
004 * Copyright (C) 2006, Niall Gallagher <niallg@users.sf.net>
005 *
006 * Licensed under the Apache License, Version 2.0 (the "License");
007 * you may not use this file except in compliance with the License.
008 * You may obtain a copy of the License at
009 *
010 *     http://www.apache.org/licenses/LICENSE-2.0
011 *
012 * Unless required by applicable law or agreed to in writing, software
013 * distributed under the License is distributed on an "AS IS" BASIS,
014 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or 
015 * implied. See the License for the specific language governing 
016 * permissions and limitations under the License.
017 */
018
019package org.simpleframework.xml.stream;
020
021/**
022 * The <code>InputNode</code> object represents an iterator for the
023 * elements within an element. This allows the input node object to
024 * become a self contained iterator for an element and its children.
025 * Each child taken from the input node object, is itself an input
026 * node, and can be used to explore its sub elements without having
027 * any affect on its outer elements.
028 *
029 * @author Niall Gallagher
030 */ 
031public interface InputNode extends Node {
032
033   /**
034    * This method is used to determine if this node is the root 
035    * node for the XML document. The root node is the first node
036    * in the document and has no sibling nodes. This is false
037    * if the node has a parent node or a sibling node.
038    * 
039    * @return true if this is the root node within the document
040    */
041   boolean isRoot();
042
043   /**
044    * This is used to determine if this node is an element. This
045    * allows users of the framework to make a distinction between
046    * nodes that represent attributes and nodes that represent
047    * elements. This is particularly useful given that attribute
048    * nodes do not maintain a node map of attributes.
049    *
050    * @return this returns true if the node is an element node
051    */ 
052   boolean isElement();
053   
054   /**
055    * This is used to acquire the namespace prefix for the node.
056    * If there is no namespace prefix for the node then this will
057    * return null. Acquiring the prefix enables the qualification
058    * of the node to be determined. It also allows nodes to be
059    * grouped by its prefix and allows group operations.
060    * 
061    * @return this returns the prefix associated with this node
062    */
063   String getPrefix();
064   
065   /**
066    * This allows the namespace reference URI to be determined.
067    * A reference is a globally unique string that allows the
068    * node to be identified. Typically the reference will be a URI
069    * but it can be any unique string used to identify the node.
070    * This allows the node to be identified within the namespace.
071    * 
072    * @return this returns the associated namespace reference URI 
073    */
074   String getReference();
075   
076   /**
077    * This provides the position of this node within the document.
078    * This allows the user of this node to report problems with
079    * the location within the document, allowing the XML to be
080    * debugged if it does not match the class schema.
081    *
082    * @return this returns the position of the XML read cursor
083    */         
084   Position getPosition();
085        
086   /**
087    * Provides an attribute from the element represented. If an
088    * attribute for the specified name does not exist within the
089    * element represented then this method will return null.
090    *
091    * @param name this is the name of the attribute to retrieve
092    *
093    * @return this returns the value for the named attribute
094    */ 
095   InputNode getAttribute(String name);
096
097   /**
098    * This returns a map of the attributes contained within the
099    * 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}