= StaxWax =

[#a1.Overview 1. Overview][[BR]]
[#a2.Downloads 2. Downloads][[BR]]
[#a3.Userdocumentation 3. User documentation][[BR]]
[#a4.Developerdocumentation 4. Developer documentation][[BR]]
[#a5.Javadocs 5. Javadocs]

== 1. Overview ==

The !StaxWax framework provides convenient methods for high-performance XML parsing and writing and is favourable for several reasons:

 * The framework is based on the StAX Java API for XML. StAX combines the usability of tree-based APIs like DOM and the high perfomance of event-based APIs like SAX, while avoiding their disadvantages of high memory consumption and inconvenient programming model respectively.
 * !StaxWax uses the Woodstox StAX implementation which is recognized as the fastest in the market today.
 * The framework acts as a layer on top of the underlying stream readers and writers, and provides more convenient methods that allows for a clean and comprehensible programming model.
 * The !StaxWax XMLReader is robust regarding XML that is not well-formed.

== 2. Downloads ==

The latest StAXWax relase is version 1.0.4 and can be downloaded in several formats:

[http://amplecode.org/downloads/staxwax/staxwax-1.0.4.jar StAXWax] - Binaries[[BR]]
[http://amplecode.org/downloads/staxwax/staxwax-1.0.4-with-dependencies.zip StAXWax With Dependencies] - Binaries including third-party dependencies[[BR]]
[http://amplecode.org/downloads/staxwax/staxwax-1.0.4-sources.jar StAXWax Sources] - Sources

!StaxWax framework is built with [http://maven.apache.org Maven] and is located in its central repository. It can be configured as a dependency in the project object model like this:

{{{
<dependency>
  <groupId>org.amplecode</groupId>
  <artifactId>staxwax</artifactId>
  <version>1.0.1</version>
</dependency>
}}}

== 3. User documentation ==

An XMLWriter can be obtained from the the XMLFactory:

{{{
XMLWriter writer = XMLFactory.getXMLWriter( outputStream );
}}}

For instance a collection of Person objects can be written like this:

{{{
writer.openDocument( "UTF-8", "1.0" );
writer.openElement( "persons" );

writer.openElement( "person" );
writer.writeElement( "name", "John Doe" );
writer.writeElement( "address", "Main road 1" );
writer.closeElement();

writer.openElement( "person" );
writer.writeElement( "name", "Ed Johnson" );
writer.writeElement( "address", "High way 2" );
writer.closeElement();

writer.closeElement();
writer.closeDocument();
}}}

The application is responsible for closing the underlying !OutputStream.

An XMLReader can be obtained from the XMLFactory:

{{{
XMLReader reader = XMLFactory.getXMLReader( inputStream );
}}}

The previously generated document containing the Person data can be parsed like this:

{{{
while ( reader.next() )
{
    while ( reader.moveToStartElement( "person", "persons" ) )
    {
        Map<String, String> values = reader.readElements( "person" );
        String name = values.get( "name" );
        String address = values.get( "address" );
    }
}
}}}

Another approach that gives you greater control but involves more verbose code looks like this:

{{{
while ( reader.next() )
{
    while ( reader.moveToStartElement( "person", "persons" ) )
    {
        reader.moveToStartElement( "name" );
        String name = reader.getElementValue();
        reader.moveToStartElement( "address" );
        String address = reader.getElementValue();
    }
}
}}}

The application is responsible for closing the underlying !InputStream.

== 4. Developer documentation ==

The !StaxWax framework is released under the BSD open source [http://amplecode.org/license/license_bsd.txt license] and can be modified by anyone.

The following class diagram describes the components in the !StaxWax framework: 

[[Image(staxwax_class_diagram.PNG)]]

== 5. Javadocs ==

View the [http://amplecode.org/apidocs/staxwax/1.0.1/index.html API / Javadocs].