net.sf.saxon.event

## Class TracingFilter

- java.lang.Object
- - net.sf.saxon.event.SequenceReceiver
  - - net.sf.saxon.event.ProxyReceiver
    - - net.sf.saxon.event.TracingFilter

- All Implemented Interfaces:
    Result, Receiver

      public class TracingFilter
      extends ProxyReceiver

  A filter that can be inserted into a Receiver pipeline to trace the events that pass through. This class is not normally used in Saxon, but is available for diagnostics when needed.

- - ### Field Summary

    - ### Fields inherited from class net.sf.saxon.event.ProxyReceiver

      `nextReceiver`

    - ### Fields inherited from class net.sf.saxon.event.SequenceReceiver

      `pipelineConfiguration, previousAtomic, systemId`

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

      `PI_DISABLE_OUTPUT_ESCAPING, PI_ENABLE_OUTPUT_ESCAPING`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `TracingFilter(Receiver nextReceiver)` Create a TracingFilter and allocate a unique Id.
    `TracingFilter(Receiver nextReceiver, PrintStream diagnosticOutput)` Create a TracingFilter, allocate a unique Id, and supply the destination for diagnostic trace messages

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `append(Item item, int locationId, int copyNamespaces)` Append an arbitrary item (node or atomic value) to the output
    `void` | `attribute(NodeName nameCode, SimpleType typeCode, CharSequence value, int locationId, int properties)` Notify an attribute.
    `void` | `characters(CharSequence chars, int locationId, int properties)` Character data
    `void` | `close()` End of document
    `void` | `comment(CharSequence chars, int locationId, int properties)` Output a comment
    `void` | `endDocument()` Notify the end of a document node
    `void` | `endElement()` End of element
    `int` | `getId()` Get the unique id that was allocated to this TracingFilter
    `void` | `namespace(NamespaceBinding namespaceBinding, int properties)` Notify a namespace.
    `void` | `open()` Start of event stream
    `void` | `processingInstruction(String target, CharSequence data, int locationId, int properties)` Processing Instruction
    `void` | `startContent()` Notify the start of the content, that is, the completion of all attributes and namespaces.
    `void` | `startDocument(int properties)` Start of a document node.
    `void` | `startElement(NodeName nameCode, SchemaType typeCode, int locationId, int properties)` Notify the start of an element

    - ### Methods inherited from class net.sf.saxon.event.ProxyReceiver

      `getNamePool, getUnderlyingReceiver, setPipelineConfiguration, setSystemId, setUnderlyingReceiver, setUnparsedEntity, usesTypeAnnotations`

    - ### Methods inherited from class net.sf.saxon.event.SequenceReceiver

      `append, getConfiguration, getPipelineConfiguration, getSystemId`

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

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

