MultiPartitionPager (apache-cassandra API)
Date: 2018-02-14

org.apache.cassandra.service.pager

## Class MultiPartitionPager

- java.lang.Object
- - org.apache.cassandra.service.pager.MultiPartitionPager

- All Implemented Interfaces:
    QueryPager

      public class MultiPartitionPager
      extends java.lang.Object
      implements QueryPager

  Pager over a list of ReadCommand. Note that this is not easy to make efficient. Indeed, we need to page the first command fully before returning results from the next one, but if the result returned by each command is small (compared to pageSize), paging the commands one at a time under-performs compared to parallelizing. On the other, if we parallelize and each command raised pageSize results, we'll end up with commands.size() * pageSize results in memory, which defeats the purpose of paging. For now, we keep it simple (somewhat) and just do one command at a time. Provided that we make sure to not create a pager unless we need to, this is probably fine. Though if we later want to get fancy, we could use the cfs meanPartitionSize to decide if parallelizing some of the command might be worth it while being confident we don't blow out memory.

- - ### Field Summary

    - ### Fields inherited from interface org.apache.cassandra.service.pager.QueryPager

      `EMPTY`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `MultiPartitionPager(SinglePartitionReadCommand.Group group, PagingState state, ProtocolVersion protocolVersion)`

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `ReadExecutionController` | `executionController()` Starts a new read operation.
    `PartitionIterator` | `fetchPage(int pageSize, ConsistencyLevel consistency, ClientState clientState, long queryStartNanoTime)` Fetches the next page.
    `PartitionIterator` | `fetchPageInternal(int pageSize, ReadExecutionController executionController)` Fetches the next page internally (in other, this does a local query).
    `boolean` | `isExhausted()` Whether or not this pager is exhausted, i.e.
    `int` | `maxRemaining()` The maximum number of cells/CQL3 row that we may still have to return.
    `PagingState` | `state()` Get the current state of the pager.
    `QueryPager` | `withUpdatedLimit(DataLimits newLimits)` Creates a new `QueryPager` that use the new limits.

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

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

- - ### Constructor Detail

    - #### MultiPartitionPager

          public MultiPartitionPager(SinglePartitionReadCommand.Group group,
                                     PagingState state,
                                     ProtocolVersion protocolVersion)

  - ### Method Detail

    - #### withUpdatedLimit

          public QueryPager withUpdatedLimit(DataLimits newLimits)

      Description copied from interface: `QueryPager`
      Creates a new `QueryPager` that use the new limits.
      Specified by:
        `withUpdatedLimit` in interface `QueryPager`
      Parameters:
        `newLimits` - the new limits
      Returns:
        a new `QueryPager` that use the new limits

    - #### state

          public PagingState state()

      Description copied from interface: `QueryPager`
      Get the current state of the pager. The state can allow to restart the paging on another host from where we are at this point.
      Specified by:
        `state` in interface `QueryPager`
      Returns:
        the current paging state. Will return null if paging is at the beginning. If the pager is exhausted, the result is undefined.

    - #### isExhausted

          public boolean isExhausted()

      Description copied from interface: `QueryPager`
      Whether or not this pager is exhausted, i.e. whether or not a call to fetchPage may return more result.
      Specified by:
        `isExhausted` in interface `QueryPager`
      Returns:
        whether the pager is exhausted.

    - #### executionController

          public ReadExecutionController executionController()

      Description copied from interface: `QueryPager`
      Starts a new read operation.

      This must be called before `fetchPageInternal` and passed to it to protect the read. The returned object must be closed on all path and it is thus strongly advised to use it in a try-with-ressource construction.

      Specified by:
        `executionController` in interface `QueryPager`
      Returns:
        a newly started order group for this `QueryPager`.

    - #### fetchPage

          public PartitionIterator fetchPage(int pageSize,
                                             ConsistencyLevel consistency,
                                             ClientState clientState,
                                             long queryStartNanoTime)
                                      throws RequestValidationException,
                                             RequestExecutionException

      Description copied from interface: `QueryPager`
      Fetches the next page.
      Specified by:
        `fetchPage` in interface `QueryPager`
      Parameters:
        `pageSize` - the maximum number of elements to return in the next page.
        `consistency` - the consistency level to achieve for the query.
        `clientState` - the `ClientState` for the query. In practice, this can be null unless `consistency` is a serial consistency.
      Returns:
        the page of result.
      Throws:
        `RequestValidationException`
        `RequestExecutionException`

    - #### fetchPageInternal

          public PartitionIterator fetchPageInternal(int pageSize,
                                                     ReadExecutionController executionController)
                                              throws RequestValidationException,
                                                     RequestExecutionException

      Description copied from interface: `QueryPager`
      Fetches the next page internally (in other, this does a local query).
      Specified by:
        `fetchPageInternal` in interface `QueryPager`
      Parameters:
        `pageSize` - the maximum number of elements to return in the next page.
        `executionController` - the `ReadExecutionController` protecting the read.
      Returns:
        the page of result.
      Throws:
        `RequestValidationException`
        `RequestExecutionException`

    - #### maxRemaining

          public int maxRemaining()

      Description copied from interface: `QueryPager`
      The maximum number of cells/CQL3 row that we may still have to return. In other words, that's the initial user limit minus what we've already returned (note that it's not how many we *will* return, just the upper limit on it).
      Specified by:
        `maxRemaining` in interface `QueryPager`

Copyright © 2018 The Apache Software Foundation