Package 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 | 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

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method | 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