Package net.sf.saxon.event

## Class ContentHandlerProxy

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

- All Implemented Interfaces:
    `javax.xml.transform.Result`, `Receiver`
  Direct Known Subclasses:
    `TypedContentHandler`

      public class ContentHandlerProxy
      extends java.lang.Object
      implements Receiver

  A ContentHandlerProxy is a Receiver that converts events into the form expected by an underlying SAX2 ContentHandler. Relevant events (notably comments) can also be fed to a LexicalHandler.

  Note that in general the output passed to a Receiver corresponds to an External General Parsed Entity. A SAX2 ContentHandler only expects to deal with well-formed XML documents, so we only pass it the contents of the first element encountered, unless the saxon:require-well-formed output property is set to "no".

  This ContentHandlerProxy provides no access to type information. For a ContentHandler that makes type information available, see `TypedContentHandler`

  The ContentHandlerProxy can also be nominated as a TraceListener, to receive notification of trace events.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class | Description
    --- | --- | ---
    `static class` | `ContentHandlerProxy.ContentHandlerProxyTraceListener` | Create a TraceListener that will collect information about the current location in the source document.

  - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `protected org.xml.sax.ContentHandler` | `handler` |
    `protected org.xml.sax.ext.LexicalHandler` | `lexicalHandler` |

    - ### Fields inherited from interface javax.xml.transform.Result

      `PI_DISABLE_OUTPUT_ESCAPING, PI_ENABLE_OUTPUT_ESCAPING`

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `ContentHandlerProxy()` |

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `characters​(java.lang.CharSequence chars, Location locationId, int properties)` | Character data
    `void` | `close()` | Notify the end of the event stream
    `void` | `comment​(java.lang.CharSequence chars, Location locationId, int properties)` | Output a comment.
    `void` | `endDocument()` | Notify the end of the document
    `void` | `endElement()` | End of element
    `Configuration` | `getConfiguration()` | Get the Saxon configuration
    `Location` | `getCurrentLocation()` | Get the current location identifier
    `PipelineConfiguration` | `getPipelineConfiguration()` | Get the pipeline configuration
    `java.lang.String` | `getSystemId()` | Get the System ID of the destination tree
    `ContentHandlerProxy.ContentHandlerProxyTraceListener` | `getTraceListener()` | Get the associated TraceListener that receives notification of trace events
    `org.xml.sax.ContentHandler` | `getUnderlyingContentHandler()` | Get the underlying content handler
    `boolean` | `isRequireWellFormed()` | Ask whether the content handler can handle a stream of events that is merely well-balanced, or whether it can only handle a well-formed sequence.
    `boolean` | `isUndeclareNamespaces()` | Ask whether namespace undeclaration events (for a non-null prefix) should be notified.
    `protected void` | `notifyNotWellFormed()` | The following function is called when it is found that the output is not a well-formed document.
    `void` | `open()` | Notify the start of the event stream
    `void` | `processingInstruction​(java.lang.String target, java.lang.CharSequence data, Location locationId, int properties)` | Processing Instruction
    `void` | `setLexicalHandler​(org.xml.sax.ext.LexicalHandler handler)` | Set the Lexical Handler to be used.
    `void` | `setOutputProperties​(java.util.Properties details)` | Set the output details.
    `void` | `setPipelineConfiguration​(PipelineConfiguration pipe)` | Set the pipeline configuration
    `void` | `setRequireWellFormed​(boolean wellFormed)` | Set whether the content handler can handle a stream of events that is merely well-balanced, or whether it can only handle a well-formed sequence.
    `void` | `setSystemId​(java.lang.String systemId)` | Set the System ID of the destination tree
    `void` | `setUndeclareNamespaces​(boolean undeclareNamespaces)` | Set whether namespace undeclaration events (for a non-null prefix) should be notified.
    `void` | `setUnderlyingContentHandler​(org.xml.sax.ContentHandler handler)` | Set the underlying content handler.
    `void` | `setUnparsedEntity​(java.lang.String name, java.lang.String systemID, java.lang.String publicID)` | Notify an unparsed entity URI.
    `void` | `startDocument​(int properties)` | Notify the start of the document.
    `void` | `startElement​(NodeName elemName, SchemaType type, AttributeMap attributes, NamespaceMap namespaces, Location location, int properties)` | Notify the start of an element
    `boolean` | `usesTypeAnnotations()` | Ask whether this Receiver (or the downstream pipeline) makes any use of the type annotations supplied on element and attribute events

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

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

    - ### Methods inherited from interface net.sf.saxon.event.Receiver

      `append, append, handlesAppend`

