io7m
io7m-jstructural 3.1.0
2.1
API Tutorial
2.1.1
Overview
1
The jstructural API is divided into core and annotated types. The core types have an (almost) 1:1 correspondence with the elements that a document author writes in XML. The parser included with the XOM backend, for example, produces a document consisting of elements of the core types from an XML file. The annotated types are, unsurprisingly, values of the core types with additional annotations and metadata required to actually produce documents in XHTML format.
2.1.2
Usage
1
Parsing documents and producing XHTML output is quite simple. First, a stream representing an XML file is given to the included parser, which parses and validates the document against the structural schema.
2.1.2.1. Parsing

    URI uri;
    Log log;
    InputStream stream;

    final SDocument doc = SDocumentParser.fromStream(stream, uri, log);

2
Then, the resulting document is annotated with the included annotator:
2.1.2.2. Annotation

    Log log;
    SDocument doc;

    final SADocument adoc = SAnnotator.document (doc, log);

3
Finally, either the single-page writer or multi-page writer are used to produce a set of XHTML documents that can be serialized using the standard XOM serializer.
2.1.2.3. Writing

    Log log;
    SADocument doc;
    SDocumentXHTMLWriterCallbacks callbacks;

    SDocumentXHTMLWriterSingle writer = new SDocumentXHTMLWriterSingle();
    SortedMap<String, Document> pages = writer.writeDocuments(callbacks, doc);

4
The map returned by the writeDocuments function is a set of mappings from file names to documents.
5
The writers take a set of callbacks as arguments that can be used to customize the resulting output. See the javadoc for details.