content: /*
   * InputElement.java July 2006
   *
   * Copyright (C) 2006, Niall Gallagher <niallg@users.sf.net>
   *
   * Licensed under the Apache License, Version 2.0 (the "License");
   * you may not use this file except in compliance with the License.
   * You may obtain a copy of the License at
   *
   *     http://www.apache.org/licenses/LICENSE-2.0
   *
   * Unless required by applicable law or agreed to in writing, software
   * distributed under the License is distributed on an "AS IS" BASIS,
   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or 
   * implied. See the License for the specific language governing 
   * permissions and limitations under the License.
   */
  
  package com.aliyun.odps.simpleframework.xml.stream;
  
  /**
   * The <code>InputElement</code> represents a self contained element
   * that will allow access to its child elements. If the next element
   * read from the <code>NodeReader</code> is not a child then this
   * will return null. The input element node also allows the attribute
   * values associated with the node to be accessed.
   * 
   * @author Niall Gallagher
   *
   * @see NodeReader
   */ 
  class InputElement implements InputNode {
     
     /**
      * This contains all the attributes associated with the element.
      */ 
     private final InputNodeMap map;
  
     /**
      * This is the node reader that reads from the XML document.
      */ 
     private final NodeReader reader;
     
     /**
      * This is the parent node for this XML input element node.
      */
     private final InputNode parent;
     
     /**
      * This is the XML element that this node provides access to.
      */         
     private final EventNode node;
   
     /**
      * Constructor for the <code>InputElement</code> object. This 
      * is used to create an input node that will provide access to 
      * an XML element. All attributes associated with the element 
      * given are extracted and exposed via the attribute node map.
      *
      * @param parent this is the parent XML element for this 
      * @param reader this is the reader used to read XML elements
      * @param node this is the XML element wrapped by this node
      */ 
     public InputElement(InputNode parent, NodeReader reader, EventNode node) {
        this.map = new InputNodeMap(this, node);      
        this.reader = reader;           
        this.parent = parent;
        this.node = node;
     }
     
     /**
      * 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.
      * 
      * @return this returns the source of this input node
      */
     public Object getSource() {
        return node.getSource();
     }
     
     /**
      * 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() {
        return parent;
     }
     
     /**
      * 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() {
        return new InputPosition(node);           
     }   
  
     /**
      * Returns the name of the node that this represents. This is
      * an immutable property and should not change for any node.  
      * This provides the name without the name space part.
      *  
      * @return returns the name of the node that this represents
      */   
     public String getName() {
        return node.getName();           
     }
     
     /**
      * 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.
      * 
      * @return this returns the prefix associated with this node
      */
     public String getPrefix() {
        return node.getPrefix();
     }
     
     /**
      * 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.
      * 
      * @return this returns the associated namespace reference URI 
      */
     public String getReference() {
        return node.getReference();
     }
     
     /**
      * 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() {
        return reader.isRoot(this);
     }
  
     /**
      * 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 as this instance is an element
      */ 
     public boolean isElement() {
        return true;           
     } 
  
     /**
      * 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) {
        return map.get(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<InputNode> getAttributes() {
        return map;
     }
  
     /**
      * Returns the value for the node that this represents. This 
      * is an immutable value for the node and cannot be changed.
      * If there is a problem reading an exception is thrown.
      * 
      * @return the name of the value for this node instance
      */     
     public String getValue() throws Exception {
        return reader.readValue(this);           
     }
    
     /**
      * The method is used to acquire the next child attribute of this 
      * element. If the next element from the <code>NodeReader</code> 
      * is not a child node to the element that this represents then
      * this will return null, which ensures each element represents
      * a self contained collection of child nodes.
      *
      * @return this returns the next child element of this node
      *
      * @exception Exception thrown if there is a problem reading
      */  
     public InputNode getNext() throws Exception {
        return reader.readElement(this);
     }
     
     /**
      * The method is used to acquire the next child attribute of this 
      * element. If the next element from the <code>NodeReader</code> 
      * is not a child node to the element that this represents then
      * this will return null, also if the next element does not match
      * the specified name then this will return null.
      *
      * @param name this is the name expected fromt he next element
      *
      * @return this returns the next child element of this node
      *
      * @exception Exception thrown if there is a problem reading
      */  
     public InputNode getNext(String name) throws Exception {
        return reader.readElement(this, name);
     }
     
     /**
      * 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 {
        reader.skipElement(this);           
     }
     
     /**
      * 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 {
        if(!map.isEmpty()) {
           return false;
        }
        return reader.isEmpty(this);           
     }
     
     /**
      * This is the string representation of the element. It is
      * used for debugging purposes. When evaluating the element
      * the to string can be used to print out the element name.
      * 
      * @return this returns a text description of the element
      */
     public String toString() {
        return String.format("element %s", getName());
     }
  }
  
  
  