Subject: Exported From Confluence
Content-Type: text/html; charset=UTF-8
(note: As of 09-Jun-2009, following is somewhat incomplete list,=
but should cover all major areas of functionality up to and including Stax=
StAX2 is an experimental API that is intended to extend basic StAX speci=
fications in a way that allows implementations to experiment with features =
before they end up in the actual StAX specification (if they do). As such, =
it is intended to be freely implementable by all StAX implementations same =
way as StAX, but without going through a formal JCP process.
Currently Woodstox is the only known=
To access StAX API jar, you can go to Woodstox Download page.
For javadocs you can go back to Woodstox Documentation page.
Main goals of StAX2 API are:
Access to f=
ormerly missing/inaccessible information
- DOCTYPE declaration: can access root name, public/system identifiers=
, and internal subset all separately; similarly added matching output metho=
- Attribute information: can find index of the specified attribute, as=
well as ID and NOTATION attribute indexes (as per DTD)
- Location information (XMLStreamLocation2):
- Access to nested Locations (parent context)
- Separate byte/char offsets; value type as long instead of int to =
allow for multi-gigabyte input NOT FULLY=
- Misc. information:
- XMLStreamReader.isEmptyElement() (whether current START_ELEMENT w=
as a result of an empty element, i.e. <tag />),
- XMLStreamReader.getDepth() (number of enclosing start elements, i=
ncluding current START_ELEMENT)
Efficient (fully streaming) =
- getText methods that write contents of textual events through Writer=
object passed as the argument
- Pass-through XMLStreamWriter.copyEventFromReader method
- XMLStreamReader.skipElement allows efficient skipping of all childre=
n of an element
- All events can now be output through specified XMLStreamWriter; this=
allows for full configuration of output (namespace bindings, encoding/quot=
- Can define a custom quoter/encoder for textual content
- Can define a custom quoter/encoder for attribute values
- Raw write access using XMLStreamWriter.writeRaw(), for outputting te=
xt as is, without quoting/encoding.
for per-reader/writer configuration
- XMLStreamReader: allow overriding of external DTD subset.
- XMLStreamWriter: (no options yet)
gable bi-directional validation framework
(for Stax2 v2.0 and above, i.e. Woodstox 3.0)
- Extensible: easy to add custom validators, and infoset augmenters (f=
or example, DTD validator adds default attribute values).
- Support for multiple chainable validators (for example: can do both =
DTD validation and RelaxNG validation simultaneously).
- Fully bi-directional: can not only validate when parsing, but when o=
utputting as well.
- Configurable problem (validation error) handling: can collect all va=
lidation problems, or do fail-fast validation (exception on encountering th=
e first problem).
etween Readers and Writers (where applicable)
Within Stax 1.0, writers seem like ugly stepchildren, ignored by the spe=
cification. Whereas readers have full set of accessors, and configuration, =
writers have bare-bones support (except for the confusing two-in-one handli=
ng of the repairing and non-repairing modes).
Stax2 tries to address this asymmetry by bringing over those Reader meth=
ods to Writer side that make sense, as well as make sure that new Stax2 fun=
ctionality listed above will also be available for Writers, where it makes =
sense. For example:
- You can add XMLReporter to writers as well, to be able to report non=
- Optional Location information will be accessible from Writers too: e=
ither so that they can relay information from incoming events (for event wr=
iters), or even keep track of the output line numbers. This should be usefu=
l for debugging purposes, esp. when used with Writer-side validation.
(for Stax2 v3.0 and above, i.e. Woodstox 4.0)
This means adding ability to read and write textual content (attribute v=
alues, text segments) as typed content =E2=80=93 if contents are serialized=
numbers, QNames, arrays, base64 encoded binary data, they can be accessed =
directly as such. Stax2 implementation handles necessary conversions as eff=
iciently and conveniently as possible.
In addition to supported types, simple plug-in extensions exist to allow=
for binding custom types as well.
The idea behind name "Stax2" is really either "Stax squar=
ed" (ie. Stax^2); or, "Stax, take 2", but NOT "Stax ver=
sion 2.0". There is hope that new revisions of the official Stax speci=
fication/standard will be done, sometime in future; and work with Stax2 is =
at most to provide ideas and experiences, and not to replace actual standar=