org.gjt.xpp.impl.pullparser

Class PullParser

Implemented Interfaces:
XmlPullParser, XmlPullParserBufferControl, XmlPullParserEventPosition

public class PullParser
extends java.lang.Object
implements XmlPullParser, XmlPullParserBufferControl, XmlPullParserEventPosition

XML Pull Parser (XPP) allows to pull XML events from input stream. Advantages: Limitations:
Author:
Aleksander Slominski

Field Summary

protected static boolean
CHECK_ATTRIB_UNIQ
Should attribute uniqueness be checked for attributes as in specified XML and NS specifications?
protected static boolean
USE_QNAMEBUF
protected Attribute[]
attrPos
temporary array of current attributes
protected int
attrPosEnd
index for last attribute in attrPos array
protected int
attrPosSize
size of attrPos array
protected String
elContent
Content of current element if in CONTENT state
protected ElementContent[]
elStack
temprary array to keep ElementContent stack
protected int
elStackDepth
how many elements are on elStack
protected int
elStackSize
size of elStack array
protected boolean
emptyElement
Have we read empty element?
protected int
eventEnd
end position of current event in tokenizer biffer
protected int
eventStart
start position of current event in tokenizer biffer
protected Hashtable
prefix2Ns
mapping of names prefixes to uris
protected boolean
reportNsAttribs
should parser report namespace xmlns* attributes ?
protected boolean
seenRootElement
Have we seen root element
protected byte
state
what is current event type as returned from next()?
protected boolean
supportNs
should parser support namespaces?
protected byte
token
what is current token returned from tokeizer
protected Tokenizer
tokenizer
XML tokenizer that is doing actual tokenizning of input stream.

Fields inherited from interface org.gjt.xpp.XmlPullParser

CONTENT, END_DOCUMENT, END_TAG, START_TAG

Constructor Summary

PullParser()
Create instance of pull parser.

Method Summary

protected void
ensureAttribs(int size)
Make sure that in attributes temporary array is enough space.
protected void
ensureCapacity(int size)
Make sure that we have enough space to keep element stack if passed size.
int
getBufferShrinkOffset()
int
getColumnNumber()
int
getContentLength()
Return how big is content.
int
getDepth()
Returns the current depth of the element.
char[]
getEventBuffer()
int
getEventEnd()
int
getEventStart()
byte
getEventType()
Returns the type of the current element (START_TAG, END_TAG, CONTENT, etc)
int
getHardLimit()
int
getLineNumber()
String
getLocalName()
Returns the local name of the current element (current event must be START_TAG or END_TAG)
String
getNamespaceUri()
Returns the namespace URI of the current element Returns null if not applicable (current event must be START_TAG or END_TAG)
int
getNamespacesLength(int depth)
String
getPosDesc()
Return string describing current position of parser in input stream.
String
getPrefix()
Returns the prefix of the current element or null if elemet has no prefix.
String
getQNameLocal(String qName)
Return local part of qname.
String
getQNameUri(String qName)
Return uri part of qname.
String
getRawName()
Returns the raw name (prefix + ':' + localName) of the current element (current event must be START_TAG or END_TAG)
int
getSoftLimit()
boolean
isAllowedMixedContent()
Is mixed element context allowed?
boolean
isBufferShrinkable()
boolean
isNamespaceAttributesReporting()
Is parser going to report namespace attributes (xmlns*) ?
boolean
isNamespaceAware()
Is parser namespace aware?
boolean
isWhitespaceContent()
Return true if just read CONTENT contained only white spaces.
byte
next()
This is key method - it reads more from input stream and returns next event type (such as START_TAG, END_TAG, CONTENT).
String
readContent()
Return String that contains just read CONTENT.
void
readEndTag(XmlEndTag etag)
Read value of just read END_TAG into passed as argument EndTag.
void
readNamespacesPrefixes(int depth, String[] prefixes, int off, int len)
Return namespace prefixes for element at depth
void
readNamespacesUris(int depth, String[] uris, int off, int len)
Return namespace URIs for element at depth
byte
readNode(XmlNode node)
Read subtree into node: call readNodeWithoutChildren and then parse subtree adding children (values obtained with readXontent or readNodeWithoutChildren).
void
readNodeWithoutChildren(XmlNode node)
Read node: it calls readStartTag and then if parser is namespaces aware currently declared nemaspeces will be added and defaultNamespace will be set.
void
readStartTag(XmlStartTag stag)
Read value of just read START_TAG into passed as argument StartTag.
void
reset()
Reset parser state so it can be used to parse new
protected void
resetState()
void
setAllowedMixedContent(boolean enable)
Allow for mixed element content.
void
setBufferShrinkable(boolean shrinkable)
void
setHardLimit(int value)
void
setInput(Reader reader)
Reset parser and set new input.
void
setInput(char[] buf)
Reset parser and set new input.
void
setInput(char[] buf, int off, int len)
Set the input for parser.
void
setNamespaceAttributesReporting(boolean enable)
Make parser to report xmlns* attributes.
void
setNamespaceAware(boolean awareness)
Set support of namespaces.
void
setSoftLimit(int value)
byte
skipNode()
If parser has just read start tag it allows to skip whoole subtree contined in this element.

