Class XmlPullParser

java.lang.Object
com.codename1.backend.xml.XmlPullParser
public final class XmlPullParser extends Object

A small streaming XML parser: call next() until it answers END_DOCUMENT, reading the element name, attributes and text of each event as it goes.

XmlPullParser p = XmlPullParser.of(bytes);
for (int ev = p.next(); ev != XmlPullParser.END_DOCUMENT; ev = p.next()) {
    if (ev == XmlPullParser.START_ELEMENT && "item".equals(p.getName())) {
        String id = p.getAttributeValue("id");
    }
}

What it does:

  • Elements, attributes (single or double quoted) and text. An empty element (<a/>) is reported as a start followed immediately by its end.
  • Text and CDATA sections are reported together as one TEXT event per run of character data between two tags; whitespace is kept as written. Text outside the root element is ignored.
  • The five predefined entities (&amp; &lt; &gt; &quot; &apos;) and numeric character references (&#65;, &#x41;) are decoded, in text and in attribute values.
  • Namespaces are not resolved: a name is reported as written, prefix included (plist:dict, xmlns:a).
  • Comments, processing instructions and the XML declaration are skipped.

What it refuses, by construction rather than by configuration:

  • A document type declaration is skipped, never interpreted. Its internal subset is not read, so an entity it declares is never defined, an external one is never fetched, and a reference to either is an XmlException. That makes the parser immune to external entity (XXE) and entity expansion ("billion laughs") attacks: there is nothing to expand.
  • Elements nested deeper than setMaxDepth(int) (256 by default) are rejected, so a hostile document cannot make a recursive consumer such as XmlElement overflow its stack.
  • A document that is not well formed -- a mismatched end tag, an unclosed element, a second root element, a stray < -- is an XmlException.

Input is decoded as UTF-8; a leading byte order mark is skipped. The encoding of the XML declaration is not consulted.

  • Field Details

    • START_ELEMENT

      public static final int START_ELEMENT
      An element's start tag; getName() and the attribute accessors describe it.
      See Also:

    • END_ELEMENT

      public static final int END_ELEMENT
      An element's end tag; getName() names the element being closed.
      See Also:

    • TEXT

      public static final int TEXT
      Character data, with entities decoded; read it with getText().
      See Also:

    • END_DOCUMENT

      public static final int END_DOCUMENT
      The end of the document. Every later call to next() answers this again.
      See Also:

  • Method Details

    • of

      public static XmlPullParser of(String document)
      A parser over a document that is already a string.

    • of

      public static XmlPullParser of(byte[] utf8)
      A parser over UTF-8 encoded bytes.

    • of

      public static XmlPullParser of(byte[] data, int offset, int length)
      A parser over length UTF-8 encoded bytes of data starting at offset.

    • of

      public static XmlPullParser of(InputStream in) throws IOException
      A parser over the whole of in, read as UTF-8. The stream is read to its end but not closed.
      Throws:
      IOException

    • setMaxDepth

      public XmlPullParser setMaxDepth(int maxDepth)
      Sets the deepest element nesting accepted; deeper is an XmlException. Answers this parser.

    • getEventType

      public int getEventType()
      The current event: one of START_ELEMENT, END_ELEMENT, TEXT or END_DOCUMENT, or 0 before the first call to next().

    • getName

      public String getName()
      The element name of the current start or end event, prefix included, or null for any other event.

    • getText

      public String getText()
      The decoded character data of the current TEXT event, or null for any other event.

    • getDepth

      public int getDepth()
      The number of elements currently open: 1 inside the root element, 0 before and after it. After an END_ELEMENT event the closed element no longer counts.

    • getAttributeCount

      public int getAttributeCount()
      The number of attributes on the current start element; 0 for any other event.

    • getAttributeName

      public String getAttributeName(int index)
      The name of attribute index of the current start element, as written.

    • getAttributeValue

      public String getAttributeValue(int index)
      The decoded value of attribute index of the current start element.

    • getAttributeValue

      public String getAttributeValue(String attributeName)
      The decoded value of the attribute named attributeName (prefix included) on the current start element, or null when it has none.

    • next

      public int next() throws XmlException

      Advances to the next event and answers its type.

      Throws
      • XmlException: when the document is not well formed, nests too deeply, or references an entity this parser does not define.
      Throws:
      XmlException