Package net.sf.saxon.s9api.streams

## Class XdmCollectors

- java.lang.Object
- - net.sf.saxon.s9api.streams.XdmCollectors

-     public class XdmCollectors
      extends java.lang.Object

  This class contains a number of static methods that deliver implementations of the `Collector` interface suitable for use with streams processing XDM nodes and other items.

  For example, the method `asNode` can be used in an expression such as `XdmNode n = x.select(child("author")).collect(asNode())` to indicate that the content of the stream delivered by the `select()` call is to be delivered as a single XdmNode object, and that an exception should occur if the result is anything other than a single node.

  Although these methods can be used directly as arguments to `Stream.collect(java.util.function.Supplier<R>, java.util.function.BiConsumer<R, ? super T>, java.util.function.BiConsumer<R, R>)`, it is usually more convenient to use them indirectly, the form of terminal operations on the class `XdmStream`, which extends `Stream`. So a more usual usage would be `XdmNode n = x.select(child("author")).asNode()`

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class | Description
    --- | --- | ---
    `static class` | `XdmCollectors.MultipleItemException` | Unchecked exception that occurs when a collector method such as `asAtomic()` or `asOptionalNode()` is called, and the sequence contains more than one item.

  - ### Constructor Summary

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

  - ### Method Summary

    All Methods Static Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `static net.sf.saxon.s9api.streams.XdmCollectors.XdmCollector<XdmAtomicValue,​XdmAtomicValue>` | `asAtomic()` | This method provides a Collector that returns the content of a stream as a single atomic value, that is, an instance of `XdmAtomicValue`.
    `static net.sf.saxon.s9api.streams.XdmCollectors.XdmCollector<java.util.List<XdmAtomicValue>,​XdmAtomicValue>` | `asListOfAtomic()` | This method provides a Collector that returns the content of a stream as a list of atomic values (that is, as an instance of `List<XdmAtomicValue>`)
    `static net.sf.saxon.s9api.streams.XdmCollectors.XdmCollector<java.util.List<XdmNode>,​XdmNode>` | `asListOfNodes()` | This method provides a Collector that returns the content of a stream as a list of `XdmNode` objects (that is, as an instance of `List<XdmNode>`)
    `static net.sf.saxon.s9api.streams.XdmCollectors.XdmCollector<XdmNode,​XdmNode>` | `asNode()` | This method provides a Collector that returns the content of a stream as a single `XdmNode`.
    `static net.sf.saxon.s9api.streams.XdmCollectors.XdmCollector<java.util.Optional<XdmAtomicValue>,​XdmAtomicValue>` | `asOptionalAtomic()` | This method provides a Collector that returns the content of a stream as an optional atomic value (that is, as an instance of `Optional<XdmAtomicValue>`)
    `static net.sf.saxon.s9api.streams.XdmCollectors.XdmCollector<java.util.Optional<XdmNode>,​XdmNode>` | `asOptionalNode()` | This method provides a Collector that returns the content of a stream as an optional `XdmNode` (that is, as an instance of `Optional<XdmNode>`)
    `static net.sf.saxon.s9api.streams.XdmCollectors.XdmCollector<java.util.Optional<java.lang.String>,​XdmItem>` | `asOptionalString()` | This method provides a Collector that returns the content of a stream as an optional String (that is, as an instance of `Optional<String>`) The stream must deliver either nothing, or a single `XdmItem`; the collector returns the string value of that item.
    `static net.sf.saxon.s9api.streams.XdmCollectors.XdmCollector<java.lang.String,​XdmItem>` | `asString()` | This method provides a Collector that returns the content of a stream as an optional String (that is, as an instance of `Optional<String>`) The stream must deliver a single `XdmItem`; the collector returns the string value of that item.
    `static net.sf.saxon.s9api.streams.XdmCollectors.XdmCollector<XdmValue,​XdmItem>` | `asXdmValue()` | This method provides a Collector that returns the content of a stream as an `XdmValue`

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

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

