/*
    * Copyright 2001-2005 (C) MetaStuff, Ltd. All Rights Reserved.
    *
    * This software is open source.
    * See the bottom of this file for the licence.
    */
   
   package org.dom4j.io;
   
  import java.io.InputStream;
  import java.io.Reader;
  import java.util.Iterator;
  
  import javax.xml.namespace.QName;
  import javax.xml.stream.XMLEventReader;
  import javax.xml.stream.XMLInputFactory;
  import javax.xml.stream.XMLStreamConstants;
  import javax.xml.stream.XMLStreamException;
  import javax.xml.stream.events.Attribute;
  import javax.xml.stream.events.Characters;
  import javax.xml.stream.events.Comment;
  import javax.xml.stream.events.EndElement;
  import javax.xml.stream.events.EntityReference;
  import javax.xml.stream.events.Namespace;
  import javax.xml.stream.events.ProcessingInstruction;
  import javax.xml.stream.events.StartDocument;
  import javax.xml.stream.events.StartElement;
  import javax.xml.stream.events.XMLEvent;
  
  import org.dom4j.CharacterData;
  import org.dom4j.Document;
  import org.dom4j.DocumentFactory;
  import org.dom4j.Element;
  import org.dom4j.Entity;
  import org.dom4j.Node;
  
  /***
   * Reads a DOM4J {@link Document}, as well as other {@link Node}s, from a StAX
   * {@link XMLEventReader}.
   * 
   * @author Christian Niles
   */
  public class STAXEventReader {
      /*** Reference to the DocumentFactory used to build DOM4J nodes. */
      private DocumentFactory factory;
  
      /*** A StAX input factory, used to construct streams from IO streams. */
      private XMLInputFactory inputFactory = XMLInputFactory.newInstance();
  
      /***
       * Constructs a default <code>STAXEventReader</code> instance with a
       * default {@link DocumentFactory}.
       */
      public STAXEventReader() {
          this.factory = DocumentFactory.getInstance();
      }
  
      /***
       * Constructs a <code>STAXEventReader</code> instance that uses the
       * specified {@link DocumentFactory}to construct DOM4J {@link Node}s.
       * 
       * @param factory
       *            The DocumentFactory to use when constructing DOM4J nodes, or
       *            <code>null</code> if a default should be used.
       */
      public STAXEventReader(DocumentFactory factory) {
          if (factory != null) {
              this.factory = factory;
          } else {
              this.factory = DocumentFactory.getInstance();
          }
      }
  
      /***
       * Sets the DocumentFactory to be used when constructing DOM4J nodes.
       * 
       * @param documentFactory
       *            The DocumentFactory to use when constructing DOM4J nodes, or
       *            <code>null</code> if a default should be used.
       */
      public void setDocumentFactory(DocumentFactory documentFactory) {
          if (documentFactory != null) {
              this.factory = documentFactory;
          } else {
              this.factory = DocumentFactory.getInstance();
          }
      }
  
      /***
       * Constructs a StAX event stream from the provided I/O stream and reads a
       * DOM4J document from it.
       * 
       * @param is
       *            The I/O stream from which the Document will be read.
       * 
       * @return The Document that was read from the stream.
       * 
       * @throws XMLStreamException
       *             If an error occurs reading content from the stream.
      */
     public Document readDocument(InputStream is) throws XMLStreamException {
         return readDocument(is, null);
     }
 
     /***
      * Constructs a StAX event stream from the provided I/O character stream and
      * reads a DOM4J document from it.
      * 
      * @param reader
      *            The character stream from which the Document will be read.
      * 
      * @return The Document that was read from the stream.
      * 
      * @throws XMLStreamException
      *             If an error occurs reading content from the stream.
      */
     public Document readDocument(Reader reader) throws XMLStreamException {
         return readDocument(reader, null);
     }
 
     /***
      * Constructs a StAX event stream from the provided I/O stream and reads a
      * DOM4J document from it.
      * 
      * @param is
      *            The I/O stream from which the Document will be read.
      * @param systemId
      *            A system id used to resolve entities.
      * 
      * @return The Document that was read from the stream.
      * 
      * @throws XMLStreamException
      *             If an error occurs reading content from the stream.
      */
     public Document readDocument(InputStream is, String systemId)
             throws XMLStreamException {
         XMLEventReader eventReader = inputFactory.createXMLEventReader(
                 systemId, is);
 
         try {
             return readDocument(eventReader);
         } finally {
             eventReader.close();
         }
     }
 
     /***
      * Constructs a StAX event stream from the provided I/O character stream and
      * reads a DOM4J document from it.
      * 
      * @param reader
      *            The character stream from which the Document will be read.
      * @param systemId
      *            A system id used to resolve entities.
      * 
      * @return The Document that was read from the stream.
      * 
      * @throws XMLStreamException
      *             If an error occurs reading content from the stream.
      */
     public Document readDocument(Reader reader, String systemId)
             throws XMLStreamException {
         XMLEventReader eventReader = inputFactory.createXMLEventReader(
                 systemId, reader);
 
         try {
             return readDocument(eventReader);
         } finally {
             eventReader.close();
         }
     }
 
     /***
      * Reads a {@link Node}from the event stream. If the next event is a
      * {@link StartElement}, all events until the closing {@link EndElement}
      * will be read, and the resulting nodes will be added to the returned
      * {@link Element}.
      * 
      * <p>
      * <strong>Pre-Conditions </strong>: The stream must be positioned before an
      * event other than an <code>EndElement</code>,<code>EndDocument</code>,
      * or any DTD-related events, which are not currently supported.
      * </p>
      * 
      * @param reader
      *            The reader from which events will be read.
      * 
      * @return A DOM4J {@link Node}constructed from the read events.
      * 
      * @throws XMLStreamException
      *             If an error occurs reading from the stream, or the stream was
      *             positioned before an unsupported event.
      */
     public Node readNode(XMLEventReader reader) throws XMLStreamException {
         XMLEvent event = reader.peek();
 
         if (event.isStartElement()) {
             return readElement(reader);
         } else if (event.isCharacters()) {
             return readCharacters(reader);
         } else if (event.isStartDocument()) {
             return readDocument(reader);
         } else if (event.isProcessingInstruction()) {
             return readProcessingInstruction(reader);
         } else if (event.isEntityReference()) {
             return readEntityReference(reader);
         } else if (event.isAttribute()) {
             return readAttribute(reader);
         } else if (event.isNamespace()) {
             return readNamespace(reader);
         } else {
             throw new XMLStreamException("Unsupported event: " + event);
         }
     }
 
     /***
      * Reads a DOM4J {@link Document}from the provided stream. The stream
      * should be positioned at the start of a document, or before a {@link
      * StartElement} event.
      * 
      * @param reader
      *            The event stream from which to read the {@link Document}.
      * 
      * @return The {@link Document}that was read from the stream.
      * 
      * @throws XMLStreamException
      *             If an error occurs reading events from the stream.
      */
     public Document readDocument(XMLEventReader reader)
             throws XMLStreamException {
         Document doc = null;
 
         while (reader.hasNext()) {
             XMLEvent nextEvent = reader.peek();
             int type = nextEvent.getEventType();
 
             switch (type) {
                 case XMLStreamConstants.START_DOCUMENT:
 
                     StartDocument event = (StartDocument) reader.nextEvent();
 
                     if (doc == null) {
                         // create document
                         if (event.encodingSet()) {
                             String encodingScheme = event
                                     .getCharacterEncodingScheme();
                             doc = factory.createDocument(encodingScheme);
                         } else {
                             doc = factory.createDocument();
                         }
                     } else {
                         // duplicate or misplaced xml declaration
                         String msg = "Unexpected StartDocument event";
                         throw new XMLStreamException(msg, event.getLocation());
                     }
 
                     break;
 
                 case XMLStreamConstants.END_DOCUMENT:
                 case XMLStreamConstants.SPACE:
                 case XMLStreamConstants.CHARACTERS:
 
                     // skip end document and space outside the root element
                     reader.nextEvent();
 
                     break;
 
                 default:
 
                     if (doc == null) {
                         // create document
                         doc = factory.createDocument();
                     }
 
                     Node n = readNode(reader);
                     doc.add(n);
             }
         }
 
         return doc;
     }
 
     /***
      * Reads a DOM4J Element from the provided event stream. The stream must be
      * positioned before an {@link StartElement}event. In addition to the
      * initial start event, all events up to and including the closing {@link
      * EndElement} will be read, and included with the returned element.
      * 
      * @param eventReader
      *            The event stream from which to read the Element.
      * 
      * @return The Element that was read from the stream.
      * 
      * @throws XMLStreamException
      *             If an error occured reading events from the stream, or the
      *             stream was not positioned before a {@linkStartElement}event.
      */
     public Element readElement(XMLEventReader eventReader)
             throws XMLStreamException {
         XMLEvent event = eventReader.peek();
 
         if (event.isStartElement()) {
             // advance the reader and get the StartElement event
             StartElement startTag = eventReader.nextEvent().asStartElement();
             Element elem = createElement(startTag);
 
             // read element content
             while (true) {
                 if (!eventReader.hasNext()) {
                     String msg = "Unexpected end of stream while reading"
                             + " element content";
                     throw new XMLStreamException(msg);
                 }
 
                 XMLEvent nextEvent = eventReader.peek();
 
                 if (nextEvent.isEndElement()) {
                     EndElement endElem = eventReader.nextEvent().asEndElement();
 
                     if (!endElem.getName().equals(startTag.getName())) {
                         throw new XMLStreamException("Expected "
                                 + startTag.getName() + " end-tag, but found"
                                 + endElem.getName());
                     }
 
                     break;
                 }
 
                 Node child = readNode(eventReader);
                 elem.add(child);
             }
 
             return elem;
         } else {
             throw new XMLStreamException("Expected Element event, found: "
                     + event);
         }
     }
 
     /***
      * Constructs a DOM4J Attribute from the provided event stream. The stream
      * must be positioned before an {@link Attribute}event.
      * 
      * @param reader
      *            The event stream from which to read the Attribute.
      * 
      * @return The Attribute that was read from the stream.
      * 
      * @throws XMLStreamException
      *             If an error occured reading events from the stream, or the
      *             stream was not positioned before an {@linkAttribute}event.
      */
     public org.dom4j.Attribute readAttribute(XMLEventReader reader)
             throws XMLStreamException {
         XMLEvent event = reader.peek();
 
         if (event.isAttribute()) {
             Attribute attr = (Attribute) reader.nextEvent();
 
             return createAttribute(null, attr);
         } else {
             throw new XMLStreamException("Expected Attribute event, found: "
                     + event);
         }
     }
 
     /***
      * Constructs a DOM4J Namespace from the provided event stream. The stream
      * must be positioned before a {@link Namespace}event.
      * 
      * @param reader
      *            The event stream from which to read the Namespace.
      * 
      * @return The Namespace that was read from the stream.
      * 
      * @throws XMLStreamException
      *             If an error occured reading events from the stream, or the
      *             stream was not positioned before a {@linkNamespace}event.
      */
     public org.dom4j.Namespace readNamespace(XMLEventReader reader)
             throws XMLStreamException {
         XMLEvent event = reader.peek();
 
         if (event.isNamespace()) {
             Namespace ns = (Namespace) reader.nextEvent();
 
             return createNamespace(ns);
         } else {
             throw new XMLStreamException("Expected Namespace event, found: "
                     + event);
         }
     }
 
     /***
      * Constructs a DOM4J Text or CDATA section from the provided event stream.
      * The stream must be positioned before a {@link Characters}event.
      * 
      * @param reader
      *            The event stream from which to read the Text or CDATA.
      * 
      * @return The Text or CDATA that was read from the stream.
      * 
      * @throws XMLStreamException
      *             If an error occured reading events from the stream, or the
      *             stream was not positioned before a {@linkCharacters}event.
      */
     public CharacterData readCharacters(XMLEventReader reader)
             throws XMLStreamException {
         XMLEvent event = reader.peek();
 
         if (event.isCharacters()) {
             Characters characters = reader.nextEvent().asCharacters();
 
             return createCharacterData(characters);
         } else {
             throw new XMLStreamException("Expected Characters event, found: "
                     + event);
         }
     }
 
     /***
      * Constructs a DOM4J Comment from the provided event stream. The stream
      * must be positioned before a {@link Comment}event.
      * 
      * @param reader
      *            The event stream from which to read the Comment.
      * 
      * @return The Comment that was read from the stream.
      * 
      * @throws XMLStreamException
      *             If an error occured reading events from the stream, or the
      *             stream was not positioned before a {@linkComment}event.
      */
     public org.dom4j.Comment readComment(XMLEventReader reader)
             throws XMLStreamException {
         XMLEvent event = reader.peek();
 
         if (event instanceof Comment) {
             return createComment((Comment) reader.nextEvent());
         } else {
             throw new XMLStreamException("Expected Comment event, found: "
                     + event);
         }
     }
 
     /***
      * Constructs a DOM4J Entity from the provided event stream. The stream must
      * be positioned before an {@link EntityReference}event.
      * 
      * @param reader
      *            The event stream from which to read the {@link
      *            EntityReference}.
      * 
      * @return The {@link org.dom4j.Entity}that was read from the stream.
      * 
      * @throws XMLStreamException
      *             If an error occured reading events from the stream, or the
      *             stream was not positioned before an {@linkEntityReference}
      *             event.
      */
     public Entity readEntityReference(XMLEventReader reader)
             throws XMLStreamException {
         XMLEvent event = reader.peek();
 
         if (event.isEntityReference()) {
             EntityReference entityRef = (EntityReference) reader.nextEvent();
 
             return createEntity(entityRef);
         } else {
             throw new XMLStreamException("Expected EntityRef event, found: "
                     + event);
         }
     }
 
     /***
      * Constructs a DOM4J ProcessingInstruction from the provided event stream.
      * The stream must be positioned before a {@link ProcessingInstruction}
      * event.
      * 
      * @param reader
      *            The event stream from which to read the ProcessingInstruction.
      * 
      * @return The ProcessingInstruction that was read from the stream.
      * 
      * @throws XMLStreamException
      *             If an error occured reading events from the stream, or the
      *             stream was not positioned before a {@link
      *             ProcessingInstruction} event.
      */
     public org.dom4j.ProcessingInstruction readProcessingInstruction(
             XMLEventReader reader) throws XMLStreamException {
         XMLEvent event = reader.peek();
 
         if (event.isProcessingInstruction()) {
             ProcessingInstruction pi = (ProcessingInstruction) reader
                     .nextEvent();
 
             return createProcessingInstruction(pi);
         } else {
             throw new XMLStreamException("Expected PI event, found: " + event);
         }
     }
 
     /***
      * Constructs a new DOM4J Element from the provided StartElement event. All
      * attributes and namespaces will be added to the returned element.
      * 
      * @param startEvent
      *            The StartElement event from which to construct the new DOM4J
      *            Element.
      * 
      * @return The Element constructed from the provided StartElement event.
      */
     public Element createElement(StartElement startEvent) {
         QName qname = startEvent.getName();
         org.dom4j.QName elemName = createQName(qname);
 
         Element elem = factory.createElement(elemName);
 
         // create attributes
         for (Iterator i = startEvent.getAttributes(); i.hasNext();) {
             Attribute attr = (Attribute) i.next();
             elem.addAttribute(createQName(attr.getName()), attr.getValue());
         }
 
         // create namespaces
         for (Iterator i = startEvent.getNamespaces(); i.hasNext();) {
             Namespace ns = (Namespace) i.next();
             elem.addNamespace(ns.getPrefix(), ns.getNamespaceURI());
         }
 
         return elem;
     }
 
     /***
      * Constructs a new DOM4J Attribute from the provided StAX Attribute event.
      * 
      * @param elem
      *            DOCUMENT ME!
      * @param attr
      *            The Attribute event from which to construct the new DOM4J
      *            Attribute.
      * 
      * @return The Attribute constructed from the provided Attribute event.
      */
     public org.dom4j.Attribute createAttribute(Element elem, Attribute attr) {
         return factory.createAttribute(elem, createQName(attr.getName()), attr
                 .getValue());
     }
 
     /***
      * Constructs a new DOM4J Namespace from the provided StAX Namespace event.
      * 
      * @param ns
      *            The Namespace event from which to construct the new DOM4J
      *            Namespace.
      * 
      * @return The Namespace constructed from the provided Namespace event.
      */
     public org.dom4j.Namespace createNamespace(Namespace ns) {
         return factory.createNamespace(ns.getPrefix(), ns.getNamespaceURI());
     }
 
     /***
      * Constructs a new DOM4J Text or CDATA object from the provided Characters
      * event.
      * 
      * @param characters
      *            The Characters event from which to construct the new DOM4J
      *            Text or CDATA object.
      * 
      * @return The Text or CDATA object constructed from the provided Characters
      *         event.
      */
     public CharacterData createCharacterData(Characters characters) {
         String data = characters.getData();
 
         if (characters.isCData()) {
             return factory.createCDATA(data);
         } else {
             return factory.createText(data);
         }
     }
 
     /***
      * Constructs a new DOM4J Comment from the provided StAX Comment event.
      * 
      * @param comment
      *            The Comment event from which to construct the new DOM4J
      *            Comment.
      * 
      * @return The Comment constructed from the provided Comment event.
      */
     public org.dom4j.Comment createComment(Comment comment) {
         return factory.createComment(comment.getText());
     }
 
     /***
      * Constructs a new DOM4J Entity from the provided StAX EntityReference
      * event.
      * 
      * @param entityRef
      *            The EntityReference event from which to construct the new
      *            DOM4J Entity.
      * 
      * @return The Entity constructed from the provided EntityReference event.
      */
     public org.dom4j.Entity createEntity(EntityReference entityRef) {
         return factory.createEntity(entityRef.getName(), entityRef
                 .getDeclaration().getReplacementText());
     }
 
     /***
      * Constructs a new DOM4J ProcessingInstruction from the provided StAX
      * ProcessingInstruction event.
      * 
      * @param pi
      *            The ProcessingInstruction event from which to construct the
      *            new DOM4J ProcessingInstruction.
      * 
      * @return The ProcessingInstruction constructed from the provided
      *         ProcessingInstruction event.
      */
     public org.dom4j.ProcessingInstruction createProcessingInstruction(
             ProcessingInstruction pi) {
         return factory
                 .createProcessingInstruction(pi.getTarget(), pi.getData());
     }
 
     /***
      * Constructs a new DOM4J QName from the provided JAXP QName.
      * 
      * @param qname
      *            The JAXP QName from which to create a DOM4J QName.
      * 
      * @return The newly constructed DOM4J QName.
      */
     public org.dom4j.QName createQName(QName qname) {
         return factory.createQName(qname.getLocalPart(), qname.getPrefix(),
                 qname.getNamespaceURI());
     }
 }
 
 /*
  * Redistribution and use of this software and associated documentation
  * ("Software"), with or without modification, are permitted provided that the
  * following conditions are met:
  * 
  * 1. Redistributions of source code must retain copyright statements and
  * notices. Redistributions must also contain a copy of this document.
  * 
  * 2. Redistributions in binary form must reproduce the above copyright notice,
  * this list of conditions and the following disclaimer in the documentation
  * and/or other materials provided with the distribution.
  * 
  * 3. The name "DOM4J" must not be used to endorse or promote products derived
  * from this Software without prior written permission of MetaStuff, Ltd. For
  * written permission, please contact dom4j-info@metastuff.com.
  * 
  * 4. Products derived from this Software may not be called "DOM4J" nor may
  * "DOM4J" appear in their names without prior written permission of MetaStuff,
  * Ltd. DOM4J is a registered trademark of MetaStuff, Ltd.
  * 
  * 5. Due credit should be given to the DOM4J Project - http://www.dom4j.org
  * 
  * THIS SOFTWARE IS PROVIDED BY METASTUFF, LTD. AND CONTRIBUTORS ``AS IS'' AND
  * ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  * ARE DISCLAIMED. IN NO EVENT SHALL METASTUFF, LTD. OR ITS CONTRIBUTORS BE
  * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  * POSSIBILITY OF SUCH DAMAGE.
  * 
  * Copyright 2001-2005 (C) MetaStuff, Ltd. All Rights Reserved.
  */