Package net.sf.saxon.event

## Class StreamWriterToReceiver

- java.lang.Object
- - net.sf.saxon.event.StreamWriterToReceiver

- All Implemented Interfaces:
    `javax.xml.stream.XMLStreamWriter`
  Direct Known Subclasses:
    `BuildingStreamWriterImpl`

      public class StreamWriterToReceiver
      extends java.lang.Object
      implements javax.xml.stream.XMLStreamWriter

  This class implements the XmlStreamWriter interface, translating the events into Saxon Receiver events. The Receiver can be anything: a serializer, a schema validator, a tree builder.

  This class does not itself perform "namespace repairing" as defined in the interface Javadoc (also referred to as "prefix defaulting" in the StaX JSR specification). In normal use, however, the events emitted by this class are piped into a `NamespaceReducer` which performs a function very similar to namespace repairing; specifically, it ensures that when elements and attribute are generated with a given namespace URI and local name, then namespace declarations are generated automatically without any explicit need to call the `writeNamespace(String, String)` method.

  The class will check all names, URIs, and character content for conformance against XML well-formedness rules unless the `checkValues` option is set to false.

  The implementation of this class is influenced not only by the Javadoc documentation of the `XMLStreamWriter` interface (which is woefully inadequate), but also by the helpful but unofficial interpretation of the spec to be found at http://veithen.github.io/2009/11/01/understanding-stax.html

  Provided that the sequence of events sent to this class is legitimate, the events sent to the supplied `Receiver` should constitute a regular sequence as defined in the documentation of class `RegularSequenceChecker`.

  Since:
    9.3. Rewritten May 2015 to fix bug 2357. Further modified in 9.7.0.2 in light of the discussion of bug 2398, and the interpretation of the spec cited above.

- - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `StreamWriterToReceiver​(Receiver receiver)` | Constructor.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `close()` |
    `void` | `flush()` |
    `javax.xml.namespace.NamespaceContext` | `getNamespaceContext()` | Return the current namespace context.
    `java.lang.String` | `getPrefix​(java.lang.String uri)` |
    `java.lang.Object` | `getProperty​(java.lang.String name)` |
    `Receiver` | `getReceiver()` | Get the Receiver to which this StreamWriterToReceiver is writing events
    `boolean` | `isCheckValues()` | Ask whether names and values are to be checked for conformance with XML rules
    `void` | `setCheckValues​(boolean check)` | Say whether names and values are to be checked for conformance with XML rules
    `void` | `setDefaultNamespace​(java.lang.String uri)` |
    `void` | `setNamespaceContext​(javax.xml.namespace.NamespaceContext context)` |
    `void` | `setPrefix​(java.lang.String prefix, java.lang.String uri)` |
    `void` | `writeAttribute​(java.lang.String localName, java.lang.String value)` |
    `void` | `writeAttribute​(java.lang.String namespaceURI, java.lang.String localName, java.lang.String value)` |
    `void` | `writeAttribute​(java.lang.String prefix, java.lang.String namespaceURI, java.lang.String localName, java.lang.String value)` |
    `void` | `writeCData​(java.lang.String data)` |
    `void` | `writeCharacters​(char[] text, int start, int len)` |
    `void` | `writeCharacters​(java.lang.String text)` |
    `void` | `writeComment​(java.lang.String data)` |
    `void` | `writeDefaultNamespace​(java.lang.String namespaceURI)` | Emits a default namespace declaration
    `void` | `writeDTD​(java.lang.String dtd)` |
    `void` | `writeEmptyElement​(java.lang.String localName)` |
    `void` | `writeEmptyElement​(java.lang.String namespaceURI, java.lang.String localName)` |
    `void` | `writeEmptyElement​(java.lang.String prefix, java.lang.String localName, java.lang.String namespaceURI)` |
    `void` | `writeEndDocument()` |
    `void` | `writeEndElement()` |
    `void` | `writeEntityRef​(java.lang.String name)` |
    `void` | `writeNamespace​(java.lang.String prefix, java.lang.String namespaceURI)` | Emits a namespace declaration event.
    `void` | `writeProcessingInstruction​(java.lang.String target)` |
    `void` | `writeProcessingInstruction​(java.lang.String target, java.lang.String data)` |
    `void` | `writeStartDocument()` |
    `void` | `writeStartDocument​(java.lang.String version)` |
    `void` | `writeStartDocument​(java.lang.String encoding, java.lang.String version)` |
    `void` | `writeStartElement​(java.lang.String localName)` | Generate a start element event for an element in no namespace.
    `void` | `writeStartElement​(java.lang.String namespaceURI, java.lang.String localName)` | Generate a start element event.
    `void` | `writeStartElement​(java.lang.String prefix, java.lang.String localName, java.lang.String namespaceURI)` | Generate a start element event.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### StreamWriterToReceiver

          public StreamWriterToReceiver​(Receiver receiver)

      Constructor. Creates a StreamWriter as a front-end to a given Receiver.
      Parameters:
        `receiver` - the Receiver that is to receive the events generated by this StreamWriter.

  - ### Method Detail

    - #### getReceiver

          public Receiver getReceiver()

      Get the Receiver to which this StreamWriterToReceiver is writing events
      Returns:
        the destination Receiver

    - #### setCheckValues

          public void setCheckValues​(boolean check)

      Say whether names and values are to be checked for conformance with XML rules
      Parameters:
        `check` - true if names and values are to be checked. Default is false;

    - #### isCheckValues

          public boolean isCheckValues()

      Ask whether names and values are to be checked for conformance with XML rules
      Returns:
        true if names and values are to be checked. Default is false;

    - #### writeStartElement

          public void writeStartElement​(java.lang.String localName)
                                 throws javax.xml.stream.XMLStreamException

      Generate a start element event for an element in no namespace. Note: the element will be in no namespace, even if `setDefaultNamespace(String)` has been called; this is Saxon's interpretation of the intended effect of the StAX specification.
      Specified by:
        `writeStartElement` in interface `javax.xml.stream.XMLStreamWriter`
      Parameters:
        `localName` - local name of the tag, may not be null
      Throws:
        `javax.xml.stream.XMLStreamException` - if names are being checked and the name is invalid, or if an error occurs downstream
        `java.lang.NullPointerException` - if the supplied local name is null

    - #### writeStartElement

          public void writeStartElement​(java.lang.String namespaceURI,
                                        java.lang.String localName)
                                 throws javax.xml.stream.XMLStreamException

      Generate a start element event. The name of the element is determined by the supplied namespace URI and local name. The prefix used for the element is determined by the in-scope prefixes established using `setPrefix(String, String)` and/or `setDefaultNamespace(String)` if these include the specified namespace URI; otherwise the namespace will become the default namespace and there will therefore be no prefix.
      Specified by:
        `writeStartElement` in interface `javax.xml.stream.XMLStreamWriter`
      Parameters:
        `namespaceURI` - the namespace URI of the element name. Must not be null. A zero-length string means the element is in no namespace.
        `localName` - local part of the element name. Must not be null
      Throws:
        `javax.xml.stream.XMLStreamException` - if names are being checked and are found to be invalid, or if an error occurs downstream in the pipeline.
        `java.lang.NullPointerException` - if either argument is null

    - #### writeStartElement

          public void writeStartElement​(java.lang.String prefix,
                                        java.lang.String localName,
                                        java.lang.String namespaceURI)
                                 throws javax.xml.stream.XMLStreamException

      Generate a start element event. The name of the element is determined by the supplied namespace URI and local name, and the prefix will be as supplied in the call.
      Specified by:
        `writeStartElement` in interface `javax.xml.stream.XMLStreamWriter`
      Parameters:
        `prefix` - the prefix of the element, must not be null. If the prefix is supplied as a zero-length string, the element will nave no prefix (that is, the namespace URI will become the default namespace).
        `localName` - local name of the element, must not be null
        `namespaceURI` - the uri to bind the prefix to, must not be null. If the value is a zero-length string, the element will be in no namespace; in this case any prefix is ignored.
      Throws:
        `java.lang.NullPointerException` - if any of the arguments is null.
        `javax.xml.stream.XMLStreamException` - if names are being checked and are found to be invalid, or if an error occurs downstream in the pipeline.

    - #### writeEmptyElement

          public void writeEmptyElement​(java.lang.String namespaceURI,
                                        java.lang.String localName)
                                 throws javax.xml.stream.XMLStreamException

      Specified by:
        `writeEmptyElement` in interface `javax.xml.stream.XMLStreamWriter`
      Throws:
        `javax.xml.stream.XMLStreamException`

    - #### writeEmptyElement

          public void writeEmptyElement​(java.lang.String prefix,
                                        java.lang.String localName,
                                        java.lang.String namespaceURI)
                                 throws javax.xml.stream.XMLStreamException

      Specified by:
        `writeEmptyElement` in interface `javax.xml.stream.XMLStreamWriter`
      Throws:
        `javax.xml.stream.XMLStreamException`

    - #### writeEmptyElement

          public void writeEmptyElement​(java.lang.String localName)
                                 throws javax.xml.stream.XMLStreamException

      Specified by:
        `writeEmptyElement` in interface `javax.xml.stream.XMLStreamWriter`
      Throws:
        `javax.xml.stream.XMLStreamException`

    - #### writeEndElement

          public void writeEndElement()
                               throws javax.xml.stream.XMLStreamException

      Specified by:
        `writeEndElement` in interface `javax.xml.stream.XMLStreamWriter`
      Throws:
        `javax.xml.stream.XMLStreamException`

    - #### writeEndDocument

          public void writeEndDocument()
                                throws javax.xml.stream.XMLStreamException

      Specified by:
        `writeEndDocument` in interface `javax.xml.stream.XMLStreamWriter`
      Throws:
        `javax.xml.stream.XMLStreamException`

    - #### close

          public void close()
                     throws javax.xml.stream.XMLStreamException

      Specified by:
        `close` in interface `javax.xml.stream.XMLStreamWriter`
      Throws:
        `javax.xml.stream.XMLStreamException`

    - #### flush

          public void flush()

      Specified by:
        `flush` in interface `javax.xml.stream.XMLStreamWriter`

    - #### writeAttribute

          public void writeAttribute​(java.lang.String localName,
                                     java.lang.String value)

      Specified by:
        `writeAttribute` in interface `javax.xml.stream.XMLStreamWriter`

    - #### writeAttribute

          public void writeAttribute​(java.lang.String prefix,
                                     java.lang.String namespaceURI,
                                     java.lang.String localName,
                                     java.lang.String value)

      Specified by:
        `writeAttribute` in interface `javax.xml.stream.XMLStreamWriter`

    - #### writeAttribute

          public void writeAttribute​(java.lang.String namespaceURI,
                                     java.lang.String localName,
                                     java.lang.String value)

      Specified by:
        `writeAttribute` in interface `javax.xml.stream.XMLStreamWriter`

    - #### writeNamespace

          public void writeNamespace​(java.lang.String prefix,
                                     java.lang.String namespaceURI)
                              throws javax.xml.stream.XMLStreamException

      Emits a namespace declaration event.

      If the prefix argument to this method is the empty string, "xmlns", or null this method will delegate to writeDefaultNamespace.

      This method does not change the name of any element or attribute; its only use is to write additional or redundant namespace declarations. With this implementation of XMLStreamWriter, this method is needed only to generate namespace declarations for prefixes that do not appear in element or attribute names. If an attempt is made to generate a namespace declaration that conflicts with the prefix-uri bindings in scope for element and attribute names, an exception occurs.

      Specified by:
        `writeNamespace` in interface `javax.xml.stream.XMLStreamWriter`
      Parameters:
        `prefix` - the prefix to bind this namespace to
        `namespaceURI` - the uri to bind the prefix to
      Throws:
        `java.lang.IllegalStateException` - if the current state does not allow Namespace writing
        `javax.xml.stream.XMLStreamException` - if things go wrong

    - #### writeDefaultNamespace

          public void writeDefaultNamespace​(java.lang.String namespaceURI)

      Emits a default namespace declaration

      This method does not change the name of any element or attribute; its only use is to write additional or redundant namespace declarations. With this implementation of XMLStreamWriter, this method is needed only to generate namespace declarations for prefixes that do not appear in element or attribute names. If an attempt is made to generate a namespace declaration that conflicts with the prefix-uri bindings in scope for element and attribute names, an exception occurs.

      Specified by:
        `writeDefaultNamespace` in interface `javax.xml.stream.XMLStreamWriter`
      Parameters:
        `namespaceURI` - the uri to bind the default namespace to
      Throws:
        `java.lang.IllegalStateException` - if the current state does not allow Namespace writing

    - #### writeComment

          public void writeComment​(java.lang.String data)
                            throws javax.xml.stream.XMLStreamException

      Specified by:
        `writeComment` in interface `javax.xml.stream.XMLStreamWriter`
      Throws:
        `javax.xml.stream.XMLStreamException`

    - #### writeProcessingInstruction

          public void writeProcessingInstruction​(java.lang.String target)
                                          throws javax.xml.stream.XMLStreamException

      Specified by:
        `writeProcessingInstruction` in interface `javax.xml.stream.XMLStreamWriter`
      Throws:
        `javax.xml.stream.XMLStreamException`

    - #### writeProcessingInstruction

          public void writeProcessingInstruction​(java.lang.String target,
                                                 java.lang.String data)
                                          throws javax.xml.stream.XMLStreamException

      Specified by:
        `writeProcessingInstruction` in interface `javax.xml.stream.XMLStreamWriter`
      Throws:
        `javax.xml.stream.XMLStreamException`

    - #### writeCData

          public void writeCData​(java.lang.String data)
                          throws javax.xml.stream.XMLStreamException

      Specified by:
        `writeCData` in interface `javax.xml.stream.XMLStreamWriter`
      Throws:
        `javax.xml.stream.XMLStreamException`

    - #### writeDTD

          public void writeDTD​(java.lang.String dtd)
                        throws javax.xml.stream.XMLStreamException

      Specified by:
        `writeDTD` in interface `javax.xml.stream.XMLStreamWriter`
      Throws:
        `javax.xml.stream.XMLStreamException`

    - #### writeEntityRef

          public void writeEntityRef​(java.lang.String name)

      Specified by:
        `writeEntityRef` in interface `javax.xml.stream.XMLStreamWriter`

    - #### writeStartDocument

          public void writeStartDocument()
                                  throws javax.xml.stream.XMLStreamException

      Specified by:
        `writeStartDocument` in interface `javax.xml.stream.XMLStreamWriter`
      Throws:
        `javax.xml.stream.XMLStreamException`

    - #### writeStartDocument

          public void writeStartDocument​(java.lang.String version)
                                  throws javax.xml.stream.XMLStreamException

      Specified by:
        `writeStartDocument` in interface `javax.xml.stream.XMLStreamWriter`
      Throws:
        `javax.xml.stream.XMLStreamException`

    - #### writeStartDocument

          public void writeStartDocument​(java.lang.String encoding,
                                         java.lang.String version)
                                  throws javax.xml.stream.XMLStreamException

      Specified by:
        `writeStartDocument` in interface `javax.xml.stream.XMLStreamWriter`
      Throws:
        `javax.xml.stream.XMLStreamException`

    - #### writeCharacters

          public void writeCharacters​(java.lang.String text)
                               throws javax.xml.stream.XMLStreamException

      Specified by:
        `writeCharacters` in interface `javax.xml.stream.XMLStreamWriter`
      Throws:
        `javax.xml.stream.XMLStreamException`

    - #### writeCharacters

          public void writeCharacters​(char[] text,
                                      int start,
                                      int len)
                               throws javax.xml.stream.XMLStreamException

      Specified by:
        `writeCharacters` in interface `javax.xml.stream.XMLStreamWriter`
      Throws:
        `javax.xml.stream.XMLStreamException`

    - #### getPrefix

          public java.lang.String getPrefix​(java.lang.String uri)

      Specified by:
        `getPrefix` in interface `javax.xml.stream.XMLStreamWriter`

    - #### setPrefix

          public void setPrefix​(java.lang.String prefix,
                                java.lang.String uri)

      Specified by:
        `setPrefix` in interface `javax.xml.stream.XMLStreamWriter`

    - #### setDefaultNamespace

          public void setDefaultNamespace​(java.lang.String uri)

      Specified by:
        `setDefaultNamespace` in interface `javax.xml.stream.XMLStreamWriter`

    - #### setNamespaceContext

          public void setNamespaceContext​(javax.xml.namespace.NamespaceContext context)

      Specified by:
        `setNamespaceContext` in interface `javax.xml.stream.XMLStreamWriter`

    - #### getNamespaceContext

          public javax.xml.namespace.NamespaceContext getNamespaceContext()

      Return the current namespace context.

      The specification of this method is hopelessly vague. This method returns a namespace context that contains the namespaces declared using `setPrefix(String, String)` calls that are in-scope at the time, overlaid on the root namespace context that was defined using `setNamespaceContext(NamespaceContext)`. The namespaces bound using `setPrefix(String, String)` are copied, and are therefore unaffected by subsequent changes, but the root namespace context is not copied, because the NamespaceContext interface provides no way of doing so.

      Specified by:
        `getNamespaceContext` in interface `javax.xml.stream.XMLStreamWriter`
      Returns:
        a copy of the current namespace context.

    - #### getProperty

          public java.lang.Object getProperty​(java.lang.String name)
                                       throws java.lang.IllegalArgumentException

      Specified by:
        `getProperty` in interface `javax.xml.stream.XMLStreamWriter`
      Throws:
        `java.lang.IllegalArgumentException`