Paging Support with the Space Iterator API

If a collection of entries must be returned from the Space, this is usually carried out using one of the readMultiple overloads in GigaSpace. However, if there are a lot of matching entries, you may encounter several problems:

  • Memory usage - Both the server and client must allocate enough memory for the entire result set.
  • Latency - Because all the results are returned in a single batch, the client must wait until the final result arrives before it can process the first one.

A better approach is to create an iterator that iterates over the matching entries one at a time. Under the hood, the server returns the results in batches, and when the client's buffer is exhausted the next batch is implicitly returned from the server.

This page describes the new Space iterator, which is intended to replace the old GSIterator starting from GigaSpaces version 10.1. Information about the old GSIterator is available here.

Using the Space Iterator API

Use the GigaSpaceiterator(template) method to create an iterator of all the objects in the Space that match the template (either SQLQuery or template). This results in a SpaceIterator<T>, which implements both Iterator<T> and Iterable<T>, so a simple for-each loopand can be used to iterate the results. For example:

private void demoIterator(GigaSpace gigaSpace) {
    SQLQuery<MySpaceClass> query = new SQLQuery(MySpaceClass.class,"lastName = 'Smith'");
    int counter = 0;
    for (MySpaceClass entry : gigaSpace.iterator(query)) {
        System.out.println((counter++ ) + " " + entry.getLastName());

If you're using Java 8 or later, you may use the new "forEach` extension with a lambda expression:

private void demoForEach(GigaSpace gigaSpace) {
    SQLQuery<MySpaceClass> query = new SQLQuery(MySpaceClass.class,"lastName = 'Smith'");
    AtomicInteger counter = new AtomicInteger();
    SpaceIterator<MySpaceClass> spaceIterator = gigaSpace.iterator(query);			
    spaceIterator.forEach((e) -> System.out.println(counter.incrementAndGet() + " " + e.getLastName()));

Batch Size

Under the hood, the iterator uses batching to fetch entries from the server, then serves the entries from the batch to the client whenever it asks for the next entry. The default batch size is 100. You can use a different batch size by calling the gigaSpace.iterator(template, batchSize) overload.


Iterating through the matched set does not lock the object. Objects that are under transaction and match the specified template aren't included as part of the matched set.


The Space iterator only supports simple SQL queries. For more information about the differences between simple and complex queries, see the SQL Query Using SDK section of the SQL Query Using SDK topic.