# InputNode
Date: 2013-02-18

## org.simpleframework.xml.stream
Interface InputNode

All Superinterfaces:
  Node

    public interface InputNode

extends Node

The `InputNode` 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 explore its sub elements without having any affect on its outer elements.

Author:
  Niall Gallagher

Method Summary
`InputNode` `getAttribute(java.lang.String name)` Provides an attribute from the element represented.
`NodeMap<InputNode>` `getAttributes()` This returns a map of the attributes contained within the element.
`InputNode` `getNext()` This returns the next child element within this element if one exists.
`InputNode` `getNext(java.lang.String name)` This returns the next child in this element if that child has the name provided.
`InputNode` `getParent()` This is used to acquire the `Node` that is the parent of this node.
`Position` `getPosition()` This provides the position of this node within the document.
`java.lang.String` `getPrefix()` This is used to acquire the namespace prefix for the node.
`java.lang.String` `getReference()` This allows the namespace reference URI to be determined.
`java.lang.Object` `getSource()` This is used to return the source object for this node.
`boolean` `isElement()` This is used to determine if this node is an element.
`boolean` `isEmpty()` This is used to determine if this input node is empty.
`boolean` `isRoot()` This method is used to determine if this node is the root node for the XML document.
`void` `skip()` This method is used to skip all child elements from this element.

Methods inherited from interface org.simpleframework.xml.stream.Node
`getName, getValue`

Method Detail

### isRoot

    boolean isRoot()

  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.

  Returns:
    true if this is the root node within the document

### isElement

    boolean isElement()

  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.

  Returns:
    this returns true if the node is an element node

### getPrefix

    java.lang.String getPrefix()

  This is used to acquire the namespace prefix for the node. If there is no namespace prefix for the node then this will return null. Acquiring the prefix enables the qualification of the node to be determined. It also allows nodes to be grouped by its prefix and allows group operations.

  Returns:
    this returns the prefix associated with this node

### getReference

    java.lang.String getReference()

  This allows the namespace reference URI to be determined. A reference is a globally unique string that allows the node to be identified. Typically the reference will be a URI but it can be any unique string used to identify the node. This allows the node to be identified within the namespace.

  Returns:
    this returns the associated namespace reference URI

### getPosition

    Position getPosition()

  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.

  Returns:
    this returns the position of the XML read cursor

### getAttribute

    InputNode getAttribute(java.lang.String name)

  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.

  Parameters:
    `name` - this is the name of the attribute to retrieve
  Returns:
    this returns the value for the named attribute

### getAttributes

    NodeMap<InputNode> getAttributes()

  This returns a map of the attributes contained within the element. If no elements exist within the element then this returns an empty map.

  Returns:
    this returns a map of attributes for the element

### getParent

    InputNode getParent()

  This is used to acquire the `Node` 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.

  Specified by:
    `getParent` in interface `Node`
  Returns:
    this returns the parent node for this node

### getSource

    java.lang.Object getSource()

  This is used to return the source object for this node. This is used primarily as a means to determine which XML provider is parsing the source document and producing the nodes. It is useful to be able to determine the XML provider like this.

  Returns:
    this returns the source of this input node

### getNext

    InputNode getNext()
                      throws java.lang.Exception

  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.

  Returns:
    this returns an input node for the next child
  Throws:
    `java.lang.Exception` - thrown if there was a parse error

### getNext

    InputNode getNext(java.lang.String name)
                      throws java.lang.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.

  Parameters:
    `name` - this is the name of the next child element
  Returns:
    the next element if it has the name specified
  Throws:
    `java.lang.Exception` - thrown if there was a parse error

### skip

    void skip()
              throws java.lang.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.

  Throws:
    `java.lang.Exception` - thrown if there was a parse error

### isEmpty

    boolean isEmpty()
                    throws java.lang.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.

  Returns:
    this returns true if the node is an empty element
  Throws:
    `java.lang.Exception` - thrown if there was a parse error