/*
* 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 org.dom4j.*;
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.*;
import javax.xml.stream.events.Comment;
import javax.xml.stream.events.Namespace;
import javax.xml.stream.events.ProcessingInstruction;
import java.io.InputStream;
import java.io.Reader;
import java.util.Iterator;
/**
* 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/>
* <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://dom4j.sourceforge.net
*
* 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.
*/