/*
 * StreamReader.java January 2010
 *
 * Copyright (C) 2010, 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 org.simpleframework.xml.stream;

import java.util.Iterator;

import javax.xml.stream.Location;
import javax.xml.stream.XMLEventReader;
import javax.xml.stream.events.Attribute;
import javax.xml.stream.events.Characters;
import javax.xml.stream.events.StartElement;
import javax.xml.stream.events.XMLEvent;

/**
 * The <code>StreamReader</code> object provides an implementation
 * for reading XML events using StAX. This will pretty much wrap
 * core StAX events as the framework is very closely related. The
 * implementation is basically required to ensure StAX events can
 * be digested by the core reader. For performance this will match
 * the underlying implementation closely as all this basically
 * does is act as a means to adapt the underlying framework events.
 * 
 * @author Niall Gallagher
 * 
 * @see org.simpleframework.xml.stream.StreamProvider
 */
class StreamReader implements EventReader {
   
   /**
    * This is the reader that is used to parse the XML document.
    */
   private XMLEventReader reader;
 
   /**
    * This is used to keep track of any events that were peeked.
    */
   private EventNode peek;
   
   /**
    * Constructor for the <code>StreamReader</code> object. This 
    * creates a reader that extracts events from the provided object.
    * All StAX events returned from the provided instance will be
    * adapted so that they can be digested by the core reader.
    * 
    * @param reader this is the reader used to parse the XML source
    */
   public StreamReader(XMLEventReader reader) {
      this.reader = reader;
   }

   /**
    * This is used to peek at the node from the document. This will
    * scan through the document, ignoring any comments to find the
    * next relevant XML event to acquire. Typically events will be
    * the start and end of an element, as well as any text nodes.
    * 
    * @return this returns the next event taken from the document
    */
   public EventNode peek() throws Exception {
      if(peek == null) {
         peek = next();
      }
      return peek;
   }   
   
   /**
    * This is used to take the next node from the document. This will
    * scan through the document, ignoring any comments to find the
    * next relevant XML event to acquire. Typically events will be
    * the start and end of an element, as well as any text nodes.
    * 
    * @return this returns the next event taken from the source XML
    */
   public EventNode next() throws Exception {
      EventNode next = peek;
      
      if(next == null) {
         next = read();
      } else {
         peek = null;
      }
      return next;
   }
      
   /**
    * This is used to read the next node from the document. This will
    * scan through the document, ignoring any comments to find the
    * next relevant XML event to acquire. Typically events will be
    * the start and end of an element, as well as any text nodes.
    * 
    * @return this returns the next event taken from the document 
    */
   private EventNode read() throws Exception {
      XMLEvent event = reader.nextEvent();
      
      if(event.isStartElement()) {
         return start(event);
      } 
      if(event.isCharacters()) {
         return text(event);
      } 
      if(event.isEndElement()) {
         return end();
      }
      return read();
   }
   
   /**
    * This is used to convert the provided event to a start event. The
    * conversion process ensures the node can be digested by the core
    * reader and used to provide an <code>InputNode</code> that can
    * be used to represent an XML elements within the source document.
    * 
    * @param event the event that is to be converted to a start event
    *
    * @return this returns a start event created from the given event
    */
   private Start start(XMLEvent event) {
      Start node = new Start(event);
      
      if(node.isEmpty()) {
         return build(node);
      }
      return node;
   }
   
   /**
    * This is used to build the attributes that are to be used to 
    * populate the start event. Populating the start event with the
    * attributes it contains is required so that each element will
    * contain its associated attributes. Only attributes that are
    * not reserved will be added to the start event.
    * 
    * @param event this is the start event that is to be populated
    * 
    * @return this returns a start event with its attributes
    */
   private Start build(Start event) {
      Iterator<Attribute> list = event.getAttributes();

      while (list.hasNext()) {
         Attribute node = list.next();
         Entry entry = attribute(node);
         
         if(!entry.isReserved()) {
            event.add(entry);
         }
      }
      return event;
   }
   