- - ### Constructor Detail

    - #### XdmCollectors

          public XdmCollectors()

  - ### Method Detail

    - #### asXdmValue

          public static net.sf.saxon.s9api.streams.XdmCollectors.XdmCollector<XdmValue,​XdmItem> asXdmValue()

      This method provides a Collector that returns the content of a stream as an `XdmValue`
      Returns:
        a collector that returns the single node delivered by the stream, or null if the stream is empty
      Throws:
        `java.lang.ClassCastException` - if the stream contains an item that is not a node

    - #### asNode

          public static net.sf.saxon.s9api.streams.XdmCollectors.XdmCollector<XdmNode,​XdmNode> asNode()

      This method provides a Collector that returns the content of a stream as a single `XdmNode`.
      Returns:
        a collector that returns the single node delivered by the stream
      Throws:
        `java.util.NoSuchElementException` - if the stream is empty
        `XdmCollectors.MultipleItemException` - if the stream contains more than one node
        `java.lang.ClassCastException` - if the stream contains an item that is not a node

    - #### asOptionalNode

          public static net.sf.saxon.s9api.streams.XdmCollectors.XdmCollector<java.util.Optional<XdmNode>,​XdmNode> asOptionalNode()

      This method provides a Collector that returns the content of a stream as an optional `XdmNode` (that is, as an instance of `Optional<XdmNode>`)
      Returns:
        a collector that returns the single node delivered by the stream, or `Optional#empty()` if the stream is empty
      Throws:
        `XdmCollectors.MultipleItemException` - if the stream contains more than one node
        `java.lang.ClassCastException` - if the stream contains an item that is not a node

    - #### asListOfNodes

          public static net.sf.saxon.s9api.streams.XdmCollectors.XdmCollector<java.util.List<XdmNode>,​XdmNode> asListOfNodes()

      This method provides a Collector that returns the content of a stream as a list of `XdmNode` objects (that is, as an instance of `List<XdmNode>`)
      Returns:
        a collector that returns the single node delivered by the stream, or null if the stream is empty
      Throws:
        `java.lang.ClassCastException` - if the stream contains an item that is not a node

    - #### asListOfAtomic

          public static net.sf.saxon.s9api.streams.XdmCollectors.XdmCollector<java.util.List<XdmAtomicValue>,​XdmAtomicValue> asListOfAtomic()

      This method provides a Collector that returns the content of a stream as a list of atomic values (that is, as an instance of `List<XdmAtomicValue>`)
      Returns:
        a collector that returns the list of atomic values delivered by the stream
      Throws:
        `java.lang.ClassCastException` - if the stream contains an item that is not an atomic value

    - #### asOptionalAtomic

          public static net.sf.saxon.s9api.streams.XdmCollectors.XdmCollector<java.util.Optional<XdmAtomicValue>,​XdmAtomicValue> asOptionalAtomic()

      This method provides a Collector that returns the content of a stream as an optional atomic value (that is, as an instance of `Optional<XdmAtomicValue>`)
      Returns:
        a collector that returns the single atomic value delivered by the stream, or `Optional.empty()` if the stream is empty
      Throws:
        `java.lang.ClassCastException` - if the stream contains an item that is not a node

    - #### asAtomic

          public static net.sf.saxon.s9api.streams.XdmCollectors.XdmCollector<XdmAtomicValue,​XdmAtomicValue> asAtomic()

      This method provides a Collector that returns the content of a stream as a single atomic value, that is, an instance of `XdmAtomicValue`. The stream must deliver a single atomic value.
      Returns:
        a collector that returns the string value of the single item delivered by the stream
      Throws:
        `java.util.NoSuchElementException` - if the stream is empty
        `XdmCollectors.MultipleItemException` - if the stream contains more than one item
        `java.lang.ClassCastException` - if the stream delivers an item that is not an atomic value

    - #### asOptionalString

          public static net.sf.saxon.s9api.streams.XdmCollectors.XdmCollector<java.util.Optional<java.lang.String>,​XdmItem> asOptionalString()

      This method provides a Collector that returns the content of a stream as an optional String (that is, as an instance of `Optional<String>`) The stream must deliver either nothing, or a single `XdmItem`; the collector returns the string value of that item.
      Returns:
        a collector that returns the string value of the single item delivered by the stream, if any
      Throws:
        `XdmCollectors.MultipleItemException` - if the stream contains more than one item
        `java.lang.UnsupportedOperationException` - if the stream contains an item with no string value (such as a function item or an element with element-only content)

    - #### asString

          public static net.sf.saxon.s9api.streams.XdmCollectors.XdmCollector<java.lang.String,​XdmItem> asString()

      This method provides a Collector that returns the content of a stream as an optional String (that is, as an instance of `Optional<String>`) The stream must deliver a single `XdmItem`; the collector returns the string value of that item.
      Returns:
        a collector that returns the string value of the single item delivered by the stream, if any
      Throws:
        `XdmCollectors.MultipleItemException` - if the stream contains more than one item
        `java.util.NoSuchElementException` - if the stream is empty
        `java.lang.UnsupportedOperationException` - if the stream contains an item with no string value (such as a function item or an element with element-only content)