Hi,
The paging state is null as soon as the driver has retrieved the last page. The rows of the last page are still in the local cache at this point.
To summarize what's happening internally:
1) query 1 with paging state = null
2) receive response with 10 rows and paging state = xyz
3) add those 10 rows to local cache
4) as user iterates, pop rows from local cache
5) if local cache empty or fetchMoreResults called => query 2 with paging state = xyz
6) receive response with 5 rows and paging state = null (indicating the server has no more pages)
7) add those 5 rows to local cache
8) as user iterates, pop rows from local cache
9) local cache empty => signal no more results
If your condition to stop the iteration is "getPagingState() == null", you stop at step 6, with 5 rows still not returned to the user.
On a side note, if your only goal is to transform the iterator with a function, why deal with paging at all? You could just have hasNext() and next() call the internal iterator directly, and let it deal with paging.
Or better yet, use Guava's Iterators.transform.