- - ### Field Detail

    - #### handler

          protected org.xml.sax.ContentHandler handler

    - #### lexicalHandler

          protected org.xml.sax.ext.LexicalHandler lexicalHandler

  - ### Constructor Detail

    - #### ContentHandlerProxy

          public ContentHandlerProxy()

  - ### Method Detail

    - #### setUnderlyingContentHandler

          public void setUnderlyingContentHandler​(org.xml.sax.ContentHandler handler)

      Set the underlying content handler. This call is mandatory before using this Receiver. If the content handler is an instance of `LexicalHandler`, then it will also receive notification of lexical events such as comments.
      Parameters:
        `handler` - the SAX content handler to which all events will be directed

    - #### getUnderlyingContentHandler

          public org.xml.sax.ContentHandler getUnderlyingContentHandler()

      Get the underlying content handler
      Returns:
        the SAX content handler to which all events are being directed

    - #### setLexicalHandler

          public void setLexicalHandler​(org.xml.sax.ext.LexicalHandler handler)

      Set the Lexical Handler to be used. If called, this must be called AFTER setUnderlyingContentHandler()
      Parameters:
        `handler` - the SAX lexical handler to which lexical events (such as comments) will be notified.

    - #### setPipelineConfiguration

          public void setPipelineConfiguration​(PipelineConfiguration pipe)

      Set the pipeline configuration
      Specified by:
        `setPipelineConfiguration` in interface `Receiver`
      Parameters:
        `pipe` - the pipeline configuration

    - #### getPipelineConfiguration

          public PipelineConfiguration getPipelineConfiguration()

      Get the pipeline configuration
      Specified by:
        `getPipelineConfiguration` in interface `Receiver`
      Returns:
        the pipeline configuration

    - #### getConfiguration

          public Configuration getConfiguration()

      Get the Saxon configuration
      Returns:
        the Saxon configuration

    - #### setSystemId

          public void setSystemId​(java.lang.String systemId)

      Set the System ID of the destination tree
      Specified by:
        `setSystemId` in interface `Receiver`
      Specified by:
        `setSystemId` in interface `javax.xml.transform.Result`
      Parameters:
        `systemId` - the system ID (effectively the base URI)

    - #### getSystemId

          public java.lang.String getSystemId()

      Get the System ID of the destination tree
      Specified by:
        `getSystemId` in interface `javax.xml.transform.Result`
      Returns:
        the system ID (effectively the base URI)

    - #### getTraceListener

          public ContentHandlerProxy.ContentHandlerProxyTraceListener getTraceListener()

      Get the associated TraceListener that receives notification of trace events
      Returns:
        the trace listener. If there is no existing trace listener, then a new one will be created.

    - #### getCurrentLocation

          public Location getCurrentLocation()

      Get the current location identifier
      Returns:
        the location identifier of the most recent event.

    - #### setUnparsedEntity

          public void setUnparsedEntity​(java.lang.String name,
                                        java.lang.String systemID,
                                        java.lang.String publicID)
                                 throws XPathException

      Notify an unparsed entity URI.
      Specified by:
        `setUnparsedEntity` in interface `Receiver`
      Parameters:
        `name` - The name of the unparsed entity
        `systemID` - The system identifier of the unparsed entity
        `publicID` - The public identifier of the unparsed entity
      Throws:
        `XPathException` - if an error occurs

    - #### setOutputProperties

          public void setOutputProperties​(java.util.Properties details)

      Set the output details.
      Parameters:
        `details` - the serialization properties. The only values used by this implementation are `SaxonOutputKeys.REQUIRE_WELL_FORMED` and `SaxonOutputKeys.UNDECLARE_PREFIXES`.

    - #### isRequireWellFormed

          public boolean isRequireWellFormed()

      Ask whether the content handler can handle a stream of events that is merely well-balanced, or whether it can only handle a well-formed sequence.
      Returns:
        true if the content handler requires the event stream to represent a well-formed XML document (containing exactly one top-level element node and no top-level text nodes)

    - #### setRequireWellFormed

          public void setRequireWellFormed​(boolean wellFormed)

      Set whether the content handler can handle a stream of events that is merely well-balanced, or whether it can only handle a well-formed sequence. The default is false.
      Parameters:
        `wellFormed` - set to true if the content handler requires the event stream to represent a well-formed XML document (containing exactly one top-level element node and no top-level text nodes). Otherwise, multiple top-level elements and text nodes are allowed, as in the XDM model.

    - #### isUndeclareNamespaces

          public boolean isUndeclareNamespaces()

      Ask whether namespace undeclaration events (for a non-null prefix) should be notified. The default is no, because some ContentHandlers (e.g. JDOM) can't cope with them.
      Returns:
        true if namespace undeclarations (xmlns:p="") are to be output

    - #### setUndeclareNamespaces

          public void setUndeclareNamespaces​(boolean undeclareNamespaces)

      Set whether namespace undeclaration events (for a non-null prefix) should be notified. The default is no, because some ContentHandlers (e.g. JDOM) can't cope with them.
      Parameters:
        `undeclareNamespaces` - true if namespace undeclarations (xmlns:p="") are to be output

    - #### open

          public void open()
                    throws XPathException

      Notify the start of the event stream
      Specified by:
        `open` in interface `Receiver`
      Throws:
        `XPathException` - if an error occurs

    - #### close

          public void close()
                     throws XPathException

      Notify the end of the event stream
      Specified by:
        `close` in interface `Receiver`
      Throws:
        `XPathException` - if an error occurs

    - #### startDocument

          public void startDocument​(int properties)
                             throws XPathException

      Notify the start of the document.
      Specified by:
        `startDocument` in interface `Receiver`
      Parameters:
        `properties` -
      Throws:
        `XPathException` - if an error occurs

    - #### endDocument

          public void endDocument()
                           throws XPathException

      Notify the end of the document
      Specified by:
        `endDocument` in interface `Receiver`
      Throws:
        `XPathException` - if an error occurs

    - #### startElement

          public void startElement​(NodeName elemName,
                                   SchemaType type,
                                   AttributeMap attributes,
                                   NamespaceMap namespaces,
                                   Location location,
                                   int properties)
                            throws XPathException

      Notify the start of an element
      Specified by:
        `startElement` in interface `Receiver`
      Parameters:
        `elemName` - the name of the element.
        `type` - the type annotation of the element.
        `attributes` - the attributes of this element
        `namespaces` - the in-scope namespaces of this element: generally this is all the in-scope namespaces, without relying on inheriting namespaces from parent elements
        `location` - an object providing information about the module, line, and column where the node originated
        `properties` - bit-significant properties of the element node. If there are no relevant properties, zero is supplied. The definitions of the bits are in class `ReceiverOption`
      Throws:
        `XPathException` - if an error occurs

    - #### endElement

          public void endElement()
                          throws XPathException

      End of element
      Specified by:
        `endElement` in interface `Receiver`
      Throws:
        `XPathException` - if an error occurs

    - #### characters

          public void characters​(java.lang.CharSequence chars,
                                 Location locationId,
                                 int properties)
                          throws XPathException

      Character data
      Specified by:
        `characters` in interface `Receiver`
      Parameters:
        `chars` - The characters
        `locationId` - provides information such as line number and system ID.
        `properties` - Bit significant value. The following bits are defined:
        DISABLE_ESCAPING
          Disable escaping for this text node
        USE_CDATA
          Output as a CDATA section
      Throws:
        `XPathException` - if an error occurs

    - #### notifyNotWellFormed

          protected void notifyNotWellFormed()
                                      throws XPathException

      The following function is called when it is found that the output is not a well-formed document. Unless the ContentHandler accepts "balanced content", this is a fatal error.
      Throws:
        `XPathException`

    - #### processingInstruction

          public void processingInstruction​(java.lang.String target,
                                            java.lang.CharSequence data,
                                            Location locationId,
                                            int properties)
                                     throws XPathException

      Processing Instruction
      Specified by:
        `processingInstruction` in interface `Receiver`
      Parameters:
        `target` - The PI name. This must be a legal name (it will not be checked).
        `data` - The data portion of the processing instruction
        `locationId` - provides information such as line number and system ID.
        `properties` - Additional information about the PI.
      Throws:
        `XPathException` - if an error occurs

    - #### comment

          public void comment​(java.lang.CharSequence chars,
                              Location locationId,
                              int properties)
                       throws XPathException

      Output a comment. Passes it on to the ContentHandler provided that the ContentHandler is also a SAX2 LexicalHandler.
      Specified by:
        `comment` in interface `Receiver`
      Parameters:
        `chars` - The content of the comment
        `locationId` - provides information such as line number and system ID.
        `properties` - Additional information about the comment.
      Throws:
        `XPathException` - if an error occurs

    - #### usesTypeAnnotations

          public boolean usesTypeAnnotations()

      Ask whether this Receiver (or the downstream pipeline) makes any use of the type annotations supplied on element and attribute events
      Specified by:
        `usesTypeAnnotations` in interface `Receiver`
      Returns:
        true if the Receiver makes any use of this information. If false, the caller may supply untyped nodes instead of supplying the type annotation