Choosing between Cursor and Iterator APIs

It is reasonable to ask at this point, “What API should I choose? Should I create instances of XMLStreamReader or XMLEventReader? Why are there two kinds of APIs anyway?”

Development Goals

The authors of the StAX specification targeted three types of developers:

• Library and infrastructure developers: Need highly efficient, low-level APIs with minimal extensibility requirements.

• J2ME developers: Need small, simple, pull-parsing libraries, and have minimal extensibility needs.

• Java EE and Java SE developers: Need clean, efficient pull-parsing libraries, plus need the flexibility to both read and write XML streams, create new event types, and extend XML document elements and attributes.

Given these wide-ranging development categories, the StAX authors felt it was more useful to define two small, efficient APIs rather than overloading one larger and necessarily more complex API.

Comparing Cursor and Iterator APIs

Before choosing between the cursor and iterator APIs, you should note a few things that you can do with the iterator API that you cannot do with cursor API:

• Objects created from the XMLEvent subclasses are immutable, and can be used in arrays, lists, and maps, and can be passed through your applications even after the parser has moved on to subsequent events.

• You can create subtypes of XMLEvent that are either completely new information items or extensions of existing items but with additional methods.

• You can add and remove events from an XML event stream in much simpler ways than with the cursor API.

Similarly, keep some general recommendations in mind when making your choice:

• If you are programming for a particularly memory-constrained environment, like J2ME, you can make smaller, more efficient code with the cursor API.

• If performance is your highest priority (for example, when creating low-level libraries or infrastructure), the cursor API is more efficient.

• If you want to create XML processing pipelines, use the iterator API.

• If you want to modify the event stream, use the iterator API.

• If you want your application to be able to handle pluggable processing of the event stream, use the iterator API.

• In general, if you do not have a strong preference one way or the other, using the iterator API is recommended because it is more flexible and extensible, thereby “future-proofing” your applications.