Package org.kiwiproject.search

Class KiwiSearching

java.lang.Object
org.kiwiproject.search.KiwiSearching
public final class KiwiSearching extends Object
Utilities related to searching and pagination. Supports both zero- and one-based page numbering but the default is one-based. Use the methods that accept KiwiSearching.PageNumberingScheme to work with either zero- or one-based numbering.

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static enum 
    KiwiSearching.PageNumberingScheme
    Enum that represents either zero or one-based page numbering scheme.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final int
    DEFAULT_PAGE_SIZE
    A rather opinionated value for the default page size.
    static final String
    DEFAULT_PAGE_SIZE_AS_STRING
    The rather opinionated value for default page size as a String, in order to support web framework annotations like Jakarta REST's jakarta.ws.rs.DefaultValue that require a String.
    static final String
    PAGE_SIZE_ERROR
     

  • Method Summary

    Modifier and Type
    Method
    Description
    static void
    checkPageNumber(int pageNumber)
    Validate the given page number is greater than zero.
    static void
    checkPageNumber(int pageNumber, KiwiSearching.PageNumberingScheme numberingScheme)
    Validate the given page number is equal to or greater than the minimum for the given KiwiSearching.PageNumberingScheme.
    static void
    checkPageSize(int pageSize)
    Validate that the given page size is greater than zero.
    static int
    numberOfPages(long resultCount, int pageSize)
    Calculate the number of pages necessary to paginate the given number of results using the given page size.
    static int
    numberOnPage(long resultCount, int pageSize, int pageNumber)
    Calculate the number of results on the given page number for the given number of results and page size.
    static int
    numberOnPage(long resultCount, int pageSize, int pageNumber, KiwiSearching.PageNumberingScheme numberingScheme)
    Calculate the number of results on the given page number for the given number of results and page size, and using the given KiwiSearching.PageNumberingScheme.
    static int
    zeroBasedOffset(int pageNumber, int pageSize)
    Calculate the zero-based offset for the given page number and size using page numbers starting at one, after first validating the page number and size.
    static int
    zeroBasedOffset(int pageNumber, KiwiSearching.PageNumberingScheme numberingScheme, int pageSize)
    Calculate the zero-based offset for the given page number and size using the given page numbering scheme, after first validating the page number and size.
    static int
    zeroBasedOffsetForOneBasedPaging(int pageNumber, int pageSize)
    Calculate the zero-based offset for the given page number and size using page numbers starting at one, after first validating the page number and size.
    static int
    zeroBasedOffsetForZeroBasedPaging(int pageNumber, int pageSize)
    Calculate the zero-based offset for the given page number and size using page numbers starting at zero, after first validating the page number and size.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Field Details

    • DEFAULT_PAGE_SIZE

      public static final int DEFAULT_PAGE_SIZE
      A rather opinionated value for the default page size.
      See Also:

    • DEFAULT_PAGE_SIZE_AS_STRING

      public static final String DEFAULT_PAGE_SIZE_AS_STRING
      The rather opinionated value for default page size as a String, in order to support web framework annotations like Jakarta REST's jakarta.ws.rs.DefaultValue that require a String.
      See Also:
      Implementation Note:
      This must be a constant not an expression, otherwise trying to use it in an annotation like the Jakarta REST DefaultValue will result in a compilation error due to the vagaries of Java annotations. For example, trying to do this: DEFAULT_PAGE_SIZE_AS_STRING = String.valueOf(DEFAULT_PAGE_SIZE) and then using in an annotation like this: @DefaultValue(DEFAULT_PAGE_SIZE_AS_STRING) will result in the following compiler error: "java: element value must be a constant expression"

    • PAGE_SIZE_ERROR

      public static final String PAGE_SIZE_ERROR
      See Also:

  • Method Details

    • checkPageSize

      public static void checkPageSize(int pageSize)
      Validate that the given page size is greater than zero.
      Parameters:
      pageSize - the page size to check

    • checkPageNumber

      public static void checkPageNumber(int pageNumber)
      Validate the given page number is greater than zero. This uses one-based page numbering.
      Parameters:
      pageNumber - the page number to check
      Throws:
      IllegalArgumentException - if the page number is not greater than zero
      See Also:

    • checkPageNumber

      public static void checkPageNumber(int pageNumber, KiwiSearching.PageNumberingScheme numberingScheme)
      Validate the given page number is equal to or greater than the minimum for the given KiwiSearching.PageNumberingScheme.
      Parameters:
      pageNumber - the page number to check
      numberingScheme - the page numbering scheme to use
      Throws:
      IllegalArgumentException - if the page number is invalid according to the numbering scheme
      See Also:

    • zeroBasedOffset

      public static int zeroBasedOffset(int pageNumber, int pageSize)
      Calculate the zero-based offset for the given page number and size using page numbers starting at one, after first validating the page number and size. Useful for any data access library that requires a zero-based offset.

      This uses one-based page numbering.

      Parameters:
      pageNumber - the page number (one-based)
      pageSize - the page size
      Returns:
      the zero-based offset, e.g. for use in SQL queries using OFFSET and LIMIT
      Throws:
      IllegalArgumentException - if the page number or size is invalid
      See Also:

    • zeroBasedOffsetForOneBasedPaging

      public static int zeroBasedOffsetForOneBasedPaging(int pageNumber, int pageSize)
      Calculate the zero-based offset for the given page number and size using page numbers starting at one, after first validating the page number and size. Useful for any data access library that requires a zero-based offset.

      This method is an alias for zeroBasedOffset(int, int).

      Parameters:
      pageNumber - the page number (one-based)
      pageSize - the page size
      Returns:
      the zero-based offset, e.g. for use in SQL queries using OFFSET and LIMIT
      See Also:

    • zeroBasedOffsetForZeroBasedPaging

      public static int zeroBasedOffsetForZeroBasedPaging(int pageNumber, int pageSize)
      Calculate the zero-based offset for the given page number and size using page numbers starting at zero, after first validating the page number and size. Useful for any data access library that requires a zero-based offset.
      Parameters:
      pageNumber - the page number (zero-based)
      pageSize - the page size
      Returns:
      the zero-based offset, e.g. for use in SQL queries using OFFSET and LIMIT

    • zeroBasedOffset

      public static int zeroBasedOffset(int pageNumber, KiwiSearching.PageNumberingScheme numberingScheme, int pageSize)
      Calculate the zero-based offset for the given page number and size using the given page numbering scheme, after first validating the page number and size. Useful for any data access library that requires a zero-based offset.
      Parameters:
      pageNumber - the page number
      numberingScheme - the page numbering scheme to use
      pageSize - the page size
      Returns:
      the zero-based offset, e.g. for use in SQL queries using OFFSET and LIMIT
      Throws:
      IllegalArgumentException - if the page number or size is invalid
      See Also:

    • numberOfPages

      public static int numberOfPages(long resultCount, int pageSize)
      Calculate the number of pages necessary to paginate the given number of results using the given page size.
      Parameters:
      resultCount - the total number of results to paginate
      pageSize - the size of each page
      Returns:
      the number of pages
      Throws:
      IllegalArgumentException - if the page size is invalid

    • numberOnPage

      public static int numberOnPage(long resultCount, int pageSize, int pageNumber)
      Calculate the number of results on the given page number for the given number of results and page size. This uses one-based page numbering.
      Parameters:
      resultCount - the total number of results to paginate
      pageSize - the size of each page
      pageNumber - the page number
      Returns:
      the number of results on the given page
      Throws:
      IllegalArgumentException - if page number or size is invalid
      See Also:

    • numberOnPage

      public static int numberOnPage(long resultCount, int pageSize, int pageNumber, KiwiSearching.PageNumberingScheme numberingScheme)
      Calculate the number of results on the given page number for the given number of results and page size, and using the given KiwiSearching.PageNumberingScheme.
      Parameters:
      resultCount - the total number of results to paginate
      pageSize - the size of each page
      pageNumber - the page number
      numberingScheme - the page numbering scheme to use
      Returns:
      the number of results on the given page
      Throws:
      IllegalArgumentException - if page number or size is invalid
      See Also: