Package uk.ac.ebi.utils.collections

Class PaginationIterator<P,E>

java.lang.Object
uk.ac.ebi.utils.collections.PaginationIterator<P,E>
Type Parameters:
P - the page the iterator deals with. Examples: a number, an API bookmark value, anything that allows a page element provider to produce an element iterator from a page. In particular, this could be the page element iterator itself, with the page elements provider being the identity function (see offsetBasedPageIterator(Function, long)).
E - the elements that the iterator returns by switching from one page to the next. The page elements provider in the constructors yield an iterator that iterates over the elements of a (current) page.
All Implemented Interfaces:
Iterator<E>
public class PaginationIterator<P,E> extends Object implements Iterator<E>
A generic helper to build a pagination iteration. The idea is that a page iterator offers a new page P every time it is asked and a page elements function yields an iterator over the elements of a page. This very abstract model can be applied to a big number of sources that need to be queried with pagination, eg, databases or APIs.
Author:
Marco Brandizi
Date:
7 Oct 2024

  • Constructor Details

    • PaginationIterator

      public PaginationIterator(Iterator<? extends P> pageIterator, Function<? super P,? extends Iterator<? extends E>> pageElementsProvider)
      Parameters:
      pageIterator - as said above, this provides a new page every time that's needed.
      pageElementsProvider - as said above, this provides an iterator over the elements of the parameter page. The pagination iterator works by asking a new page, asking the page elements iterator, iterating on the latter until exhaustion and going back to ask the next page as more elements are requested, terminating when the page iterator is exhausted too.

    • PaginationIterator

      public PaginationIterator(Function<Long,? extends P> nextPageSelector, long pageSize, Function<? super P,? extends Iterator<? extends E>> pageElementsProvider)
      Builds the page iterator using offsetBasedPageIterator(Function, long).

  • Method Details

    • offsetBasedPageIterator

      public static <P> Iterator<P> offsetBasedPageIterator(Function<Long,? extends P> nextPageSelector, long pageSize)
      Builds a page iterator for PaginationIterator that moves from one page to the next based on pageSize and returns a page based on the selector function.
      Parameters:
      nextPageSelector - yields a page, from an offset parameter, ie, an element index that says where we are in the data source. Eg, the value passed to SKIP or OFFSET in an SQL query. Since this is based on IteratorUtils.supplier2Iterator(java.util.function.Supplier), this function must return null when (and only when) there aren't further pages to iterate through. Note that the result of this could be the same as the page elements iterator, eg, you might have a paged SQL (or API) that issues a query with the current page and returns the database cursor/result-set if the hasNext() method of the latter is true, else it returns null.
      pageSize - the resulting iterator increases an internal offset by this amount every time a new page P has to be produced. The page selector receives this offset when needed to produce the page.

    • hasNext

      public boolean hasNext()
      See PaginationIterator(Iterator, Function) for details on how we loop.
      Specified by:
      hasNext in interface Iterator<P>

    • next

      public E next()
      See PaginationIterator(Iterator, Function) for details on how we loop.
      Specified by:
      next in interface Iterator<P>