   /**
    * This is used to convert the provided object to an attribute. The
    * conversion process ensures the node can be digested by the core
    * reader and used to provide an <code>InputNode</code> that can
    * be used to represent an XML attribute within the source document.
    * 
    * @param entry the object that is to be converted to an attribute
    *
    * @return this returns an attribute created from the given object
    */
   private Entry attribute(Attribute entry) {
      return new Entry(entry);
   }

   /**
    * This is used to convert the provided event to a text event. The
    * conversion process ensures the node can be digested by the core
    * reader and used to provide an <code>InputNode</code> that can
    * be used to represent an XML attribute within the source document.
    * 
    * @param event the event that is to be converted to a text event
    *
    * @return this returns the text event created from the given event
    */
   private Text text(XMLEvent event) {
      return new Text(event);
   }
   
   /**
    * This is used to create an event to signify that an element has
    * just ended. End events are important as they allow the core
    * reader to determine if a node is still in context. This provides
    * a more convenient way to use <code>InputNode</code> objects as
    * they should only ever be able to extract their children. 
    * 
    * @return this returns an end event to signify an element close
    */
   private End end() {
      return new End();
   }
   
   /**
    * The <code>Entry</code> object is used to represent an attribute
    * within a start element. This holds the name and value of the
    * attribute as well as the namespace prefix and reference. These
    * details can be used to represent the attribute so that should
    * the core reader require these details they can be acquired.
    * 
    * @author Niall Gallagher
    */
   private static class Entry extends EventAttribute {
      
      /**
       * This is the attribute object representing this attribute.
       */
      private final Attribute entry;
      
      /**
       * Constructor for the <code>Entry</code> object. This creates
       * an attribute object that is used to extract the name, value
       * namespace prefix, and namespace reference from the provided
       * node. This is used to populate any start events created.
       * 
       * @param entry this is the node that represents the attribute
       */
      public Entry(Attribute entry) {
         this.entry = entry;
      }
      
      /**
       * This provides the name of the attribute. This will be the
       * name of the XML attribute without any namespace prefix. If
       * the name begins with "xml" then this attribute is reserved.
       * according to the namespaces for XML 1.0 specification.
       * 
       * @return this returns the name of this attribute object
       */
      public String getName() {
         return entry.getName().getLocalPart();
      }
      
      /**
       * This is used to acquire the namespace prefix associated with
       * this attribute. A prefix is used to qualify the attribute
       * within a namespace. So, if this has a prefix then it should
       * have a reference associated with it.
       * 
       * @return this returns the namespace prefix for the attribute
       */
      public String getPrefix() {
         return entry.getName().getPrefix();
      }
      
      /**
       * This is used to acquire the namespace reference that this 
       * attribute is in. A namespace is normally associated with an
       * attribute if that attribute is prefixed with a known token.
       * If there is no prefix then this will return null.
       * 
       * @return this provides the associated namespace reference
       */
      public String getReference() {
         return entry.getName().getNamespaceURI();
      }
      
      /**
       * This returns the value of the event. This will be the value
       * that the attribute contains. If the attribute does not have
       * a value then this returns null or an empty string.
       * 
       * @return this returns the value represented by this object
       */
      public String getValue() {
         return entry.getValue();
      }
      
      /**
       * This returns true if the attribute is reserved. An attribute
       * is considered reserved if it begins with "xml" according to 
       * the namespaces in XML 1.0 specification. Such attributes are
       * used for namespaces and other such details.
       *
       * @return this returns true if the attribute is reserved
       */
      public boolean isReserved() {
         return false;
      }
      
      /**
       * This is used to return the node for the attribute. Because 
       * this represents a StAX attribute the StAX object is returned.
       * Returning the node helps with certain debugging issues.
       * 
       * @return this will return the source object for this
       */
      public Object getSource() {
         return entry;
      }
   }
   
   /**
    * The <code>Start</code> object is used to represent the start of
    * an XML element. This will hold the attributes associated with
    * the element and will provide the name, the namespace reference
    * and the namespace prefix. For debugging purposes the source XML
    * element is provided for this start event.
    * 
    * @author Niall Gallagher
    */
   private static class Start extends EventElement {
      
      /**
       * This is the start element to be used by this start event.
       */
      private final StartElement element;
      
      /**
       * This is the element location used to detmine line numbers.
       */
      private final Location location;
      