- - ### Constructor Detail

    - #### TracingFilter

          public TracingFilter(Receiver nextReceiver)

      Create a TracingFilter and allocate a unique Id.
      Parameters:
        `nextReceiver` - the underlying receiver to which the events will be sent

    - #### TracingFilter

          public TracingFilter(Receiver nextReceiver,
                       PrintStream diagnosticOutput)

      Create a TracingFilter, allocate a unique Id, and supply the destination for diagnostic trace messages
      Parameters:
        `nextReceiver` - the underlying receiver to which the events will be sent
        `diagnosticOutput` - the destination for diagnostic trace messages

  - ### Method Detail

    - #### getId

          public int getId()

      Get the unique id that was allocated to this TracingFilter
      Returns:
        the unique id (which is included in all diagnostic messages)

    - #### append

          public void append(Item item,
                    int locationId,
                    int copyNamespaces)
                      throws XPathException

      Append an arbitrary item (node or atomic value) to the output
      Overrides:
        `append` in class `ProxyReceiver`
      Parameters:
        `item` - the item to be appended
        `locationId` - the location of the calling instruction, for diagnostics
        `copyNamespaces` - if the item is an element node, this indicates whether its namespaces need to be copied. Values are `NodeInfo.ALL_NAMESPACES`, `NodeInfo.LOCAL_NAMESPACES`, `NodeInfo.NO_NAMESPACES`
      Throws:
        `XPathException` - if the operation fails

    - #### attribute

          public void attribute(NodeName nameCode,
                       SimpleType typeCode,
                       CharSequence value,
                       int locationId,
                       int properties)
                         throws XPathException

      Notify an attribute. Attributes are notified after the startElement event, and before any children. Namespaces and attributes may be intermingled.
      Specified by:
        `attribute` in interface `Receiver`
      Overrides:
        `attribute` in class `ProxyReceiver`
      Parameters:
        `nameCode` - The name of the attribute, as held in the name pool
        `typeCode` - The type of the attribute, as held in the name pool
        `properties` - Bit significant value. The following bits are defined:
        DISABLE_ESCAPING
      Disable escaping for this attribute
        NO_SPECIAL_CHARACTERS
      Attribute value contains no special characters
        `value` - the string value of the attribute
        `locationId` - an integer which can be interpreted using a `LocationProvider` to return information such as line number and system ID. If no location information is available, the value zero is supplied.
      Throws:
        `IllegalStateException:` - attempt to output an attribute when there is no open element start tag
        `XPathException` - if an error occurs

    - #### characters

          public void characters(CharSequence chars,
                        int locationId,
                        int properties)
                          throws XPathException

      Character data
      Specified by:
        `characters` in interface `Receiver`
      Overrides:
        `characters` in class `ProxyReceiver`
      Parameters:
        `chars` - The characters
        `locationId` - an integer which can be interpreted using a `LocationProvider` to return information such as line number and system ID. If no location information is available, the value zero is supplied.
        `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

    - #### close

          public void close()
                     throws XPathException

      End of document
      Specified by:
        `close` in interface `Receiver`
      Overrides:
        `close` in class `ProxyReceiver`
      Throws:
        `XPathException` - if an error occurs

    - #### comment

          public void comment(CharSequence chars,
                     int locationId,
                     int properties)
                       throws XPathException

      Output a comment
      Specified by:
        `comment` in interface `Receiver`
      Overrides:
        `comment` in class `ProxyReceiver`
      Parameters:
        `chars` - The content of the comment
        `locationId` - an integer which can be interpreted using a `LocationProvider` to return information such as line number and system ID. If no location information is available, the value zero is supplied.
        `properties` - Additional information about the comment.
      Throws:
        `XPathException` - if an error occurs

    - #### endDocument

          public void endDocument()
                           throws XPathException

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

    - #### endElement

          public void endElement()
                          throws XPathException

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

    - #### namespace

          public void namespace(NamespaceBinding namespaceBinding,
                       int properties)
                         throws XPathException

      Notify a namespace. Namespaces are notified after the startElement event, and before any children for the element. The namespaces that are reported are only required to include those that are different from the parent element; however, duplicates may be reported. A namespace must not conflict with any namespaces already used for element or attribute names.
      Specified by:
        `namespace` in interface `Receiver`
      Overrides:
        `namespace` in class `ProxyReceiver`
      Parameters:
        `namespaceBinding` - the namespace (prefix, uri) pair to be notified
        `properties` - any special properties to be passed on this call
      Throws:
        `IllegalStateException:` - attempt to output a namespace when there is no open element start tag
        `XPathException` - if an error occurs

    - #### open

          public void open()
                    throws XPathException

      Start of event stream
      Specified by:
        `open` in interface `Receiver`
      Overrides:
        `open` in class `ProxyReceiver`
      Throws:
        `XPathException` - if an error occurs

    - #### processingInstruction

          public void processingInstruction(String target,
                                   CharSequence data,
                                   int locationId,
                                   int properties)
                                     throws XPathException

      Processing Instruction
      Specified by:
        `processingInstruction` in interface `Receiver`
      Overrides:
        `processingInstruction` in class `ProxyReceiver`
      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` - an integer which can be interpreted using a `LocationProvider` to return information such as line number and system ID. If no location information is available, the value zero is supplied.
        `properties` - Additional information about the PI.
      Throws:
        `XPathException` - if an error occurs

    - #### startContent

          public void startContent()
                            throws XPathException

      Notify the start of the content, that is, the completion of all attributes and namespaces. Note that the initial receiver of output from XSLT instructions will not receive this event, it has to detect it itself. Note that this event is reported for every element even if it has no attributes, no namespaces, and no content.
      Specified by:
        `startContent` in interface `Receiver`
      Overrides:
        `startContent` in class `ProxyReceiver`
      Throws:
        `XPathException` - if an error occurs

    - #### startDocument

          public void startDocument(int properties)
                             throws XPathException

      Start of a document node.
      Specified by:
        `startDocument` in interface `Receiver`
      Overrides:
        `startDocument` in class `ProxyReceiver`
      Parameters:
        `properties` - bit-significant integer indicating properties of the document node. The definitions of the bits are in class `ReceiverOptions`
      Throws:
        `XPathException` - if an error occurs

    - #### startElement

          public void startElement(NodeName nameCode,
                          SchemaType typeCode,
                          int locationId,
                          int properties)
                            throws XPathException

      Notify the start of an element
      Specified by:
        `startElement` in interface `Receiver`
      Overrides:
        `startElement` in class `ProxyReceiver`
      Parameters:
        `nameCode` - integer code identifying the name of the element within the name pool.
        `typeCode` - integer code identifying the element's type within the name pool.
        `properties` - properties of the element node
        `locationId` - an integer which can be interpreted using a `LocationProvider` to return information such as line number and system ID. If no location information is available, the value zero is supplied.
      Throws:
        `XPathException` - if an error occurs

Copyright (c) 2004-2013 Saxonica Limited. All rights reserved.