FileDocCategorySizeDatePackage
SimplePullParser.javaAPI DocAndroid 1.5 API10879Wed May 06 22:41:16 BST 2009com.google.wireless.gdata.parser.xml

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 final XmlPullParser
mParser
private String
mCurrentStartTag
Constructors Summary
public SimplePullParser(XmlPullParser parser)
Constructs a new SimplePullParser to parse the xml

param
parser the underlying parser to use


                    
     
    mParser = parser;
    mCurrentStartTag = null;
  
Methods Summary
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)
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;
  
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.StringnextTag(int parentDepth)
The same as nextTagOrText(int, StringBuilder) but ignores text blocks.

    return nextTagOrText(parentDepth, null /* ignore text */);
  
public java.lang.StringnextTagOrText(int parentDepth, java.lang.StringBuffer textBuffer)
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
textBuffer 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();
          // TODO: this is an example of how to do logging of the XML
//                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) {
          // TODO: this is an example of how to do logging of the XML
//                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) {
        return null;
      }

      if (eventType == XmlPullParser.TEXT && depth == parentDepth) {
        if (textBuffer == null) {
          continue;
        }
        String text = mParser.getText();
        textBuffer.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.StringBuffer textBuffer)
Consumes the rest of the children, accumulating any text at this level into the builder.

param
textBuffer
throws
IOException propogated from the XmlPullParser
throws
ParseException if there was an error parsing the xml.

    while (nextTagOrText(parentDepth, textBuffer) != null) {
    }