net.sf.saxon.s9api

Interface Push

All Known Implementing Classes:

PushToReceiver

public interface Push

An interface designed for applications to generate XML documents by issuing events. Functionally similar to the SAX ContentHandler or the Stax XMLStreamWriter, it is designed eliminate the usability problems and ambiguities in those specifications.

The Push interface can be used to create a single tree rooted at a document node. It is possible to constrain the document node to be well-formed (in which case it must have a single element node child, plus optionally comment and processing instruction children). Some implementations may only accept well-formed documents.

The document created using the Push interface is set to the Destination defined when Push is created using the factory method Processor.newPush(Destination). The Destination will commonly be an XdmDestination or a Serializer, but it could also be, for example, an XsltTransformer or an SchemaValidator.

Here is an example of application code written to construct a simple XML document:

 Push.Document doc = processor.newPush(destination).document(true);
 doc.setDefaultNamespace("http://www.example.org/ns");
 Push.Element top = doc.element("root");
 top.attribute("version", "1.5");
 for (Employee emp : employees) {
     top.element("emp")
        .attribute("ssn", emp.getSSN())
        .text(emp.getName());
 }
 doc.close();
 

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static interface	Push.Container The Container interface represents a document node or element node under construction; there are concrete subclasses representing document nodes and element nodes respectively.
static interface	Push.Document A Push.Container representing a document node.
static interface	Push.Element A Push.Container representing an element node.

Method Summary

Modifier and Type	Method and Description
Push.Document	document(boolean wellFormed) Start an XML document.

Method Detail

document

Push.Document document(boolean wellFormed)
                throws SaxonApiException

Start an XML document.

Parameters:

wellFormed - Set to true if the document is required to be well-formed; set to false if there is no such requirement. A well-formed document must have as its children exactly one element node plus optionally, any number of comment and processing instruction nodes (no text nodes are allowed); any attempt to construct a node sequence that does not follow these rules will result in an exception. If the document is not required to be well-formed, the children of the document node may comprise any sequence of element, text, comment, and processing instruction nodes.

Returns:

a Doc object which may be used to add content to the document, or to close the document when it has been fully written.

Throws:

SaxonApiException - if the specified constraints are violated, or if the implementation detects any problems