org.modeshape.jcr.query

## Class NodeSequence

- java.lang.Object
- - org.modeshape.jcr.query.NodeSequence

- Direct Known Subclasses:
    CountableSequence, DelegatingSequence, DependentQuery, RestartableSequence

      @NotThreadSafe
      public abstract class NodeSequence
      extends Object

  A sequence of nodes that is accessed by batches and that is accessible only once.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `protected static class` | `NodeSequence.AlternateSizeBatch`
    `static interface` | `NodeSequence.Batch` A batch of rows containing nodes and scores.
    `protected static class` | `NodeSequence.LimitBatch`
    `protected static class` | `NodeSequence.MultiWidthBatch`
    `static interface` | `NodeSequence.Restartable`
    `static interface` | `NodeSequence.RowAccessor` An interface that abstracts accessing the node(s) and score(s) in a row.
    `static interface` | `NodeSequence.RowFilter` A filter of rows.
    `protected static class` | `NodeSequence.SingleWidthBatch`

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected static Logger` | `LOGGER`
    `static NodeSequence.RowFilter` | `NO_PASS_ROW_FILTER`
    `static NodeSequence.RowFilter` | `PASS_ROW_FILTER`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `NodeSequence()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `static NodeSequence` | `append(NodeSequence first, NodeSequence second)` Create a sequence of nodes that contains the nodes from the first sequence followed by the second sequence.
    `static NodeSequence.Batch` | `batchFilteredWith(NodeSequence.Batch batch, NodeSequence.RowFilter filter)` Create a batch that applies the given filter to the supplied batch.
    `static NodeSequence.Batch` | `batchOf(Collection<CachedNode> nodes, float score, String workspaceName)` Create a batch of nodes around the supplied iterable container.
    `static NodeSequence.Batch` | `batchOf(Iterator<CachedNode> nodes, long nodeCount, float score, String workspaceName)` Create a batch of nodes around the supplied iterator.
    `protected static NodeSequence.Batch` | `batchOf(NodeSequence.Batch first, NodeSequence.Batch second, int firstWidth, int secondWidth)`
    `static NodeSequence.Batch` | `batchOfKeys(Collection<NodeKey> keys, float score, String workspaceName, RepositoryCache repository)` Create a batch of nodes around the supplied iterable container.
    `static NodeSequence.Batch` | `batchOfKeys(Iterator<NodeKey> keys, Iterator<Float> scores, long nodeCount, String workspaceName, RepositoryCache repository)` Create a batch of nodes around the supplied iterator and the scores iterator.
    `static NodeSequence.Batch` | `batchOfKeys(Iterator<NodeKey> keys, long nodeCount, float score, String workspaceName, NodeCache cache)` Create a batch of nodes around the supplied iterator.
    `static NodeSequence.Batch` | `batchOfKeys(Iterator<NodeKey> keys, long nodeCount, float score, String workspaceName, RepositoryCache repository)` Create a batch of nodes around the supplied iterator.
    `static NodeSequence.Batch` | `batchWithCount(NodeSequence.Batch batch)` Create a batch that always has a `NodeSequence.Batch.rowCount()`, even if that means returning a new Batch that buffers the original's rows it into memory.
    `abstract void` | `close()` Signal that this node sequence is no longer needed.
    `static NodeSequence.Batch` | `copy(NodeSequence.Batch batch)` Create a copy of a batch that always has a `NodeSequence.Batch.rowCount()`.
    `static NodeSequence.Batch` | `emptyBatch(String workspaceName, int width)` Get a batch of nodes that is empty.
    `static NodeSequence` | `emptySequence(int width)` Get an empty node sequence.
    `static NodeSequence` | `filter(NodeSequence sequence, NodeSequence.RowFilter filter)` Create a sequence of nodes that all satisfy the supplied filter.
    `abstract long` | `getRowCount()` Get the number of rows in this sequence.
    `abstract boolean` | `isEmpty()` Determine whether this results is known to be empty.
    `protected static NodeKey` | `keyFor(CachedNode node)`
    `static NodeSequence` | `limit(NodeSequence sequence, Limit limitAndOffset)` Create a sequence of nodes that skips a specified number of nodes before returning any nodes and that limits the number of nodes returned.
    `static NodeSequence` | `limit(NodeSequence sequence, long maxRows)` Create a sequence of nodes that returns at most the supplied number of rows.
    `static NodeSequence` | `merging(NodeSequence first, NodeSequence second, int totalWidth)` Create a sequence of nodes that merges the two supplied sequences.
    `abstract NodeSequence.Batch` | `nextBatch()` Get the next batch of `NodeKey` instances.
    `static NodeSequence.RowFilter` | `requireBoth(NodeSequence.RowFilter first, NodeSequence.RowFilter second)`
    `static NodeSequence.RowFilter` | `requireEither(NodeSequence.RowFilter first, NodeSequence.RowFilter second)`
    `static NodeSequence` | `skip(NodeSequence sequence, int skip)` Create a sequence of nodes that skips a specified number of rows before returning any rows.
    `abstract int` | `width()` Get the number of nodes in each row.
    `static NodeSequence` | `withBatch(NodeSequence.Batch sequence)` Create a sequence of nodes that returns the supplied single batch of nodes.
    `static NodeSequence` | `withBatches(Collection<NodeSequence.Batch> batches, int width)` Create a sequence of nodes that iterates over the supplied batches of nodes.
    `static NodeSequence` | `withBatches(Iterator<NodeSequence.Batch> batches, int width, long rowCount)` Create a sequence of nodes that iterates over the supplied batches of nodes.
    `static NodeSequence` | `withNode(CachedNode node, int width, float score, String workspaceName)`
    `static NodeSequence` | `withNodeKeys(Collection<NodeKey> keys, float score, String workspaceName, NodeCache cache)` Create a sequence of nodes that iterates over the supplied node keys.
    `static NodeSequence` | `withNodeKeys(Collection<NodeKey> keys, float score, String workspaceName, RepositoryCache repository)` Create a sequence of nodes that iterates over the supplied node keys.
    `static NodeSequence` | `withNodeKeys(Iterator<NodeKey> keys, long keyCount, float score, String workspaceName, NodeCache cache)` Create a sequence of nodes that iterates over the supplied node keys.
    `static NodeSequence` | `withNodeKeys(Iterator<NodeKey> keys, long keyCount, float score, String workspaceName, RepositoryCache repository)` Create a sequence of nodes that iterates over the supplied node keys.
    `static NodeSequence` | `withNodes(Collection<CachedNode> nodes, float score, String workspaceName)` Create a sequence of nodes that iterates over the supplied nodes.
    `static NodeSequence` | `withNodes(Iterator<CachedNode> nodes, long nodeCount, float score, String workspaceName)` Create a sequence of nodes that iterates over the supplied nodes.

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

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

