Package io.permazen.util

Class NavigableSetPager<E>

java.lang.Object
io.permazen.util.NavigableSetPager<E>
Type Parameters:
E - set element type
public abstract class NavigableSetPager<E> extends Object
Allows efficient forward and backward paging through a NavigableSet.

Instances are configured with a page size and a view ordering (ascending or descending).

Instances maintain a cursor position that anchors one "page" of consecutive items within the set. Each time readCurrentPage() is invoked, the set is reacquired from getNavigableSet() and the contents of the current page are read from it.

For navigation, nextPage() and prevPage() move to the next or previous page, firstPage() and lastPage() jump to the first or last page. After movement, hasNextPage() and hasPrevPage() indicate whether adjacent pages exist.

The view ordering can be either ascending (default) or descending. With descending view ordering, the set is viewed in reverse, i.e., as if viewing the result of NavigableSet.descendingSet().

  • Field Details

  • Constructor Details

    • NavigableSetPager

      public NavigableSetPager()

  • Method Details

    • getPageSize

      public int getPageSize()
      Get the page size.
      Returns:
      maximum number of rows in a page, always greater than zero

    • setPageSize

      public void setPageSize(int pageSize)
      Set the page size.
      Parameters:
      pageSize - maximum number of rows in a page
      Throws:
      IllegalArgumentException - if pageSize is zero or less

    • isDescending

      public boolean isDescending()
      Get the view ordering. Default is ascending.
      Returns:
      false if container order is ascending, true if descending

    • setDescending

      public void setDescending(boolean descending)
      Set the view ordering.
      Parameters:
      descending - true for descending view, false for ascending view

    • reverseViewOrdering

      public void reverseViewOrdering()
      Reverse the view ordering.

      Equivalent to this.setDescending(!this.isDescending()).

    • setFilter

      public void setFilter(Predicate<? super E> filter)
      Filter which items in the set are returned.

      Items that fail to pass the specified filter are omitted from the results and do not contribute to the page total. Beware that a filter can reject arbitrarily many items and therefore when using filters the time it takes to load a full page is potentially unbounded.

      Parameters:
      filter - filter that accepts only the desired items, or null to accept all

    • hasNextPage

      public boolean hasNextPage()
      Indicates that there are more results after the current page.
      Returns:
      true if there are more results in the forward direction, false if we are on the last page

    • hasPrevPage

      public boolean hasPrevPage()
      Indicates that there are more results before the current page.
      Returns:
      true if there are more results in the reverse direction, false if we are on the first page

    • nextPage

      public boolean nextPage()
      Advance forward to the next page of results, if any.

      This will advance to the next higher page of results if configured for an ascending view, or the next lower page of results if configured for a descending view.

      After invoking this method, readCurrentPage() must be invoked for it to take effect. Duplicate invocations of this method without an intervening call to readCurrentPage() will have no effect and return false.

      Returns:
      true if successful, false if we were already on the last page

    • prevPage

      public boolean prevPage()
      Advance backward to the previous page of results, if any.

      This will regress to be the next lower page of results if configured for an ascending view, or the next higher page of results if configured for a descending view.

      After invoking this method, readCurrentPage() must be invoked for it to take effect. Duplicate invocations of this method without an intervening call to readCurrentPage() will have no effect and return false.

      Returns:
      true if successful, false if we were already on the first page

    • firstPage

      public void firstPage()
      Jump to the first page.

    • lastPage

      public void lastPage()
      Jump to the last page.

    • setCursor

      public void setCursor(E cursor)
      Set the current cursor position, i.e., page anchor.

      The next page returned by readCurrentPage() will start at cursor, inclusive for an ascending ordering or exclusive for a descending ordering.

      The cursor must not be null unless the underlying NavigableSet supports null values.

      Parameters:
      cursor - new cursor position for the current page

    • getPageNumber

      public int getPageNumber()
      Get the current page number, if known.

      This method returns either a positive or negative number depending on whether the start or the end of the data has been most recently reached. Positive values (1, 2, 3, ...) count pages from the start of the data; negative values (-1, -2, -3, ...) count pages from the end of the data.

      If setCursor(E) has been invoked since the last time we hit the beginning or the end of the data, then the current page number is unknown and this method returns zero.

      The correctness of this method depends on the underlying data not changing. For example, if nextPage() is invoked five times and then prevPage() is invoked two times, this method returns a value three higher than before, regardless of whether items were concurrently added or removed from the underlying set. The page number is only guaranteed to be accurate if the set hasn't changed since we most recently reached the start or end of the data.

      Returns:
      current page number, or zero if unknown

    • readCurrentPage

      public List<E> readCurrentPage()
      Read the contents of the current page.

      The list is read starting from the current cursor position (inclusive for an ascending ordering, exclusive for a descending ordering).

      If configured for an ascending view, the list will have ascending ordering; if configured for a descending view, the list will have descending ordering.

      Returns:
      list of items in the current page

    • getNavigableSet

      protected abstract NavigableSet<E> getNavigableSet()
      Get the NavigableSet through which to page.

      This method is invoked anew each time readCurrentPage() is invoked.

      Returns:
      the entire query domain in ascending order