Field Details

CHECK_ATTRIB_UNIQ

protected static final boolean CHECK_ATTRIB_UNIQ
Should attribute uniqueness be checked for attributes as in specified XML and NS specifications?
Field Value:
true

USE_QNAMEBUF

protected static final boolean USE_QNAMEBUF
Field Value:
false

attrPos

protected Attribute[] attrPos
temporary array of current attributes

attrPosEnd

protected int attrPosEnd
index for last attribute in attrPos array

attrPosSize

protected int attrPosSize
size of attrPos array

elContent

protected String elContent
Content of current element if in CONTENT state

elStack

protected ElementContent[] elStack
temprary array to keep ElementContent stack

elStackDepth

protected int elStackDepth
how many elements are on elStack

elStackSize

protected int elStackSize
size of elStack array

emptyElement

protected boolean emptyElement
Have we read empty element?

eventEnd

protected int eventEnd
end position of current event in tokenizer biffer

eventStart

protected int eventStart
start position of current event in tokenizer biffer

prefix2Ns

protected Hashtable prefix2Ns
mapping of names prefixes to uris

reportNsAttribs

protected boolean reportNsAttribs
should parser report namespace xmlns* attributes ?

seenRootElement

protected boolean seenRootElement
Have we seen root element

state

protected byte state
what is current event type as returned from next()?

supportNs

protected boolean supportNs
should parser support namespaces?

token

protected byte token
what is current token returned from tokeizer

tokenizer

protected Tokenizer tokenizer
XML tokenizer that is doing actual tokenizning of input stream.

Constructor Details

PullParser

public PullParser()
Create instance of pull parser.

Method Details

ensureAttribs

protected void ensureAttribs(int size)
Make sure that in attributes temporary array is enough space.

ensureCapacity

protected void ensureCapacity(int size)
Make sure that we have enough space to keep element stack if passed size.

getBufferShrinkOffset

public int getBufferShrinkOffset()
Specified by:
getBufferShrinkOffset in interface XmlPullParserBufferControl

getColumnNumber

public int getColumnNumber()
Specified by:
getColumnNumber in interface XmlPullParser

getContentLength

public int getContentLength()
            throws XmlPullParserException
Return how big is content.

NOTE: parser must be on CONTENT event.

Specified by:
getContentLength in interface XmlPullParser

getDepth

public int getDepth()
Returns the current depth of the element.
Specified by:
getDepth in interface XmlPullParser

getEventBuffer

public char[] getEventBuffer()
Specified by:
getEventBuffer in interface XmlPullParserEventPosition

getEventEnd

public int getEventEnd()
Specified by:
getEventEnd in interface XmlPullParserEventPosition

getEventStart

public int getEventStart()
Specified by:
getEventStart in interface XmlPullParserEventPosition

getEventType

public byte getEventType()
Returns the type of the current element (START_TAG, END_TAG, CONTENT, etc)
Specified by:
getEventType in interface XmlPullParser

