com.google.appengine.api.search

## Class Cursor

- java.lang.Object
- - com.google.appengine.api.search.Cursor

- All Implemented Interfaces:
    java.io.Serializable

      public final class Cursor
      extends java.lang.Object
      implements java.io.Serializable

  Represents a cursor on the set of results found for executing a `Query` during a search on the `Index`.

  For example, the following code shows how to use a cursor to get the next page of results

       Index index = ...
       Cursor cursor = Cursor.newBuilder().build();
       Query query = Query.newBuilder().setOptions(
           QueryOptions.newBuilder().setCursor(cursor).build("some query"));

       // Get the first page of results
       Results<ScoredDocument> results = index.search(query);

       // process results
       ...

       // Get the next set of results from the returned cursor
       query = Query.newBuilder().setOptions(
           QueryOptions.newBuilder().setCursor(
               results.getCursor()).build("some query"));

       results = index.search(query);

  Alternatively, you can get a cursor to continue from each of the returned results.

       Cursor cursor =
           Cursor.newBuilder().setPerResult(true).build();
       Query query = Query.newBuilder().setOptions(
           QueryOptions.newBuilder().setCursor(cursor).build("some query"));

       // Get the first page of results
       Results<ScoredDocument> results = index.search(query);

       // process results
       for (ScoredDocument result : results) {
         // choose a cursor from one of the results
         cursor = result.getCursor();
       }

       // Get the next set of results from the result's cursor
       query = Query.newBuilder().setOptions(
           QueryOptions.newBuilder().setCursor(cursor).build("some query"));

       results = index.search(query);

  See Also:
    Serialized Form

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `Cursor.Builder` A builder which constructs Cursor objects.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `boolean` | `isPerResult()`
    `static Cursor.Builder` | `newBuilder()` Creates and returns a `Cursor` builder.
    `static Cursor.Builder` | `newBuilder(Cursor request)` Creates a builder from the given request.
    `java.lang.String` | `toString()`
    `java.lang.String` | `toWebSafeString()` A web safe string representing a cursor returned from a previous set of search results to use as a starting point to retrieve the next set of results.

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

      `equals, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- - ### Method Detail

    - #### toWebSafeString

          public java.lang.String toWebSafeString()

      A web safe string representing a cursor returned from a previous set of search results to use as a starting point to retrieve the next set of results. Can be null.
      Returns:
        a web safe string representation of the cursor

    - #### isPerResult

          public boolean isPerResult()

      Returns:
        whether the cursor is for all Results or one cursor per result

    - #### newBuilder

          public static Cursor.Builder newBuilder()

      Creates and returns a `Cursor` builder. Set the search request parameters and use the `Cursor.Builder.build()` method to create a concrete instance of Cursor.
      Returns:
        a `Cursor.Builder` which can construct a search request

    - #### newBuilder

          public static Cursor.Builder newBuilder(Cursor request)

      Creates a builder from the given request.
      Parameters:
        `request` - the search request for the builder to use to build another request
      Returns:
        this builder

    - #### toString

          public java.lang.String toString()

      Overrides:
        `toString` in class `java.lang.Object`