FileDocCategorySizeDatePackage
SimplePullParser.javaAPI DocAndroid 1.5 API14437Wed May 06 22:41:56 BST 2009com.google.android.util

SimplePullParser

public class SimplePullParser extends Object
This is an abstraction of a pull parser that provides several benefits:
  • it is easier to use robustly because it makes it trivial to handle unexpected tags (which might have children)
  • it makes the handling of text (cdata) blocks more convenient
  • it provides convenient methods for getting a mandatory attribute (and throwing an exception if it is missing) or an optional attribute (and using a default value if it is missing)

Fields Summary
public static final String
TEXT_TAG
private String
mLogTag
private final XmlPullParser
mParser
private Closeable
source
private String
mCurrentStartTag
Constructors Summary
public SimplePullParser(InputStream stream, String encoding)
Constructs a new SimplePullParser to parse the stream

param
stream stream to parse
param
encoding the encoding to use


                            
        
               
        try {
            XmlPullParser parser = Xml.newPullParser();
            parser.setInput(stream, encoding);
            moveToStartDocument(parser);
            mParser = parser;
            mCurrentStartTag = null;
            source = stream;
        } catch (XmlPullParserException e) {
            throw new ParseException(e);
        }
    
public SimplePullParser(XmlPullParser parser)
Constructs a new SimplePullParser to parse the xml

param
parser the underlying parser to use

        mParser = parser;
        mCurrentStartTag = null;
        source = null;
    
public SimplePullParser(String xml)
Constructs a new SimplePullParser to parse the xml

param
xml the xml to parse

        this(new StringReader(xml));
    
public SimplePullParser(Reader reader)
Constructs a new SimplePullParser to parse the xml

param
reader a reader containing the xml

        try {
            XmlPullParser parser = Xml.newPullParser();
            parser.setInput(reader);
            moveToStartDocument(parser);
            mParser = parser;
            mCurrentStartTag = null;
            source = reader;
        } catch (XmlPullParserException e) {
            throw new ParseException(e);
        }
    
Methods Summary
public voidclose()
Close this SimplePullParser and any underlying resources (e.g., its InputStream or Reader source) used by this SimplePullParser.

        if (source != null) {
            try {
                source.close();
            } catch (IOException ioe) {
                // ignore
            }
        }
    
public java.lang.StringgetAttributeName(int i)
Returns the name of the nth attribute on the current element.

return
the name of the nth attribute on the current element

        return mParser.getAttributeName(i);
    
public java.lang.StringgetAttributeNamespace(int i)
Returns the namespace of the nth attribute on the current element.

return
the namespace of the nth attribute on the current element

        return mParser.getAttributeNamespace(i);
    
public intgetDepth()
Returns the depth of the current element. The depth is 0 before the first element has been returned, 1 after that, etc.

return
the depth of the current element

        return mParser.getDepth();
    
public intgetIntAttribute(java.lang.String namespace, java.lang.String name, int defaultValue)
Returns the string value of the named attribute. An exception will be thrown if the attribute is not a valid integer.

param
namespace the namespace of the attribute
param
name the name of the attribute
param
defaultValue the value to return if the attribute is not specified
return
the value of the attribute
throws
ParseException thrown if the attribute not a valid integer.

        String value = mParser.getAttributeValue(namespace, name);
        if (null == value) return defaultValue;
        try {
            return Integer.parseInt(value);
        } catch (NumberFormatException e) {
            throw new ParseException("Cannot parse '" + value + "' as an integer");
        }
    
public intgetIntAttribute(java.lang.String namespace, java.lang.String name)
Returns the string value of the named attribute. An exception will be thrown if the attribute is not present or is not a valid integer.

param
namespace the namespace of the attribute
param
name the name of the attribute @return the value of the attribute
throws
ParseException thrown if the attribute is missing or not a valid integer.

        String value = getStringAttribute(namespace, name);
        try {
            return Integer.parseInt(value);
        } catch (NumberFormatException e) {
            throw new ParseException("Cannot parse '" + value + "' as an integer");
        }
    
public longgetLongAttribute(java.lang.String namespace, java.lang.String name, long defaultValue)
Returns the string value of the named attribute. An exception will be thrown if the attribute is not a valid long.

param
namespace the namespace of the attribute
param
name the name of the attribute @return the value of the attribute
throws
ParseException thrown if the attribute is not a valid long.

        String value = mParser.getAttributeValue(namespace, name);
        if (null == value) return defaultValue;
        try {
            return Long.parseLong(value);
        } catch (NumberFormatException e) {
            throw new ParseException("Cannot parse '" + value + "' as a long");
        }
    
public longgetLongAttribute(java.lang.String namespace, java.lang.String name)
Returns the string value of the named attribute. An exception will be thrown if the attribute is not present or is not a valid long.

param
namespace the namespace of the attribute
param
name the name of the attribute @return the value of the attribute
throws
ParseException thrown if the attribute is missing or not a valid long.

        String value = getStringAttribute(namespace, name);
        try {
            return Long.parseLong(value);
        } catch (NumberFormatException e) {
            throw new ParseException("Cannot parse '" + value + "' as a long");
        }
    