getHardLimit

public int getHardLimit()
Specified by:
getHardLimit in interface XmlPullParserBufferControl

getLineNumber

public int getLineNumber()
Specified by:
getLineNumber in interface XmlPullParser

getLocalName

public String getLocalName()
Returns the local name of the current element (current event must be START_TAG or END_TAG)
Specified by:
getLocalName in interface XmlPullParser

getNamespaceUri

public String getNamespaceUri()
Returns the namespace URI of the current element Returns null if not applicable (current event must be START_TAG or END_TAG)
Specified by:
getNamespaceUri in interface XmlPullParser

getNamespacesLength

public int getNamespacesLength(int depth)
Specified by:
getNamespacesLength in interface XmlPullParser

getPosDesc

public String getPosDesc()
Return string describing current position of parser in input stream.
Specified by:
getPosDesc in interface XmlPullParser

getPrefix

public String getPrefix()
Returns the prefix of the current element or null if elemet has no prefix. (current event must be START_TAG or END_TAG)
Specified by:
getPrefix in interface XmlPullParser

getQNameLocal

public String getQNameLocal(String qName)
Return local part of qname. For example for 'xsi:type' it returns 'type'.
Specified by:
getQNameLocal in interface XmlPullParser

getQNameUri

public String getQNameUri(String qName)
            throws XmlPullParserException
Return uri part of qname. It is depending on current state of parser to find what namespace uri is mapped from namespace prefix. For example for 'xsi:type' if xsi namespace prefix was declared to 'urn:foo' it will return 'urn:foo'.
Specified by:
getQNameUri in interface XmlPullParser

getRawName

public String getRawName()
Returns the raw name (prefix + ':' + localName) of the current element (current event must be START_TAG or END_TAG)
Specified by:
getRawName in interface XmlPullParser

getSoftLimit

public int getSoftLimit()
Specified by:
getSoftLimit in interface XmlPullParserBufferControl

isAllowedMixedContent

public boolean isAllowedMixedContent()
Is mixed element context allowed?
Specified by:
isAllowedMixedContent in interface XmlPullParser

isBufferShrinkable

public boolean isBufferShrinkable()
Specified by:
isBufferShrinkable in interface XmlPullParserBufferControl

isNamespaceAttributesReporting

public boolean isNamespaceAttributesReporting()
Is parser going to report namespace attributes (xmlns*) ?
Specified by:
isNamespaceAttributesReporting in interface XmlPullParser

isNamespaceAware

public boolean isNamespaceAware()
Is parser namespace aware?
Specified by:
isNamespaceAware in interface XmlPullParser

isWhitespaceContent

public boolean isWhitespaceContent()
            throws XmlPullParserException
Return true if just read CONTENT contained only white spaces.
Specified by:
isWhitespaceContent in interface XmlPullParser

next

public byte next()
            throws XmlPullParserException,
                   IOException
This is key method - it reads more from input stream and returns next event type (such as START_TAG, END_TAG, CONTENT). or END_DOCUMENT if no more input.

This is simple automata (in pseudo-code):

 byte next() {
    while(state != END_DOCUMENT) {
      token = tokenizer.next();  // get next XML token
      switch(token) {

      case Tokenizer.END_DOCUMENT:
        return state = END_DOCUMENT

      case Tokenizer.CONTENT:
        // check if content allowed - only inside element
        return state = CONTENT

     case Tokenizer.ETAG_NAME:
        // popup element from stack - compare if matched start and end tag
        // if namespaces supported restore namespaces prefix mappings
        return state = END_TAG;

      case Tokenizer.STAG_NAME:
        // create new  element push it on stack
        // process attributes (including namespaces)
        // set emptyElement = true; if empty element
        // check atribute uniqueness (including nmespacese prefixes)
        return state = START_TAG;

      }
    }
 }
 

Actual parsing is more complex especilly for start tag due to dealing with attributes reported separately from tokenizer and declaring namespace prefixes and uris.

Specified by:
next in interface XmlPullParser

readContent

public String readContent()
            throws XmlPullParserException
Return String that contains just read CONTENT.
Specified by:
readContent in interface XmlPullParser

readEndTag

public void readEndTag(XmlEndTag etag)
            throws XmlPullParserException
Read value of just read END_TAG into passed as argument EndTag.
Specified by:
readEndTag in interface XmlPullParser

readNamespacesPrefixes

public void readNamespacesPrefixes(int depth,
                                   String[] prefixes,
                                   int off,
                                   int len)
            throws XmlPullParserException
Return namespace prefixes for element at depth
Specified by:
readNamespacesPrefixes in interface XmlPullParser

readNamespacesUris

public void readNamespacesUris(int depth,
                               String[] uris,
                               int off,
                               int len)
            throws XmlPullParserException
Return namespace URIs for element at depth
Specified by:
readNamespacesUris in interface XmlPullParser

readNode

public byte readNode(XmlNode node)
            throws XmlPullParserException,
                   IOException
Read subtree into node: call readNodeWithoutChildren and then parse subtree adding children (values obtained with readXontent or readNodeWithoutChildren).

NOTE: parser must be on START_TAG event. and all events will written into node!

Specified by:
readNode in interface XmlPullParser

readNodeWithoutChildren

public void readNodeWithoutChildren(XmlNode node)
            throws XmlPullParserException
Read node: it calls readStartTag and then if parser is namespaces aware currently declared nemaspeces will be added and defaultNamespace will be set.

NOTE: parser must be on START_TAG event. and all events will written into node!

Specified by:
readNodeWithoutChildren in interface XmlPullParser

readStartTag

public void readStartTag(XmlStartTag stag)
            throws XmlPullParserException
Read value of just read START_TAG into passed as argument StartTag.
Specified by:
readStartTag in interface XmlPullParser

reset

public void reset()
Reset parser state so it can be used to parse new
Specified by:
reset in interface XmlPullParser

resetState

protected void resetState()

setAllowedMixedContent

public void setAllowedMixedContent(boolean enable)
Allow for mixed element content. Enabled by default. When disbaled element must containt either text or other elements.
Specified by:
setAllowedMixedContent in interface XmlPullParser

setBufferShrinkable

public void setBufferShrinkable(boolean shrinkable)
            throws XmlPullParserException
Specified by:
setBufferShrinkable in interface XmlPullParserBufferControl

setHardLimit

public void setHardLimit(int value)
            throws XmlPullParserException
Specified by:
setHardLimit in interface XmlPullParserBufferControl

setInput

public void setInput(Reader reader)
Reset parser and set new input.
Specified by:
setInput in interface XmlPullParser

setInput

public void setInput(char[] buf)
Reset parser and set new input.
Specified by:
setInput in interface XmlPullParser

setInput

public void setInput(char[] buf,
                     int off,
                     int len)
            throws XmlPullParserException
Set the input for parser.
Specified by:
setInput in interface XmlPullParser

setNamespaceAttributesReporting

public void setNamespaceAttributesReporting(boolean enable)
Make parser to report xmlns* attributes. Disabled by default. Only meaningful when namespaces are enabled (when namespaces are disabled all attributes are always reported).
Specified by:
setNamespaceAttributesReporting in interface XmlPullParser

setNamespaceAware

public void setNamespaceAware(boolean awareness)
            throws XmlPullParserException
Set support of namespaces. Disabled by default.
Specified by:
setNamespaceAware in interface XmlPullParser

setSoftLimit

public void setSoftLimit(int value)
            throws XmlPullParserException
Specified by:
setSoftLimit in interface XmlPullParserBufferControl

skipNode

public byte skipNode()
            throws XmlPullParserException,
                   IOException
If parser has just read start tag it allows to skip whoole subtree contined in this element. Returns when encounters end tag matching the start tag.
Specified by:
skipNode in interface XmlPullParser

Copyright (c) 2003 IU Extreme! Lab http://www.extreme.indiana.edu/ All Rights Reserved.

Note this package is deprecated by XPP3 that implements XmlPull API