      /**
       * Constructor for the <code>Start</code> object. This will 
       * wrap the provided node and expose the required details such
       * as the name, namespace prefix and namespace reference. The
       * provided element node can be acquired for debugging purposes.
       * 
       * @param event this is the element being wrapped by this
       */
      public Start(XMLEvent event) {
         this.element = event.asStartElement();
         this.location = event.getLocation();
      }
      
      /**
       * This is used to provide the line number the XML event was
       * encountered at within the XML document. If there is no line
       * number available for the node then this will return a -1.
       * 
       * @return this returns the line number if it is available
       */
      public int getLine() {
         return location.getLineNumber();
      }
      
      /**
       * This provides the name of the event. This will be the name 
       * of an XML element the event represents. If there is a prefix
       * associated with the element, this extracts that prefix.
       * 
       * @return this returns the name without the namespace prefix
       */
      public String getName() {
         return element.getName().getLocalPart();
      }
      
      /**
       * This is used to acquire the namespace prefix associated with
       * this node. A prefix is used to qualify an XML element or
       * attribute within a namespace. So, if this represents a text
       * event then a namespace prefix is not required.
       * 
       * @return this returns the namespace prefix for this event
       */
      public String getPrefix() {
         return element.getName().getPrefix();
      }
      
      /**
       * This is used to acquire the namespace reference that this 
       * node is in. A namespace is normally associated with an XML
       * element or attribute, so text events and element close events
       * are not required to contain any namespace references. 
       * 
       * @return this will provide the associated namespace reference
       */
      public String getReference() {
         return element.getName().getNamespaceURI();
      }
      
      /**
       * This is used to acquire the attributes associated with the
       * element. Providing the attributes in this format allows 
       * the reader to build a list of attributes for the event.
       * 
       * @return this returns the attributes associated with this
       */
      public Iterator<Attribute> getAttributes() {
         return element.getAttributes();
      }
      
      /**
       * This is used to return the node for the element. Because 
       * this represents a StAX event the StAX event is returned.
       * Returning the node helps with certain debugging issues.
       * 
       * @return this will return the source object for this
       */
      public Object getSource() {
         return element;
      }
   }
   
   /**
    * The <code>Text</code> object is used to represent a text event.
    * If wraps a node that holds text consumed from the document. 
    * These are used by <code>InputNode</code> objects to extract the
    * text values for elements For debugging this exposes the node.
    * 
    * @author Niall Gallagher
    */
   private static class Text extends EventToken {
      
      /**
       * This is the event that is used to represent the text value.
       */
      private final Characters text;
      
      /**
       * Constructor for the <code>Text</code> object. This creates
       * an event that provides text to the core reader. Text can be
       * in the form of a CDATA section or a normal text entry.
       * 
       * @param event this is the node that represents the text value
       */
      public Text(XMLEvent event) {
         this.text = event.asCharacters();
      }
      
      /**
       * This is true as this event represents a text token. Text 
       * tokens are required to provide a value only. So namespace
       * details and the node name will always return null.
       *  
       * @return this returns true as this event represents text  
       */
      public boolean isText() {
         return true;
      }
      
      /**
       * This returns the value of the event. This will return the
       * text value contained within the node. If there is no
       * text within the node this should return an empty string. 
       * 
       * @return this returns the value represented by this event
       */
      public String getValue() {
         return text.getData();
      }
      
      /**
       * This is used to return the node for the text. Because 
       * this represents a StAX event the StAX event is returned.
       * Returning the node helps with certain debugging issues.
       * 
       * @return this will return the source object for this
       */
      public Object getSource() {
         return text;
      }
   }
   
   /**
    * The <code>End</code> object is used to represent the end of an
    * element. It is used by the core reader to determine which nodes
    * are in context and which ones are out of context. This allows
    * the input nodes to determine if it can read any more children.
    * 
    * @author Niall Gallagher
    */
   private static class End extends EventToken {
 
      /**
       * This is true as this event represents an element end. Such
       * events are required by the core reader to determine if a 
       * node is still in context. This helps to determine if there
       * are any more children to be read from a specific node.
       * 
       * @return this returns true as this token represents an end
       */
      public boolean isEnd() {
         return true;
      }
   }
}
