As we have seen pull parsing has some advantages and therefore it is very
important to provide developers with one consistent and simple API to work
with.

For such an API to stay minimal we need to expose only a few things to the
user. We need to expose the parser state, such as : START_TAG, END_TAG,
CONTENT, END_DOCUMENT. This number of states is minimal for any XML
parser. We will also need an ability to to get next state, for example by
calling method named next(). Finally for each state we will need to
retrieve information associated with the parser state (current event). When
we reach END_DOCUMENT there is no more input and in this case no extra
information is needed. However for CONTENT, to get element content as
String, readContent() can be used. Then for start and end tags we need the
name of the tag and its namesapace: getLocalName() and getNamespaceUri().
Finally START_TAG is the hard part as it can also contain the list of
attributes declared in this start tag. It is a good idea to make it look
like SAX Attributes/AttributeList to simplify potential conversion of pull
events into SAX push callbacks.

It is useful to represent XmlStartTag and XmlEndTag as separate interfaces
but sharing common functionality in XmlTag. It is possible to have state
retrieval methods in XmlPullParser instead of creating extra interfaces
such as XmlEndTag and XmlStartTag. However having separate interfaces
allows us to maintain parsing state in those classes easily and allows to record
state of parsing for any number of steps in the past.

This API will have to be extended to allow for more efficient handling of
namespace declarations, setting parser input, resetting parser state for
parser reuse and some other utility methods. However the core API for XML
pull parser will probably be similar to what is shown above.

We should mention here that use of XmlTag interfaces is not essential for
such API and may be abandoned when memory size constraints are of premium
such as is the case with handheld devices in J2ME. In these cases embedding
all state into one XmlPullParser interface will be very advantageous.