Package org.kiwiproject.search

Class KiwiSearching

java.lang.Object

org.kiwiproject.search.KiwiSearching

public 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

Nested Class Summary

Nested Classes

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

Field Summary

Fields

Modifier and Type	Field	Description
static int	DEFAULT_PAGE_SIZE	A rather opinionated value for the default page size.
static 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 JAX-RS's javax.ws.rs.DefaultValue that require a String.
static String	PAGE_SIZE_ERROR

Constructor Summary

Constructors

Constructor	Description
KiwiSearching()

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.

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_PAGE_SIZE

public static final int DEFAULT_PAGE_SIZE

A rather opinionated value for the default page size.

See Also:

Constant Field Values

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 JAX-RS's javax.ws.rs.DefaultValue that require a String.

See Also:

Constant Field Values

Implementation Note:

This must be a constant not an expression, otherwise trying to use it in an annotation like the JAX-RS 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:

Constant Field Values

Constructor Detail

KiwiSearching

public KiwiSearching()

Method Detail

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(int, PageNumberingScheme), KiwiSearching.PageNumberingScheme.ONE_BASED

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:

KiwiSearching.PageNumberingScheme

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:

KiwiSearching.PageNumberingScheme.ONE_BASED, zeroBasedOffset(int, PageNumberingScheme, int)

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:

KiwiSearching.PageNumberingScheme

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:

KiwiSearching.PageNumberingScheme.ONE_BASED, numberOnPage(long, int, int, PageNumberingScheme)

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:

KiwiSearching.PageNumberingScheme