/*
* PullReader.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 static org.xmlpull.v1.XmlPullParser.END_DOCUMENT;
import static org.xmlpull.v1.XmlPullParser.END_TAG;
import static org.xmlpull.v1.XmlPullParser.START_TAG;
import static org.xmlpull.v1.XmlPullParser.TEXT;
import org.xmlpull.v1.XmlPullParser;
/**
* The <code>PullReader</code> is used to provide an event reader
* thats makes use of the XML pull API. This provides the best
* performance on the Google Android platform. Providing support
* for the XML pull API ensures that a full DOM model does not
* need to be build for large documents. It also ensures that
* line numbers are available when each event is extracted.
*
* @author Niall Gallagher
*/
class PullReader implements EventReader {
/**
* This is the XML pull parser that is used to create events.
*/
private XmlPullParser parser;
/**
* This is the previous node that has been read by a peek.
*/
private EventNode peek;
/**
* Constructor for the <code>PullReader</code> object. This is
* provided an XML pull parser which has been initialized with
* the XML source document. Each even produced by this reader
* will be extracted from the provided XML pull parser.
*
* @param parser this is the parser used to create all events
*/
public PullReader(XmlPullParser parser) {
this.parser = parser;
}
/**
* 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 source XML
*/
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 {
int event = parser.next();
if(event != END_DOCUMENT) {
if(event == START_TAG){
return start();
}
if(event == TEXT) {
return text();
}
if(event == END_TAG) {
return end();
}
return read();
}
return null;
}
/**
* This is used to convert the next 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.
*
* @return this returns the text event from the XML pull parser
*/
private Text text() throws Exception {
return new Text(parser);
}
/**
* This is used to convert the next 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.
*
* @return this returns a start event created from the parser
*/
private Start start() throws Exception {
Start event = new Start(parser);
if(event.isEmpty()) {
return build(event);
}
return event;
}
/**
* 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) throws Exception {
int count = parser.getAttributeCount();
for(int i = 0; i < count; i++) {
Entry entry = attribute(i);
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 index this is the index of this attribute to create
*
* @return this returns an attribute created from the given object
*/
private Entry attribute(int index) throws Exception {
return new Entry(parser, index);
}
/**
* 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() throws Exception {
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 XML pull parser source that is used for this.
*/
private final XmlPullParser source;
/**
* This is the XML namespace reference used by the attribute.
*/
private final String reference;
/**
* This is the XML namespace prefix used by the attribute.
*/
private final String prefix;
/**
* This is the name that is used by this attribute.
*/
private final String name;
/**
* This is the value that is used by this attribute.
*/
private final String value;
/**
* 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 source this is the parser used to get the attribute
* @param index this is the index of the attribute to get
*/
public Entry(XmlPullParser source, int index) {
this.reference = source.getAttributeNamespace(index);
this.prefix = source.getAttributePrefix(index);
this.value = source.getAttributeValue(index);
this.name = source.getAttributeName(index);
this.source = source;
}
/**
* 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 name;
}
/**
* 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 value;
}
/**
* 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 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 reference;
}
/**
* 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 prefix;
}
/**
* This is used to return the node for the attribute. Because
* this represents an XML event the XML parser is returned.
* Returning the node helps with certain debugging issues.
*
* @return this will return the source object for this
*/
public Object getSource() {
return source;
}
}
/**
* 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 XML pull parser source that is used for this.
*/
private final XmlPullParser source;
/**
* This is the XML namespace reference used by the attribute.
*/
private final String reference;
/**
* This is the XML namespace prefix used by the attribute.
*/
private final String prefix;
/**
* This is the name that is used by this attribute.
*/
private final String name;
/**
* This is the line number where this element was read.
*/
private final int line;
/**
* 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 source this is the parser being wrapped by this
*/
public Start(XmlPullParser source) {
this.reference = source.getNamespace();
this.line = source.getLineNumber();
this.prefix = source.getPrefix();
this.name = source.getName();
this.source = source;
}
/**
* 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 line;
}
/**
* 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 name;
}
/**
* 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 reference;
}
/**
* 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 prefix;
}
/**
* This is used to return the node for the element. Because
* this represents an XML event the XML parser is returned.
* Returning the node helps with certain debugging issues.
*
* @return this will return the source object for this
*/
public Object getSource() {
return source;
}
}
/**
* 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 XML pull parser used to extract this text event.
*/
private final XmlPullParser source;
/**
* This is the text value that has been extracted from the XML.
*/
private final String 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 source this is the node that represents the text value
*/
public Text(XmlPullParser source){
this.text = source.getText();
this.source = source;
}
/**
* 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;
}
/**
* This is used to return the node for the text. Because
* this represents an XML event the XML parser is returned.
* Returning the node helps with certain debugging issues.
*
* @return this will return the source object for this
*/
public Object getSource() {
return source;
}
}
/**
* 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;
}
}
}