public java.lang.StringgetStringAttribute(java.lang.String namespace, java.lang.String name, java.lang.String defaultValue)
Returns the string value of the named attribute.

param
namespace the namespace of the attribute
param
name the name of the attribute
param
defaultValue the value to return if the attribute is not specified
return
the value of the attribute

        String value = mParser.getAttributeValue(namespace, name);
        if (null == value) return defaultValue;
        return value;
    
public java.lang.StringgetStringAttribute(java.lang.String namespace, java.lang.String name)
Returns the string value of the named attribute. An exception will be thrown if the attribute is not present.

param
namespace the namespace of the attribute
param
name the name of the attribute @return the value of the attribute
throws
ParseException thrown if the attribute is missing

        String value = mParser.getAttributeValue(namespace, name);
        if (null == value) {
            throw new ParseException(
                    "missing '" + name + "' attribute on '" + mCurrentStartTag + "' element");
        }
        return value;
    
private static voidmoveToStartDocument(org.xmlpull.v1.XmlPullParser parser)

        int eventType;
        eventType = parser.getEventType();
        if (eventType != XmlPullParser.START_DOCUMENT) {
            throw new XmlPullParserException("Not at start of response");
        }
    
public java.lang.StringnextTag(int parentDepth)
The same as nextTagOrTexxt(int, StringBuilder) but ignores text blocks.

        return nextTagOrText(parentDepth, null /* ignore text */);
    
public java.lang.StringnextTagOrText(int parentDepth, java.lang.StringBuilder textBuilder)
Returns the tag of the next element whose depth is parentDepth plus one or null if there are no more such elements before the next start tag. When this returns, getDepth() and all methods relating to attributes will refer to the element whose tag is returned.

param
parentDepth the depth of the parrent of the item to be returned
param
textBuilder if null then text blocks will be ignored. If non-null then text blocks will be added to the builder and TEXT_TAG will be returned when one is found
return
the next of the next child element's tag, TEXT_TAG if a text block is found, or null if there are no more child elements or DATA blocks
throws
IOException propogated from the underlying parser
throws
ParseException if there was an error parsing the xml.

        while (true) {
            int eventType = 0;
            try {
                eventType = mParser.next();
            } catch (XmlPullParserException e) {
                throw new ParseException(e);
            }
            int depth = mParser.getDepth();
            mCurrentStartTag = null;

            if (eventType == XmlPullParser.START_TAG && depth == parentDepth + 1) {
                mCurrentStartTag = mParser.getName();
                if (mLogTag != null && Log.isLoggable(mLogTag, Log.DEBUG)) {
                    StringBuilder sb = new StringBuilder();
                    for (int i = 0; i < depth; i++) sb.append("  ");
                    sb.append("<").append(mParser.getName());
                    int count = mParser.getAttributeCount();
                    for (int i = 0; i < count; i++) {
                        sb.append(" ");
                        sb.append(mParser.getAttributeName(i));
                        sb.append("=\"");
                        sb.append(mParser.getAttributeValue(i));
                        sb.append("\"");
                    }
                    sb.append(">");
                    Log.d(mLogTag, sb.toString());
                }
                return mParser.getName();
            }

            if (eventType == XmlPullParser.END_TAG && depth == parentDepth) {
                if (mLogTag != null && Log.isLoggable(mLogTag, Log.DEBUG)) {
                    StringBuilder sb = new StringBuilder();
                    for (int i = 0; i < depth; i++) sb.append("  ");
                    sb.append("</>"); // Not quite valid xml but it gets the job done.
                    Log.d(mLogTag, sb.toString());
                }
                return null;
            }

            if (eventType == XmlPullParser.END_DOCUMENT && parentDepth == 0) {
                // we could just rely on the caller calling close(), which it should, but try
                // to auto-close for clients that might have missed doing so.
                if (source != null) {
                    source.close();
                    source = null;
                }
                return null;
            }

            if (eventType == XmlPullParser.TEXT && depth == parentDepth) {
                if (textBuilder == null) {
                    continue;
                }
                String text = mParser.getText();
                textBuilder.append(text);
                return TEXT_TAG;
            }
        }
    
public intnumAttributes()
Returns the number of attributes on the current element.

return
the number of attributes on the current element

        return mParser.getAttributeCount();
    
public voidreadRemainingText(int parentDepth, java.lang.StringBuilder textBuilder)
Consumes the rest of the children, accumulating any text at this level into the builder.

param
textBuilder the builder to contain any text
throws
IOException propogated from the XmlPullParser
throws
ParseException if there was an error parsing the xml.

        while (nextTagOrText(parentDepth, textBuilder) != null) {
        }
    
public voidsetLogTag(java.lang.String logTag)
Enables logging to the provided log tag. A basic representation of the xml will be logged as the xml is parsed. No logging is done unless this is called.

param
logTag the log tag to use when logging

        mLogTag = logTag;