Skip to content

allow zero-based indexing (offsets) in PageRequest and Limit #1479

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
gavinking wants to merge 2 commits into
base: main
Choose a base branch
from
Open

allow zero-based indexing (offsets) in PageRequest and Limit #1479

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
b04dea7
allow zero-based indexing (offsets) in PageRequest and Limit
gavinking Jun 2, 2026
ef13cc4
allow zero-based indexing (offsets) in PageRequest and Limit
gavinking Jun 2, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
56 changes: 53 additions & 3 deletions api/src/main/java/jakarta/data/Limit.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -104,15 +104,35 @@ public int maxResults() {
// Override to provide method documentation:

/**
* <p>Offset at which to start when returning query results.
* The first query result is position {@code 1}.</p>
* <p>The position at which to start when returning query results.</p>
* <p>The first query result is at position one. If the start position
* is greater than one, some results at the beginning of the result set
* are skipped.</p>
*
* @return offset of the first result.
* @return position of the first result.
*
* @apiNote Positions are indexed from one;
* {@linkplain #startOffset offsets} are indexed from zero.
*/
public long startAt() {
return startAt;
}

/**
* <p>The offset at which to start when returning query results.</p>
* <p>The first query result is at offset zero. If the start offset
* is strictly positive, some results at the beginning of the result
* set are skipped.</p>
*
* @return offset of the first result.
*
* @apiNote Offsets are indexed from zero;
* {@linkplain #startAt positions} are indexed from one.
*/
public long startOffset() {
return startAt() - 1;
}

/**
* <p>Create a limit that caps the number of results at the
* specified maximum, starting from the first result.</p>
Expand All @@ -126,6 +146,36 @@ public static Limit of(int maxResults) {
return new Limit(maxResults, DEFAULT_START_AT);
}

/**
* <p>Specify the position at which to start returning query results.</p>
* <p>The first query result is at position one. If the start position
* is greater than one, some results at the beginning of the result set
* are skipped.</p>
*
* @param startAt position of the first result.
*
* @apiNote Positions are indexed from one;
* {@linkplain #withStartOffset offsets} are indexed from zero.
*/
public Limit withStartAt(int startAt) {
return new Limit(maxResults, startAt);
}

/**
* <p>Specify the offset at which to start returning query results.</p>
* <p>The first query result is at offset zero. If the start offset
* is strictly positive, some results at the beginning of the result
* set are skipped.</p>
*
* @param startOffset offset of the first result.
*
* @apiNote Offsets are indexed from zero;
* {@linkplain #withStartAt positions} are indexed from one.
*/
public Limit withStartOffset(long startOffset) {
return new Limit(maxResults, startOffset+1);
}

/**
* <p>Create a limit that restricts the results to a range,
* beginning with the {@code startAt} position and ending after the
Expand Down
2 changes: 1 addition & 1 deletion api/src/main/java/jakarta/data/page/CursoredPage.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -93,7 +93,7 @@
* <pre>{@code
* Employee emp = ...
* PageRequest pageRequest =
* PageRequest.ofPage(5)
* PageRequest.ofSize(10).atPageNumber(5)
* .size(50)
* .afterCursor(Cursor.forKey(emp.lastName, emp.firstName, emp.id));
* page = employees.withHoursOver(40, pageRequest);
Expand Down
57 changes: 54 additions & 3 deletions api/src/main/java/jakarta/data/page/PageRequest.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -84,7 +84,10 @@ public interface PageRequest {
* {@code null}.
* @throws IllegalArgumentException when the page number is negative or
* zero.
* @deprecated Use {@link #ofPage(long, int, boolean)}
* or {@link #ofSize} and {@link #atPageNumber}.
*/
@Deprecated(since = "1.1", forRemoval = true)
static PageRequest ofPage(long pageNumber) {
return new Pagination(pageNumber, 10, Mode.OFFSET, null, true);
}
Expand Down Expand Up @@ -223,11 +226,40 @@ static PageRequest beforeCursor(Cursor cursor, long pageNumber, int maxPageSize,
Mode mode();

/**
* Returns the page to be returned.
* Returns the page number of the page to be returned.
*
* @return the page to be returned.
* @since 1.1
*
* @apiNote Page <em>numbers</em> are indexed from one;
* page {@linkplain #pageOffset offsets} are indexed from zero.
*/
long pageNumber();

/**
* Returns the page offset of the page to be returned.
*
* @return the page to be returned.
* @since 1.1
*
* @apiNote Page <em>offsets</em> are indexed from zero;
* page {@linkplain #pageNumber numbers} are indexed from one.
*/
default long pageOffset() {
return pageNumber() - 1;
}

/**
* Returns the page number of the page to be returned.
*
* @return the page to be returned.
*
* @deprecated Use {@link #pageNumber}
*/
long page();
@Deprecated(since = "1.1", forRemoval = true)
default long page() {
return pageNumber();
}

/**
* Returns the requested size of each page
Expand Down Expand Up @@ -266,8 +298,27 @@ static PageRequest beforeCursor(Cursor cursor, long pageNumber, int maxPageSize,
* @return a new instance of {@code PageRequest}. This method never returns
* {@code null}.
* @since 1.1
*
* @apiNote Page <em>numbers</em> are indexed from one;
* page {@linkplain #atPageOffset offsets} are indexed from zero.
*/
PageRequest atPageNumber(long pageNumber);

/**
* <p>Creates a new page request with the same pagination information,
* but with the specified page offset.</p>
*
* @param pageOffset the page offset.
* @return a new instance of {@code PageRequest}. This method never returns
* {@code null}.
* @since 1.1
*
* @apiNote Page <em>offsets</em> are indexed from zero;
* page {@linkplain #atPageNumber numbers} are indexed from one.
*/
PageRequest page(long pageNumber);
default PageRequest atPageOffset(long pageOffset) {
return atPageNumber(pageOffset + 1);
}

/**
* <p>Creates a new page request with the same pagination information,
Expand Down
20 changes: 10 additions & 10 deletions api/src/main/java/jakarta/data/page/Pagination.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,12 +24,12 @@
/**
* Built-in implementation of PageRequest.
*/
record Pagination(long page, int size, Mode mode, Cursor type,
record Pagination(long pageNumber, int size, Mode mode, Cursor type,
boolean requestTotal) implements PageRequest {

Pagination {
if (page < 1) {
throw new IllegalArgumentException("pageNumber: " + page);
if (pageNumber < 1) {
throw new IllegalArgumentException("pageNumber: " + pageNumber);
} else if (size < 1) {
throw new IllegalArgumentException("maxPageSize: " + size);
}
Expand All @@ -42,22 +42,22 @@ record Pagination(long page, int size, Mode mode, Cursor type,

@Override
public PageRequest withoutTotal() {
return new Pagination(page, size, mode, type, false);
return new Pagination(pageNumber, size, mode, type, false);
}

@Override
public PageRequest withTotal() {
return new Pagination(page, size, mode, type, true);
return new Pagination(pageNumber, size, mode, type, true);
}

@Override
public PageRequest afterCursor(Cursor cursor) {
return new Pagination(page, size, Mode.CURSOR_NEXT, cursor, requestTotal);
return new Pagination(pageNumber, size, Mode.CURSOR_NEXT, cursor, requestTotal);
}

@Override
public PageRequest beforeCursor(Cursor cursor) {
return new Pagination(page, size, Mode.CURSOR_PREVIOUS, cursor, requestTotal);
return new Pagination(pageNumber, size, Mode.CURSOR_PREVIOUS, cursor, requestTotal);
}

@Override
Expand All @@ -68,7 +68,7 @@ public Optional<Cursor> cursor() {
@Override
public String toString() {
StringBuilder s = new StringBuilder(mode == Mode.OFFSET ? 100 : 150)
.append("PageRequest{page=").append(page)
.append("PageRequest{pageNumber=").append(pageNumber)
.append(", size=").append(size)
.append(", mode=").append(mode);
if (type != null) {
Expand All @@ -79,11 +79,11 @@ public String toString() {

@Override
public PageRequest size(int maxPageSize) {
return new Pagination(page, maxPageSize, mode, type, requestTotal);
return new Pagination(pageNumber, maxPageSize, mode, type, requestTotal);
}

@Override
public PageRequest page(long pageNumber) {
public PageRequest atPageNumber(long pageNumber) {
return new Pagination(pageNumber, size, mode, type, requestTotal);
}

Expand Down
4 changes: 2 additions & 2 deletions api/src/main/java/jakarta/data/page/impl/CursoredPageRecord.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -82,12 +82,12 @@ public CursoredPageRecord(List<T> content,
this(content, cursors, totalElements, pageRequest,
lastPage ? null : PageRequest.afterCursor(
cursors.get(cursors.size() - 1),
pageRequest.page() + 1,
pageRequest.pageNumber() + 1,
pageRequest.size(),
pageRequest.requestTotal()),
firstPage ? null : PageRequest.beforeCursor(
cursors.get(0),
pageRequest.page() == 1 ? 1 : pageRequest.page() - 1,
pageRequest.pageNumber() == 1 ? 1 : pageRequest.pageNumber() - 1,
pageRequest.size(),
pageRequest.requestTotal()));
}
Expand Down
10 changes: 5 additions & 5 deletions api/src/main/java/jakarta/data/page/impl/PageRecord.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -59,7 +59,7 @@ public PageRecord(PageRequest pageRequest,
* as {@code true} if the page {@code content} is a full page of results and
* the {@code totalElements} is either unavailable (indicated by a negative
* value) or it exceeds the current
* {@linkplain PageRequest#page() page number} multiplied by the
* {@linkplain PageRequest#pageNumber() page number} multiplied by the
* {@link PageRequest#size() size} of a full page.
*
* @param pageRequest The {@link PageRequest page request} for which this
Expand All @@ -74,7 +74,7 @@ public PageRecord(PageRequest pageRequest, List<T> content, long totalElements)
this(pageRequest, content, totalElements,
content.size() == pageRequest.size()
&& (totalElements < 0
|| totalElements > pageRequest.size() * pageRequest.page()));
|| totalElements > pageRequest.size() * pageRequest.pageNumber()));
}

@Override
Expand All @@ -98,14 +98,14 @@ public PageRequest nextPageRequest() {
throw new NoSuchElementException();
}

return PageRequest.ofPage(pageRequest.page() + 1,
return PageRequest.ofPage(pageRequest.pageNumber() + 1,
pageRequest.size(),
pageRequest.requestTotal());
}

@Override
public boolean hasPrevious() {
return pageRequest.page() > 1;
return pageRequest.pageNumber() > 1;
}

@Override
Expand All @@ -114,7 +114,7 @@ public PageRequest previousPageRequest() {
throw new NoSuchElementException();
}

return PageRequest.ofPage(pageRequest.page() - 1,
return PageRequest.ofPage(pageRequest.pageNumber() - 1,
pageRequest.size(),
pageRequest.requestTotal());
}
Expand Down
22 changes: 11 additions & 11 deletions api/src/test/java/jakarta/data/page/PageRequestCursorTest.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,7 @@ void shouldCreatePageRequestAfterKeys() {

assertSoftly(softly -> {
softly.assertThat(pageRequest.size()).isEqualTo(20);
softly.assertThat(pageRequest.page()).isEqualTo(1L);
softly.assertThat(pageRequest.pageNumber()).isEqualTo(1L);
softly.assertThat(pageRequest.requestTotal()).isEqualTo(false);
softly.assertThat(pageRequest.mode()).isEqualTo(PageRequest.Mode.CURSOR_NEXT);
softly.assertThat(pageRequest.cursor()).get().extracting(PageRequest.Cursor::size).isEqualTo(3);
Expand All @@ -54,7 +54,7 @@ void shouldCreatePageRequestAfterCursor() {

assertSoftly(softly -> {
softly.assertThat(pageRequest.size()).isEqualTo(35);
softly.assertThat(pageRequest.page()).isEqualTo(1L);
softly.assertThat(pageRequest.pageNumber()).isEqualTo(1L);
softly.assertThat(pageRequest.mode()).isEqualTo(PageRequest.Mode.CURSOR_NEXT);
softly.assertThat(pageRequest.cursor()).get().extracting(PageRequest.Cursor::size).isEqualTo(2);
softly.assertThat(pageRequest.cursor()).get().extracting(c -> c.get(0)).isEqualTo("me");
Expand All @@ -70,7 +70,7 @@ void shouldCreatePageRequestBeforeKey() {

assertSoftly(softly -> {
softly.assertThat(pageRequest.size()).isEqualTo(30);
softly.assertThat(pageRequest.page()).isEqualTo(10L);
softly.assertThat(pageRequest.pageNumber()).isEqualTo(10L);
softly.assertThat(pageRequest.requestTotal()).isEqualTo(false);
softly.assertThat(pageRequest.mode()).isEqualTo(PageRequest.Mode.CURSOR_PREVIOUS);
softly.assertThat(pageRequest.cursor()).get().extracting(PageRequest.Cursor::size).isEqualTo(2);
Expand All @@ -83,11 +83,11 @@ void shouldCreatePageRequestBeforeKey() {
@DisplayName("Should include key values in previous PageRequest from Cursor")
void shouldCreatePageRequestBeforeKeysetCursor() {
PageRequest.Cursor cursor = new PageRequestCursor(900L, 300, "testing", 120, 'T');
PageRequest pageRequest = PageRequest.ofPage(8).beforeCursor(cursor);
PageRequest pageRequest = PageRequest.ofSize(10).atPageNumber(8).beforeCursor(cursor);

assertSoftly(softly -> {
softly.assertThat(pageRequest.size()).isEqualTo(10);
softly.assertThat(pageRequest.page()).isEqualTo(8L);
softly.assertThat(pageRequest.pageNumber()).isEqualTo(8L);
softly.assertThat(pageRequest.mode()).isEqualTo(PageRequest.Mode.CURSOR_PREVIOUS);
softly.assertThat(pageRequest.cursor()).get().extracting(PageRequest.Cursor::size).isEqualTo(5);
softly.assertThat(pageRequest.cursor()).get().extracting(c -> c.get(0)).isEqualTo(900L);
Expand Down Expand Up @@ -130,10 +130,10 @@ void shouldPageRequestDisplayAsString() {
assertSoftly(softly -> {

softly.assertThat(afterKeySet.toString())
.isEqualTo("PageRequest{page=1, size=200, mode=CURSOR_NEXT, cursor size=2}");
.isEqualTo("PageRequest{pageNumber=1, size=200, mode=CURSOR_NEXT, cursor size=2}");

softly.assertThat(beforeKeySet.toString())
.isEqualTo("PageRequest{page=1, size=100, mode=CURSOR_PREVIOUS, cursor size=2}");
.isEqualTo("PageRequest{pageNumber=1, size=100, mode=CURSOR_PREVIOUS, cursor size=2}");

});
}
Expand All @@ -144,7 +144,7 @@ void shouldBeEqualWithSameKeyValues() {
PageRequest pageRequest25P1S0A1 = PageRequest.ofSize(25).afterCursor(PageRequest.Cursor.forKey("keyval1", '2', 3));
PageRequest pageRequest25P1S0B1 = PageRequest.ofSize(25).beforeCursor(PageRequest.Cursor.forKey("keyval1", '2', 3));
PageRequest pageRequest25P1S0A1Match = PageRequest.ofSize(25).afterCursor(new PageRequestCursor("keyval1", '2', 3));
PageRequest pageRequest25P2S0A1 = PageRequest.ofPage(2).size(25).afterCursor(new PageRequestCursor("keyval1", '2', 3));
PageRequest pageRequest25P2S0A1 = PageRequest.ofSize(10).atPageNumber(2).size(25).afterCursor(new PageRequestCursor("keyval1", '2', 3));
PageRequest pageRequest25P1S0A2 = PageRequest.ofSize(25).afterCursor(PageRequest.Cursor.forKey("keyval2", '2', 3));

PageRequest.Cursor cursor1 = new PageRequestCursor("keyval1", '2', 3);
Expand Down Expand Up @@ -201,7 +201,7 @@ void shouldRaiseErrorForMissingKeysetValues() {
@Test
@DisplayName("Cursor should be replaced on new instance of PageRequest")
void shouldReplaceCursor() {
PageRequest p1 = PageRequest.ofPage(12).size(30).afterCursor(PageRequest.Cursor.forKey("last1", "fname1", 100));
PageRequest p1 = PageRequest.ofSize(10).atPageNumber(12).size(30).afterCursor(PageRequest.Cursor.forKey("last1", "fname1", 100));
PageRequest p2 = p1.beforeCursor(PageRequest.Cursor.forKey("lname2", "fname2", 200));

assertSoftly(softly -> {
Expand All @@ -215,8 +215,8 @@ void shouldReplaceCursor() {
softly.assertThat(p2.cursor()).get().extracting(c -> c.get(1)).isEqualTo("fname2");
softly.assertThat(p2.cursor()).get().extracting(c -> c.get(2)).isEqualTo(200);

softly.assertThat(p1.page()).isEqualTo(12L);
softly.assertThat(p2.page()).isEqualTo(12L);
softly.assertThat(p1.pageNumber()).isEqualTo(12L);
softly.assertThat(p2.pageNumber()).isEqualTo(12L);
softly.assertThat(p1.size()).isEqualTo(30);
softly.assertThat(p2.size()).isEqualTo(30);
});
Expand Down
Loading