- - ### Field Detail

    - #### LOGGER

          protected static final Logger LOGGER

    - #### NO_PASS_ROW_FILTER

          public static final NodeSequence.RowFilter NO_PASS_ROW_FILTER

    - #### PASS_ROW_FILTER

          public static final NodeSequence.RowFilter PASS_ROW_FILTER

  - ### Constructor Detail

    - #### NodeSequence

          public NodeSequence()

  - ### Method Detail

    - #### width

          public abstract int width()

      Get the number of nodes in each row.
      Returns:
        the width of each row; always positive

    - #### getRowCount

          public abstract long getRowCount()

      Get the number of rows in this sequence. If the actual number of rows is not known, this method returns -1.
      Returns:
        the number of rows, or -1 if the number of rows is not known or cannot be found with significant overhead

    - #### isEmpty

          public abstract boolean isEmpty()

      Determine whether this results is known to be empty.
      Returns:
        the true if there are no results, or false if there is at least some or if the number of rows is not known

    - #### nextBatch

          public abstract NodeSequence.Batch nextBatch()

      Get the next batch of `NodeKey` instances.
      Returns:
        the next batch, or null if there are no more batches.

    - #### close

          public abstract void close()

      Signal that this node sequence is no longer needed.

    - #### emptySequence

          public static NodeSequence emptySequence(int width)

      Get an empty node sequence.
      Parameters:
        `width` - the width of the batches; must be positive
      Returns:
        the empty node sequence; never null

    - #### emptyBatch

          public static NodeSequence.Batch emptyBatch(String workspaceName,
                                      int width)

      Get a batch of nodes that is empty.
      Parameters:
        `workspaceName` - the name of the workspace
        `width` - the width of the batch; must be positive
      Returns:
        the empty node batch; never null

    - #### withBatch

          public static NodeSequence withBatch(NodeSequence.Batch sequence)

      Create a sequence of nodes that returns the supplied single batch of nodes.
      Parameters:
        `sequence` - the node keys to be returned; if null, an `empty instance` is returned
      Returns:
        the sequence of nodes; never null

    - #### withBatches

          public static NodeSequence withBatches(Collection<NodeSequence.Batch> batches,
                                 int width)

      Create a sequence of nodes that iterates over the supplied batches of nodes. Note that the supplied iterator is accessed lazily as the resulting sequence instance is `used`.
      Parameters:
        `batches` - the iterable container containing the node batches to be returned; if null, an `empty instance` is returned
        `width` - the width of the batch; must be positive
      Returns:
        the sequence of nodes; never null

    - #### withBatches

          public static NodeSequence withBatches(Iterator<NodeSequence.Batch> batches,
                                 int width,
                                 long rowCount)

      Create a sequence of nodes that iterates over the supplied batches of nodes. Note that the supplied iterator is accessed lazily as the resulting sequence instance is `used`.
      Parameters:
        `batches` - the iterator over the nodes to be returned; if null, an `empty instance` is returned
        `width` - the width of the batch; must be positive, and must be the width of all the batches
        `rowCount` - the number of rows in the batches; must be -1 if not known, 0 if known to be empty, or a positive number if the number of rows is known
      Returns:
        the sequence of nodes; never null
      See Also:
        `withBatches(Collection, int)`

    - #### withNodes

          public static NodeSequence withNodes(Collection<CachedNode> nodes,
                               float score,
                               String workspaceName)

      Create a sequence of nodes that iterates over the supplied nodes. Note that the supplied iterator is accessed lazily as the resulting sequence's `first batch` is `used`.
      Parameters:
        `nodes` - the iterator over the nodes to be returned; if null, an `empty instance` is returned
        `score` - the score to return for all of the nodes
        `workspaceName` - the name of the workspace in which all of the nodes exist
      Returns:
        the sequence of nodes; never null

    - #### withNodes

          public static NodeSequence withNodes(Iterator<CachedNode> nodes,
                               long nodeCount,
                               float score,
                               String workspaceName)

      Create a sequence of nodes that iterates over the supplied nodes. Note that the supplied iterator is accessed lazily as the resulting sequence's `first batch` is `used`.
      Parameters:
        `nodes` - the iterator over the node keys to be returned; if null, an `empty instance` is returned
        `nodeCount` - the number of nodes in the iterator; must be -1 if not known, 0 if known to be empty, or a positive number if the number of nodes is known
        `score` - the score to return for all of the nodes
        `workspaceName` - the name of the workspace in which all of the nodes exist
      Returns:
        the sequence of nodes; never null

    - #### withNode

          public static NodeSequence withNode(CachedNode node,
                              int width,
                              float score,
                              String workspaceName)

    - #### withNodeKeys

          public static NodeSequence withNodeKeys(Collection<NodeKey> keys,
                                  float score,
                                  String workspaceName,
                                  RepositoryCache repository)

      Create a sequence of nodes that iterates over the supplied node keys. Note that the supplied iterator is accessed lazily as the resulting sequence's `first batch` is `used`.
      Parameters:
        `keys` - the iterator over the keys of the nodes to be returned; if null, an `empty instance` is returned
        `score` - the score to return for all of the nodes
        `workspaceName` - the name of the workspace in which all of the nodes exist
        `repository` - the repository cache used to access the workspaces and cached nodes; may be null only if the key sequence is null or empty
      Returns:
        the sequence of nodes; never null

    - #### withNodeKeys

          public static NodeSequence withNodeKeys(Collection<NodeKey> keys,
                                  float score,
                                  String workspaceName,
                                  NodeCache cache)

      Create a sequence of nodes that iterates over the supplied node keys. Note that the supplied iterator is accessed lazily as the resulting sequence's `first batch` is `used`.
      Parameters:
        `keys` - the iterator over the keys of the nodes to be returned; if null, an `empty instance` is returned
        `score` - the score to return for all of the nodes
        `workspaceName` - the name of the workspace in which all of the nodes exist
        `cache` - the cache used to access the cached nodes; may be null only if the key sequence is null or empty
      Returns:
        the sequence of nodes; never null

    - #### withNodeKeys

          public static NodeSequence withNodeKeys(Iterator<NodeKey> keys,
                                  long keyCount,
                                  float score,
                                  String workspaceName,
                                  RepositoryCache repository)

      Create a sequence of nodes that iterates over the supplied node keys. Note that the supplied iterator is accessed lazily as the resulting sequence's `first batch` is `used`.
      Parameters:
        `keys` - the iterator over the keys of the node keys to be returned; if null, an `empty instance` is returned
        `keyCount` - the number of node keys in the iterator; must be -1 if not known, 0 if known to be empty, or a positive number if the number of node keys is known
        `score` - the score to return for all of the nodes
        `workspaceName` - the name of the workspace in which all of the nodes exist
        `repository` - the repository cache used to access the workspaces and cached nodes; may be null only if the key sequence is null or empty
      Returns:
        the sequence of nodes; never null

    - #### withNodeKeys

          public static NodeSequence withNodeKeys(Iterator<NodeKey> keys,
                                  long keyCount,
                                  float score,
                                  String workspaceName,
                                  NodeCache cache)

      Create a sequence of nodes that iterates over the supplied node keys. Note that the supplied iterator is accessed lazily as the resulting sequence's `first batch` is `used`.
      Parameters:
        `keys` - the iterator over the keys of the node keys to be returned; if null, an `empty instance` is returned
        `keyCount` - the number of node keys in the iterator; must be -1 if not known, 0 if known to be empty, or a positive number if the number of node keys is known
        `score` - the score to return for all of the nodes
        `workspaceName` - the name of the workspace in which all of the nodes exist
        `cache` - the node cache used to access the cached nodes; may be null only if the key sequence is null or empty
      Returns:
        the sequence of nodes; never null

    - #### limit

          public static NodeSequence limit(NodeSequence sequence,
                           Limit limitAndOffset)

      Create a sequence of nodes that skips a specified number of nodes before returning any nodes and that limits the number of nodes returned.
      Parameters:
        `sequence` - the original sequence that is to be limited; may be null
        `limitAndOffset` - the specification of the offset and limit; if null this method simply returns `sequence`
      Returns:
        the limitd sequence of nodes; never null

    - #### limit

          public static NodeSequence limit(NodeSequence sequence,
                           long maxRows)

      Create a sequence of nodes that returns at most the supplied number of rows.
      Parameters:
        `sequence` - the original sequence that is to be limited; may be null
        `maxRows` - the maximum number of rows that are to be returned by the sequence; should be positive or this method simply returns `sequence`
      Returns:
        the sequence of 'maxRows' nodes; never null

    - #### skip

          public static NodeSequence skip(NodeSequence sequence,
                          int skip)

      Create a sequence of nodes that skips a specified number of rows before returning any rows.
      Parameters:
        `sequence` - the original sequence that is to be limited; may be null
        `skip` - the number of initial rows that should be skipped; should be positive or this method simply returns `sequence`
      Returns:
        the sequence of nodes after the first `skip` nodes are skipped; never null

    - #### filter

          public static NodeSequence filter(NodeSequence sequence,
                            NodeSequence.RowFilter filter)

      Create a sequence of nodes that all satisfy the supplied filter.
      Parameters:
        `sequence` - the original sequence that is to be limited; may be null
        `filter` - the filter to apply to the nodes; if null this method simply returns `sequence`
      Returns:
        the sequence of filtered nodes; never null

    - #### append

          public static NodeSequence append(NodeSequence first,
                            NodeSequence second)

      Create a sequence of nodes that contains the nodes from the first sequence followed by the second sequence.
      Parameters:
        `first` - the first sequence; may be null
        `second` - the second sequence; may be null
      Returns:
        the new combined sequence; never null
      Throws:
        `IllegalArgumentException` - if the sequences have different widths

    - #### merging

          public static NodeSequence merging(NodeSequence first,
                             NodeSequence second,
                             int totalWidth)

      Create a sequence of nodes that merges the two supplied sequences.
      Parameters:
        `first` - the first sequence; may be null
        `second` - the second sequence; may be null
        `totalWidth` - the total width of the sequences; should be equal to `first.getWidth() + second.getWidth()`
      Returns:
        the new merged sequence; never null

    - #### batchOf

          public static NodeSequence.Batch batchOf(Collection<CachedNode> nodes,
                                   float score,
                                   String workspaceName)

      Create a batch of nodes around the supplied iterable container. Note that the supplied iterator is accessed lazily only when the batch is `used`.
      Parameters:
        `nodes` - the collection of nodes to be returned; if null, an `empty instance` is returned
        `score` - the score to return for all of the nodes
        `workspaceName` - the name of the workspace in which all of the nodes exist
      Returns:
        the batch of nodes; never null

    - #### batchOf

          public static NodeSequence.Batch batchOf(Iterator<CachedNode> nodes,
                                   long nodeCount,
                                   float score,
                                   String workspaceName)

      Create a batch of nodes around the supplied iterator. Note that the supplied iterator is accessed lazily only when the batch is `used`.
      Parameters:
        `nodes` - the iterator over the nodes to be returned; if null, an `empty instance` is returned
        `nodeCount` - the number of nodes in the iterator; must be -1 if not known, 0 if known to be empty, or a positive number if the number of nodes is known
        `score` - the score to return for all of the nodes
        `workspaceName` - the name of the workspace in which all of the nodes exist
      Returns:
        the batch of nodes; never null

    - #### batchOfKeys

          public static NodeSequence.Batch batchOfKeys(Collection<NodeKey> keys,
                                       float score,
                                       String workspaceName,
                                       RepositoryCache repository)

      Create a batch of nodes around the supplied iterable container. Note that the supplied iterator is accessed lazily only when the batch is `used`.
      Parameters:
        `keys` - the iterator over the keys of the nodes to be returned; if null, an `empty instance` is returned
        `score` - the score to return for all of the nodes
        `workspaceName` - the name of the workspace in which all of the nodes exist
        `repository` - the repository cache used to access the workspaces and cached nodes; may be null only if the key sequence is null or empty
      Returns:
        the batch of nodes; never null

    - #### batchOfKeys

          public static NodeSequence.Batch batchOfKeys(Iterator<NodeKey> keys,
                                       long nodeCount,
                                       float score,
                                       String workspaceName,
                                       NodeCache cache)

      Create a batch of nodes around the supplied iterator. Note that the supplied iterator is accessed lazily only when the batch is `used`.
      Parameters:
        `keys` - the iterator over the keys of the nodes to be returned; if null, an `empty instance` is returned
        `nodeCount` - the number of nodes in the iterator; must be -1 if not known, 0 if known to be empty, or a positive number if the number of nodes is known
        `score` - the score to return for all of the nodes
        `workspaceName` - the name of the workspace in which all of the nodes exist
        `cache` - the workspace cache used to access the cached nodes; may be null only if the key sequence is null or empty
      Returns:
        the batch of nodes; never null

    - #### batchOfKeys

          public static NodeSequence.Batch batchOfKeys(Iterator<NodeKey> keys,
                                       long nodeCount,
                                       float score,
                                       String workspaceName,
                                       RepositoryCache repository)

      Create a batch of nodes around the supplied iterator. Note that the supplied iterator is accessed lazily only when the batch is `used`.
      Parameters:
        `keys` - the iterator over the keys of the nodes to be returned; if null, an `empty instance` is returned
        `nodeCount` - the number of nodes in the iterator; must be -1 if not known, 0 if known to be empty, or a positive number if the number of nodes is known
        `score` - the score to return for all of the nodes
        `workspaceName` - the name of the workspace in which all of the nodes exist
        `repository` - the repository cache used to access the workspaces and cached nodes; may be null only if the key sequence is null or empty
      Returns:
        the batch of nodes; never null

    - #### batchOfKeys

          public static NodeSequence.Batch batchOfKeys(Iterator<NodeKey> keys,
                                       Iterator<Float> scores,
                                       long nodeCount,
                                       String workspaceName,
                                       RepositoryCache repository)

      Create a batch of nodes around the supplied iterator and the scores iterator. Note that the supplied iterators are accessed lazily only when the batch is `used`.
      Parameters:
        `keys` - the iterator over the keys of the nodes to be returned; if null, an `empty instance` is returned
        `scores` - the iterator over the scores of the nodes; must return the same number of values as nodes returned by the `keys` iterator
        `nodeCount` - the number of nodes in the iterator; must be -1 if not known, 0 if known to be empty, or a positive number if the number of nodes is known
        `workspaceName` - the name of the workspace in which all of the nodes exist
        `repository` - the repository cache used to access the workspaces and cached nodes; may be null only if the key sequence is null or empty
      Returns:
        the batch of nodes; never null

    - #### batchOf

          protected static NodeSequence.Batch batchOf(NodeSequence.Batch first,
                                   NodeSequence.Batch second,
                                   int firstWidth,
                                   int secondWidth)

    - #### keyFor

          protected static final NodeKey keyFor(CachedNode node)

    - #### requireBoth

          public static NodeSequence.RowFilter requireBoth(NodeSequence.RowFilter first,
                                           NodeSequence.RowFilter second)

    - #### requireEither

          public static NodeSequence.RowFilter requireEither(NodeSequence.RowFilter first,
                                             NodeSequence.RowFilter second)

    - #### batchFilteredWith

          public static NodeSequence.Batch batchFilteredWith(NodeSequence.Batch batch,
                                             NodeSequence.RowFilter filter)

      Create a batch that applies the given filter to the supplied batch. Only rows that satisfy the filter will be exposed by this batch. Note that this batch maintains nor caches any rows, and walks the supplied batch as needed (rather than up front). Therefore, the `getRowCount()` is almost always -1 (except when the supplied batch is null or empty, or if the filter is null.
      Parameters:
        `batch` - the batch to be filtered; if null an empty batch is returned
        `filter` - the filter to be applied to the rows in the batch; if null an empty batch is returned
      Returns:
        the filtered batch, or an empty batch if the supplied batch is null or empty, or if the supplied filter is null

    - #### batchWithCount

          public static NodeSequence.Batch batchWithCount(NodeSequence.Batch batch)

      Create a batch that always has a `NodeSequence.Batch.rowCount()`, even if that means returning a new Batch that buffers the original's rows it into memory.
      Parameters:
        `batch` - the original batch; may be null
      Returns:
        the batch that has a true `NodeSequence.Batch.rowCount()`, or the original batch if null or empty or if the original has a non-negative row count

    - #### copy

          public static NodeSequence.Batch copy(NodeSequence.Batch batch)

      Create a copy of a batch that always has a `NodeSequence.Batch.rowCount()`.
      Parameters:
        `batch` - the original batch; may be null
      Returns:
        the batch that has a true `NodeSequence.Batch.rowCount()`, or the original batch if null or empty or if the original has a non-negative row count

Copyright © 2008-2014 JBoss, a division of Red Hat. All Rights Reserved.