Package net.sf.saxon.event

## Class RegularSequenceChecker

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

- All Implemented Interfaces:
    `javax.xml.transform.Result`, `Receiver`

      public class RegularSequenceChecker
      extends ProxyReceiver

  A `RegularSequenceChecker` is a filter that can be inserted into a Receiver pipeline to check that the sequence of events passed in is a regular event sequence. Many (though not all) implementations of `Outputter` require the sequence of events to be regular according to this definition.

  A sequence of `Receiver` events is regular if the following conditions are satisfied:

  1. Calls to `Outputter.startElement(NodeName, SchemaType, Location, int)`, `endElement()`, `Outputter.startDocument(int)`, and `endDocument()` are properly paired and nested.
  2. Events must only occur in a state where they are permitted; the states and transitions between states are defined by the table below. The initial state is initial, and the final state must be final.

  Permitted state transitions
  State | Events | Next State
  initial | `open()` | open
  open | `open()` | open
  open | `Outputter.append(Item, Location, int)`, `SequenceReceiver.append(Item)`, `Outputter.characters(CharSequence, Location, int)`, `Outputter.comment(CharSequence, Location, int)`, `Outputter.processingInstruction(String, CharSequence, Location, int)` | open
  open | `Outputter.startDocument(int)` | content
  open | `Outputter.startElement(NodeName, SchemaType, Location, int)` | content
  content | `Outputter.characters(CharSequence, Location, int)`, `Outputter.comment(CharSequence, Location, int)`, `Outputter.processingInstruction(String, CharSequence, Location, int)` | content
  content | `Outputter.startElement(NodeName, SchemaType, Location, int)` | startTag
  content | `endDocument()`, `endElement()` | if the stack is empty, then content, otherwise open
  (any) | close | final
  final | close | final

  This class is not normally used in production within Saxon, but is available for diagnostics when needed.

  Some implementations of `Receiver` accept sequences of events that are not regular; indeed, some implementations are explicitly designed to produce a regular sequence from an irregular sequence. Examples of such irregularities are append or startDocument events appearing within element content, or attribute events being followed by text events with no intervening startContent.

  The rules for a regular sequence imply that the top level events (any events not surrounded by startElement-endElement or startDocument-endDocument) can represent any sequence of items, including for example multiple document nodes, free-standing attribute and namespace nodes, maps, arrays, and functions; but within a startElement-endElement or startDocument-endDocument pair, the events represent content that has been normalized and validated according to the XSLT rules for constructing complex content, or the XQuery equivalent: for example, attributes and namespaces must appear before child nodes, adjacent text nodes should have been merged, zero-length text nodes should have been eliminated, all namespaces should be explicitly declared, document nodes should be replaced by their children.

  Element nodes in "composed form" (that is, existing as a tree in memory) may be passed through the `SequenceReceiver.append(Item)` method at the top level, but within a startElement-endElement or startDocument-endDocument pair, elements must be represented in "decomposed form" as a sequence of events.

  A call to `close()` is permitted in any state, but it should only be called in `Open` state except on an error path; on error paths calling `close()` is recommended to ensure that resources are released.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class | Description
    --- | --- | ---
    `static class` | `RegularSequenceChecker.State` |

  - ### 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 | Description
    --- | ---
    `RegularSequenceChecker​(Receiver nextReceiver, boolean fullChecking)` | Create a RegularSequenceChecker and allocate a unique Id.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `append​(Item item, Location locationId, int copyNamespaces)` | Append an arbitrary item (node or atomic value) to the output.
    `void` | `characters​(java.lang.CharSequence chars, Location locationId, int properties)` | Character data (corresponding to a text node).
    `void` | `close()` | End of sequence
    `void` | `comment​(java.lang.CharSequence chars, Location locationId, int properties)` | Output a comment
    `void` | `endDocument()` | Notify the end of a document node
    `void` | `endElement()` | End of element
    `void` | `open()` | Start of event stream
    `void` | `processingInstruction​(java.lang.String target, java.lang.CharSequence data, Location locationId, int properties)` | Processing Instruction
    `void` | `startDocument​(int properties)` | Start of a document node.
    `void` | `startElement​(NodeName elemName, SchemaType type, AttributeMap attributes, NamespaceMap namespaces, Location location, int properties)` | Notify the start of an element.

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

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

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

      `append, decompose, flatten, getConfiguration, getErrorCodeForDecomposingFunctionItems, getPipelineConfiguration, getSystemId, handlesAppend`

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

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

- - ### Constructor Detail

    - #### RegularSequenceChecker

          public RegularSequenceChecker​(Receiver nextReceiver,
                                        boolean fullChecking)

      Create a RegularSequenceChecker and allocate a unique Id.
      Parameters:
        `nextReceiver` - the underlying receiver to which the events will be sent (without change)
        `fullChecking` - requests full validation of the content passed across the interface. If false, the only checking is that the sequence of events is correct. If true, more thorough validation is carried out (though this does not necessarily mean that every violation is detected).

  - ### Method Detail

    - #### append

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

      Append an arbitrary item (node or atomic value) to the output. In a regular sequence, append events occur only at the top level, that is, when the document / element stack is empty.
      Specified by:
        `append` in interface `Receiver`
      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 `ReceiverOption.ALL_NAMESPACES`; the default (0) means
      Throws:
        `XPathException` - if an error occurs

    - #### characters

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

      Character data (corresponding to a text node). For character data within content (that is, events occurring when the startDocument / startElement stack is non-empty), character data events will never be consecutive and will never be zero-length.
      Specified by:
        `characters` in interface `Receiver`
      Overrides:
        `characters` in class `ProxyReceiver`
      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

    - #### close

          public void close()
                     throws XPathException

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

    - #### comment

          public void comment​(java.lang.CharSequence chars,
                              Location 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` - provides information such as line number and system ID.
        `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

    - #### 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​(java.lang.String target,
                                            java.lang.CharSequence data,
                                            Location 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` - provides information such as line number and system ID.
        `properties` - Additional information about the PI.
      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` - properties of the document node.
      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.

      All attributes must satisfy the following constraints:

      1. The namespace prefix and URI must either both be present (non-zero-length) or both absent
      2. The prefix "xml" and the URI "http://www.w3.org/XML/1998/namespace" are allowed only in combination.
      3. The namespace URI "http://www.w3.org/2000/xmlns/" is not allowed.
      4. The namespace prefix "xmlns" is not allowed.
      5. The local name "xmlns" is not allowed in the absence of a namespace prefix and URI.

      The following additional constraints apply to the set of attributes as a whole:

      1. No two attributes may have the same (local-name, namespace URI) combination.
      2. No namespace prefix may be used in conjunction with more than one namespace URI.
      3. Every (namespace prefix, namespace URI) combination must correspond to an in-scope namespace: that is, unless the (prefix, URI) pair is ("", "") or ("xml", "http://www.w3.org/XML/1998/namespace"), it must be present in the in-scope namespaces.

      These constraints are not all enforced by this class.

      Specified by:
        `startElement` in interface `Receiver`
      Overrides:
        `startElement` in class `ProxyReceiver`
      Parameters:
        `elemName` - the name of the element. If the name is in a namespace (non-empty namespace URI) then the `Outputter.namespace(String, String, int)` event must include a binding for the relevant prefix (or absence of a prefix) to the relevant URI.
        `type` - the type annotation of the element.
        `attributes` - the attributes of the element
        `namespaces` - the in-scope namespaces of the element
        `location` - provides information such as line number and system ID.
        `properties` - properties of the element node
      Throws:
        `XPathException` - if an error occurs