Package net.sf.swan.xml.output

An API to simplify generating XML output with SAX.

See:
Description

Class Summary

AttributesResult	Represents the attributes on an element.
ContainerResult	A Result that may contain other Results as children.
ContainerResult.NamespaceBinding
DocumentResult	Specialized FragmentResult that emits startDocument and endDocument events to the ContentHandler.
ElementResult
FragmentResult	Top-level result that emits its content out to a SAX ContentHandler and optional LexicalHandler.
Result

Exception Summary

ResultException
UnresolvableNamespaceException

Package net.sf.swan.xml.output Description

An API to simplify generating XML output with SAX. To use, one may either create a DocumentResult or FragmentResult directly, or use a ResultFactory.

NOTE: This is an experimental API and is subject to change.

This API is designed with the goal of providing a simple, compact, and readable notation for creating SAX-based XML output with a reasonable amount of built-in error checking. The various Result classes each provide factory methods for creating those XML constructs appropriate within their context. The Result object returned from each of these factory methods is the one that provides the appropriate context to create further constructs along a particular axis. This permits a compact syntax that can approach the simplicity and readability of markup.

For example, consider the following XML snippet:

    <department>
        <employee id="500">
            <firstName>Kilgore</firstName>
            <lastName>Trout</lastName>
        </employee>
    </department>
			

The code to produce this directly using SAX would be quite ugly and verbose, in spite of the simplicity of the markup being produced. In contrast, code to produce this using this API could look something like this:

    
    ResultFactory factory = new ResultFactory();
    DocumentResult result = 
        factory.newDocumentResult(new StreamResult(System.out));

    ElementResult dept = result.element("department");
    
    ElementResult emp = dept.element("employee")
    emp.attribute("id", "500");
    emp.element("firstName").text("Kilgore");   // child element with text content
    emp.element("lastName").text("Trout");      // child element with text content
						
    // output the accumulated result tree
    result.end();
    
			

Alternatively, we could emit each element as it is completed, and could use an indentation style that emulates the XML structure we wish to generate:

    
    ResultFactory factory = new ResultFactory();
    DocumentResult result = 
        factory.newDocumentResult(new StreamResult(System.out));

    result.element("department")
        .element("employee").attribute("id", "500").end()
            .element("firstName")
                .text("Kilgore")
            .end()
            .element("lastName")
                .text("Trout")
            .end();
						
    // bail out here and output the remaining result tree
    result.end();
    
			

Note that we used a JAXP javax.xml.transform.stream.StreamResult to receive the final output. We could have just as easily used a DOMResult and thus built a DOM Document or Node substree, or we could have instantiated the DocumentResult directly with a SAX ContentHandler and optional LexicalHandler.