From 8985b64b0db0e2ff0d8376ebc1d24826541f6825 Mon Sep 17 00:00:00 2001 From: Nathan Rauh Date: Wed, 3 Jun 2026 14:46:47 -0500 Subject: [PATCH 1/4] Start with changes copied from Gavin's #1479 --- api/src/main/java/jakarta/data/Limit.java | 13 ++++--- .../java/jakarta/data/page/PageRequest.java | 35 ++++++++++++++++++- 2 files changed, 43 insertions(+), 5 deletions(-) diff --git a/api/src/main/java/jakarta/data/Limit.java b/api/src/main/java/jakarta/data/Limit.java index 39e9fafbf..f8470eed4 100644 --- a/api/src/main/java/jakarta/data/Limit.java +++ b/api/src/main/java/jakarta/data/Limit.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2022,2024 Contributors to the Eclipse Foundation + * Copyright (c) 2022,2026 Contributors to the Eclipse Foundation * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -104,10 +104,15 @@ public int maxResults() { // Override to provide method documentation: /** - *

Offset at which to start when returning query results. - * The first query result is position {@code 1}.

+ *

The position at which to start when returning query results.

+ *

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.

* - * @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; diff --git a/api/src/main/java/jakarta/data/page/PageRequest.java b/api/src/main/java/jakarta/data/page/PageRequest.java index 10fe0313a..085781419 100644 --- a/api/src/main/java/jakarta/data/page/PageRequest.java +++ b/api/src/main/java/jakarta/data/page/PageRequest.java @@ -223,12 +223,27 @@ 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. + * @apiNote Page numbers are indexed from one; + * page {@linkplain #pageOffset offsets} are indexed from zero. */ long page(); + /** + * Returns the page offset of the page to be returned. + * + * @return the page to be returned. + * @since 1.1 + * + * @apiNote Page offsets are indexed from zero; + * page {@linkplain #pageNumber numbers} are indexed from one. + */ + default long pageOffset() { + return pageNumber() - 1; + } + /** * Returns the requested size of each page * @@ -266,9 +281,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 numbers are indexed from one; + * page {@linkplain #atPageOffset offsets} are indexed from zero. */ PageRequest page(long pageNumber); + /** + *

Creates a new page request with the same pagination information, + * but with the specified page offset.

+ * + * @param pageOffset the page offset. + * @return a new instance of {@code PageRequest}. This method never returns + * {@code null}. + * @since 1.1 + * + * @apiNote Page offsets are indexed from zero; + * page {@linkplain #atPageNumber numbers} are indexed from one. + */ + default PageRequest atPageOffset(long pageOffset) { + return atPageNumber(pageOffset + 1); + } + /** *

Creates a new page request with the same pagination information, * but with the specified maximum page size. When a page is retrieved from From 749b0f271572312ebaafc3498b99d29a081d046e Mon Sep 17 00:00:00 2001 From: Nathan Rauh Date: Wed, 3 Jun 2026 14:53:21 -0500 Subject: [PATCH 2/4] 0-based offsets relative to first page (PageRequest) and first result (Limit) --- api/src/main/java/jakarta/data/Limit.java | 49 +++++++++++++-- .../java/jakarta/data/page/PageRequest.java | 61 +++++++++++-------- .../data/messages/DataMessages.properties | 5 +- 3 files changed, 83 insertions(+), 32 deletions(-) diff --git a/api/src/main/java/jakarta/data/Limit.java b/api/src/main/java/jakarta/data/Limit.java index f8470eed4..b08e1bb6d 100644 --- a/api/src/main/java/jakarta/data/Limit.java +++ b/api/src/main/java/jakarta/data/Limit.java @@ -17,14 +17,22 @@ */ package jakarta.data; +import jakarta.data.messages.Messages; import jakarta.data.page.PageRequest; +import jakarta.data.repository.Find; +import jakarta.data.repository.Query; /** *

Specifies a limit on the number of results retrieved by a repository * method. The results of a single invocation of a repository method may be - * limited to a given {@linkplain #of(int) maximum number of results} or to a - * given {@linkplain #range(long, long) positioned range} defined in terms of an - * offset and maximum number of results.

+ * limited to + *

* *

A query method of a repository may have a parameter of type * {@code Limit} if its return type indicates that it may return multiple @@ -105,14 +113,14 @@ public int maxResults() { /** *

The position at which to start when returning query results.

- *

The first query result is at position one. If the start position + *

The first query result is at position {@code 1}. If the start position * is greater than one, some results at the beginning of the result set * are skipped.

* * @return position of the first result. * * @apiNote Positions are indexed from one; - * {@linkplain #startOffset offsets} are indexed from zero. + * offsets are indexed from zero. */ public long startAt() { return startAt; @@ -131,6 +139,37 @@ public static Limit of(int maxResults) { return new Limit(maxResults, DEFAULT_START_AT); } + /** + * Create a limit that caps the number of results at the given maximum, + * starting at the given {@code offset} from the first result. + *

+ * An {@code offset} of zero includes the first result. A positive + * {@code offset} skips the respective number of results. + * + * @param maxResults maximum number of results + * @param offset offset at which to start + * @return limit that can be supplied to a {@link Find} method or + * {@link Query} method that performs a find operation; + * will never be {@code null} + * @throws IllegalArgumentException if {@code maxResults} or + * {@code offset} is negative or the {@code offset} is + * {@link Long#MAX_VALUE} + * @since 1.1 + */ + public static Limit of(int maxResults, long offset) { + if (offset < 0) { + throw new IllegalArgumentException( + Messages.get("004.arg.negative", "offset")); + } + + if (offset == Long.MAX_VALUE) { + throw new IllegalArgumentException( + Messages.get("013.arg.invalid", "offset", offset)); + } + + return new Limit(maxResults, offset + 1); + } + /** *

Create a limit that restricts the results to a range, * beginning with the {@code startAt} position and ending after the diff --git a/api/src/main/java/jakarta/data/page/PageRequest.java b/api/src/main/java/jakarta/data/page/PageRequest.java index 085781419..054f0ce41 100644 --- a/api/src/main/java/jakarta/data/page/PageRequest.java +++ b/api/src/main/java/jakarta/data/page/PageRequest.java @@ -20,6 +20,7 @@ import jakarta.data.Limit; import jakarta.data.Order; import jakarta.data.Sort; +import jakarta.data.messages.Messages; import jakarta.data.repository.First; import jakarta.data.repository.OrderBy; @@ -223,27 +224,14 @@ static PageRequest beforeCursor(Cursor cursor, long pageNumber, int maxPageSize, Mode mode(); /** - * Returns the page number of the page to be returned. + * Returns the requested page number. Page numbers begin with {@code 1}. * - * @return the page to be returned. + * @return the requested page number * @apiNote Page numbers are indexed from one; * page {@linkplain #pageOffset offsets} are indexed from zero. */ long page(); - /** - * Returns the page offset of the page to be returned. - * - * @return the page to be returned. - * @since 1.1 - * - * @apiNote Page offsets are indexed from zero; - * page {@linkplain #pageNumber numbers} are indexed from one. - */ - default long pageOffset() { - return pageNumber() - 1; - } - /** * Returns the requested size of each page * @@ -274,32 +262,53 @@ default long pageOffset() { boolean requestTotal(); /** - *

Creates a new page request with the same pagination information, - * but with the specified page number.

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

Creates a new page request with the same pagination information, - * but with the specified page offset.

+ * Creates a new page request with the same pagination information, + * but with the given {@code offset}. + *

+ * The offset is relative to the first page. An offset of {@code 0} + * requests the first page, and an offset of {@code 1} requests the + * second page. * - * @param pageOffset the page offset. - * @return a new instance of {@code PageRequest}. This method never returns - * {@code null}. + * @return the offset of the requested page + * @throws IllegalStateException if the {@link #mode()} is not + * {@link Mode#OFFSET} + * @throws IllegalArgumentException if the {@code offset} is negative + * or {@link Long#MAX_VALUE} * @since 1.1 * * @apiNote Page offsets are indexed from zero; - * page {@linkplain #atPageNumber numbers} are indexed from one. + * page {@linkplain #page numbers} are indexed from one. */ - default PageRequest atPageOffset(long pageOffset) { - return atPageNumber(pageOffset + 1); + default PageRequest pageOffset(long offset) { + if (mode() != Mode.OFFSET) { + throw new IllegalStateException( + Messages.get("014.mode.disallows.offset", mode())); + } + + if (offset < 0) { + throw new IllegalArgumentException( + Messages.get("004.arg.negative", "offset")); + } + + if (offset == Long.MAX_VALUE) { + throw new IllegalArgumentException( + Messages.get("013.arg.invalid", "offset", offset)); + } + + return page(offset + 1); } /** diff --git a/api/src/main/resources/jakarta/data/messages/DataMessages.properties b/api/src/main/resources/jakarta/data/messages/DataMessages.properties index bc276eb83..b7a2157e9 100644 --- a/api/src/main/resources/jakarta/data/messages/DataMessages.properties +++ b/api/src/main/resources/jakarta/data/messages/DataMessages.properties @@ -1,5 +1,5 @@ # -# Copyright (c) 2025 Contributors to the Eclipse Foundation +# Copyright (c) 2025,2026 Contributors to the Eclipse Foundation # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. @@ -35,3 +35,6 @@ identify the entity class that declares the attribute. For static metamodel \ classes, use an .of method that is defined on an Attribute subtype to supply \ the entity class and entity attribute type. +013.arg.invalid=The {0} argument cannot be {1} +014.mode.disallows.offset=A page cannot be requested to have an offset \ + and a mode of {0} From ff6b9194136a11bcbe00921d1bf4514d9c891e19 Mon Sep 17 00:00:00 2001 From: Nathan Rauh Date: Thu, 4 Jun 2026 08:15:39 -0500 Subject: [PATCH 3/4] Code review correction to description of range method MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Good catch - I rearranged some text that was there previously and you spotted an error in it. Co-authored-by: Stéphane Épardaud --- api/src/main/java/jakarta/data/Limit.java | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api/src/main/java/jakarta/data/Limit.java b/api/src/main/java/jakarta/data/Limit.java index b08e1bb6d..bbcc9a948 100644 --- a/api/src/main/java/jakarta/data/Limit.java +++ b/api/src/main/java/jakarta/data/Limit.java @@ -31,7 +31,7 @@ *

  • a {@linkplain #of(int, long) maximum number of results relative to an * offset}, or
    • *
  • a {@linkplain #range(long, long) positioned range} defined in terms of - * a starting position and maximum number of results.
    • + * a starting position and an ending position. *

    * *

    A query method of a repository may have a parameter of type From 8c47327c67aed182cf78ca30a8b3d3d5a0c3fdfa Mon Sep 17 00:00:00 2001 From: Nathan Rauh Date: Wed, 17 Jun 2026 09:49:10 -0500 Subject: [PATCH 4/4] Rename page(n) to pageNumber(n), introduce pageNumber() and deprecate page() --- .../java/jakarta/data/page/CursoredPage.java | 4 +-- .../java/jakarta/data/page/PageRequest.java | 19 +++++++++--- .../java/jakarta/data/page/Pagination.java | 30 ++++++++++++------- .../data/page/impl/CursoredPageRecord.java | 6 ++-- .../jakarta/data/page/impl/PageRecord.java | 10 +++---- .../data/page/PageRequestCursorTest.java | 18 +++++------ .../jakarta/data/page/PageRequestTest.java | 20 ++++++------- .../jakarta/data/page/PaginationTest.java | 9 +++--- .../page/impl/CursoredPageRecordTest.java | 18 +++++------ .../data/page/impl/PageRecordTest.java | 8 ++--- spec/src/main/asciidoc/repository.asciidoc | 16 +++++----- .../data/standalone/entity/EntityTests.java | 16 +++++----- .../standalone/entity/SortNullableTests.java | 2 +- 13 files changed, 98 insertions(+), 78 deletions(-) diff --git a/api/src/main/java/jakarta/data/page/CursoredPage.java b/api/src/main/java/jakarta/data/page/CursoredPage.java index 3004ba63d..026331fcc 100644 --- a/api/src/main/java/jakarta/data/page/CursoredPage.java +++ b/api/src/main/java/jakarta/data/page/CursoredPage.java @@ -93,8 +93,8 @@ * 

    {@code
  * Employee emp = ...
  * PageRequest pageRequest =
- *         PageRequest.ofPage(5)
- *                    .size(50)
+ *         PageRequest.ofSize(50)
+ *                    .pageNumber(5)
  *                    .afterCursor(Cursor.forKey(emp.lastName, emp.firstName, emp.id));
  * page = employees.withHoursOver(40, pageRequest);
  * }
    diff --git a/api/src/main/java/jakarta/data/page/PageRequest.java b/api/src/main/java/jakarta/data/page/PageRequest.java index 054f0ce41..d85d596c0 100644 --- a/api/src/main/java/jakarta/data/page/PageRequest.java +++ b/api/src/main/java/jakarta/data/page/PageRequest.java @@ -223,6 +223,17 @@ static PageRequest beforeCursor(Cursor cursor, long pageNumber, int maxPageSize, */ Mode mode(); + /** + * Returns the requested page number. Page numbers begin with {@code 1}. + * + * @return the requested page number + * @deprecated use {@link #pageNumber()} instead + */ + @Deprecated(since = "1.1", forRemoval = true) + default long page() { + return pageNumber(); + } + /** * Returns the requested page number. Page numbers begin with {@code 1}. * @@ -230,7 +241,7 @@ static PageRequest beforeCursor(Cursor cursor, long pageNumber, int maxPageSize, * @apiNote Page numbers are indexed from one; * page {@linkplain #pageOffset offsets} are indexed from zero. */ - long page(); + long pageNumber(); /** * Returns the requested size of each page @@ -272,7 +283,7 @@ static PageRequest beforeCursor(Cursor cursor, long pageNumber, int maxPageSize, * @apiNote Page numbers are indexed from one; * page {@linkplain #pageOffset offsets} are indexed from zero. */ - PageRequest page(long pageNumber); + PageRequest pageNumber(long pageNumber); /** * Creates a new page request with the same pagination information, @@ -290,7 +301,7 @@ static PageRequest beforeCursor(Cursor cursor, long pageNumber, int maxPageSize, * @since 1.1 * * @apiNote Page offsets are indexed from zero; - * page {@linkplain #page numbers} are indexed from one. + * page {@linkplain #pageNumber numbers} are indexed from one. */ default PageRequest pageOffset(long offset) { if (mode() != Mode.OFFSET) { @@ -308,7 +319,7 @@ default PageRequest pageOffset(long offset) { Messages.get("013.arg.invalid", "offset", offset)); } - return page(offset + 1); + return pageNumber(offset + 1); } /** diff --git a/api/src/main/java/jakarta/data/page/Pagination.java b/api/src/main/java/jakarta/data/page/Pagination.java index 80b953641..627e8bcd6 100644 --- a/api/src/main/java/jakarta/data/page/Pagination.java +++ b/api/src/main/java/jakarta/data/page/Pagination.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2022,2025 Contributors to the Eclipse Foundation + * Copyright (c) 2022,2026 Contributors to the Eclipse Foundation * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -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); } @@ -42,22 +42,30 @@ 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 @@ -68,7 +76,7 @@ public Optional 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) { @@ -79,11 +87,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 pageNumber(long pageNumber) { return new Pagination(pageNumber, size, mode, type, requestTotal); } diff --git a/api/src/main/java/jakarta/data/page/impl/CursoredPageRecord.java b/api/src/main/java/jakarta/data/page/impl/CursoredPageRecord.java index e13ea0420..60acdde58 100644 --- a/api/src/main/java/jakarta/data/page/impl/CursoredPageRecord.java +++ b/api/src/main/java/jakarta/data/page/impl/CursoredPageRecord.java @@ -82,12 +82,14 @@ public CursoredPageRecord(List 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())); } diff --git a/api/src/main/java/jakarta/data/page/impl/PageRecord.java b/api/src/main/java/jakarta/data/page/impl/PageRecord.java index 73e2688f0..ab18de40d 100644 --- a/api/src/main/java/jakarta/data/page/impl/PageRecord.java +++ b/api/src/main/java/jakarta/data/page/impl/PageRecord.java @@ -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 @@ -74,7 +74,7 @@ public PageRecord(PageRequest pageRequest, List content, long totalElements) this(pageRequest, content, totalElements, content.size() == pageRequest.size() && (totalElements < 0 - || totalElements > pageRequest.size() * pageRequest.page())); + || totalElements > pageRequest.size() * pageRequest.pageNumber())); } @Override @@ -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 @@ -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()); } diff --git a/api/src/test/java/jakarta/data/page/PageRequestCursorTest.java b/api/src/test/java/jakarta/data/page/PageRequestCursorTest.java index d39b89b9e..c69938dde 100644 --- a/api/src/test/java/jakarta/data/page/PageRequestCursorTest.java +++ b/api/src/test/java/jakarta/data/page/PageRequestCursorTest.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2022,2024 Contributors to the Eclipse Foundation + * Copyright (c) 2022,2026 Contributors to the Eclipse Foundation * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -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); @@ -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"); @@ -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); @@ -87,7 +87,7 @@ void shouldCreatePageRequestBeforeKeysetCursor() { 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); @@ -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}"); }); } @@ -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); }); diff --git a/api/src/test/java/jakarta/data/page/PageRequestTest.java b/api/src/test/java/jakarta/data/page/PageRequestTest.java index 59c5bcf4c..65e1223a5 100644 --- a/api/src/test/java/jakarta/data/page/PageRequestTest.java +++ b/api/src/test/java/jakarta/data/page/PageRequestTest.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2022,2024 Contributors to the Eclipse Foundation + * Copyright (c) 2022,2026 Contributors to the Eclipse Foundation * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -31,7 +31,7 @@ void shouldCreatePageRequest() { PageRequest pageRequest = PageRequest.ofPage(2).size(6); assertSoftly(softly -> { - softly.assertThat(pageRequest.page()).isEqualTo(2L); + softly.assertThat(pageRequest.pageNumber()).isEqualTo(2L); softly.assertThat(pageRequest.size()).isEqualTo(6); }); } @@ -42,7 +42,7 @@ void shouldCreatePageRequestWithSize() { PageRequest pageRequest = PageRequest.ofSize(50); assertSoftly(softly -> { - softly.assertThat(pageRequest.page()).isEqualTo(1L); + softly.assertThat(pageRequest.pageNumber()).isEqualTo(1L); softly.assertThat(pageRequest.size()).isEqualTo(50); }); } @@ -53,7 +53,7 @@ void shouldCreatePage() { PageRequest pageRequest = PageRequest.ofPage(5); assertSoftly(softly -> { - softly.assertThat(pageRequest.page()).isEqualTo(5L); + softly.assertThat(pageRequest.pageNumber()).isEqualTo(5L); softly.assertThat(pageRequest.size()).isEqualTo(10); }); } @@ -63,10 +63,10 @@ void shouldCreatePage() { void shouldPageRequestDisplayAsString() { assertSoftly(softly -> { softly.assertThat(PageRequest.ofSize(60).toString()) - .isEqualTo("PageRequest{page=1, size=60, mode=OFFSET}"); + .isEqualTo("PageRequest{pageNumber=1, size=60, mode=OFFSET}"); softly.assertThat(PageRequest.ofSize(80).toString()) - .isEqualTo("PageRequest{page=1, size=80, mode=OFFSET}"); + .isEqualTo("PageRequest{pageNumber=1, size=80, mode=OFFSET}"); }); } @@ -76,7 +76,7 @@ void shouldRequestTotalConfigBePreserved() { PageRequest pageRequest1 = PageRequest.ofPage(1).withTotal().size(70); assertSoftly(softly -> { - softly.assertThat(pageRequest1.page()).isEqualTo(1L); + softly.assertThat(pageRequest1.pageNumber()).isEqualTo(1L); softly.assertThat(pageRequest1.size()).isEqualTo(70); softly.assertThat(pageRequest1.requestTotal()).isEqualTo(true); }); @@ -84,7 +84,7 @@ void shouldRequestTotalConfigBePreserved() { PageRequest pageRequest2 = PageRequest.ofPage(2).size(80).withoutTotal(); assertSoftly(softly -> { - softly.assertThat(pageRequest2.page()).isEqualTo(2L); + softly.assertThat(pageRequest2.pageNumber()).isEqualTo(2L); softly.assertThat(pageRequest2.size()).isEqualTo(80); softly.assertThat(pageRequest2.requestTotal()).isEqualTo(false); }); @@ -112,8 +112,8 @@ void shouldReplaceSize() { assertSoftly(softly -> { softly.assertThat(s80.size()).isEqualTo(80); softly.assertThat(s90.size()).isEqualTo(90); - softly.assertThat(s90.page()).isEqualTo(4L); - softly.assertThat(s80.page()).isEqualTo(4L); + softly.assertThat(s90.pageNumber()).isEqualTo(4L); + softly.assertThat(s80.pageNumber()).isEqualTo(4L); }); } diff --git a/api/src/test/java/jakarta/data/page/PaginationTest.java b/api/src/test/java/jakarta/data/page/PaginationTest.java index 1f9495f5b..fe897827d 100644 --- a/api/src/test/java/jakarta/data/page/PaginationTest.java +++ b/api/src/test/java/jakarta/data/page/PaginationTest.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2023,2024 Contributors to the Eclipse Foundation + * Copyright (c) 2023,2026 Contributors to the Eclipse Foundation * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -97,9 +97,10 @@ void shouldUpdatePageSize() { @DisplayName("should override page number") void shouldUpdatePageNumber() { var pagination = new Pagination(1, 10, PageRequest.Mode.OFFSET, null, false); - var updated = pagination.page(5); + var updated = pagination.pageNumber(5); - assertThat(updated).hasFieldOrPropertyWithValue("page", 5L); + assertThat(updated).hasFieldOrPropertyWithValue("page", 5L); // deprecated + assertThat(updated).hasFieldOrPropertyWithValue("pageNumber", 5L); } @Test @@ -109,7 +110,7 @@ void shouldPrintToStringWithCursorInfo() { var pagination = new Pagination(2, 50, PageRequest.Mode.CURSOR_NEXT, cursor, true); assertThat(pagination.toString()) - .contains("page=2", "size=50", "mode=CURSOR_NEXT", "cursor size=2"); + .contains("pageNumber=2", "size=50", "mode=CURSOR_NEXT", "cursor size=2"); } diff --git a/api/src/test/java/jakarta/data/page/impl/CursoredPageRecordTest.java b/api/src/test/java/jakarta/data/page/impl/CursoredPageRecordTest.java index 0ff6247f7..5d07f4166 100644 --- a/api/src/test/java/jakarta/data/page/impl/CursoredPageRecordTest.java +++ b/api/src/test/java/jakarta/data/page/impl/CursoredPageRecordTest.java @@ -83,11 +83,10 @@ void shouldBeImmutable() { page4Request, page2Request); - // Modify the values that were supplied to the CursoredPageRecord - // constructor - page2Request.page(5); - page3Request.page(6); - page4Request.page(7); + // Verify that these methods do not modify the original instances + page2Request.pageNumber(5); + page3Request.pageNumber(6); + page4Request.pageNumber(7); page2Request.size(9); page3Request.size(6); @@ -117,19 +116,18 @@ void shouldBeImmutable() { .containsSequence(originalPage3Content); }); - // Modify (or attempt to modify) values returned by the - // CursoredPageRecord - page3.previousPageRequest().page(1); + // Verify that these methods do not modify the original CursoredPageRecord + page3.previousPageRequest().pageNumber(1); page3.previousPageRequest().size(8); page3.previousPageRequest().withTotal(); page3.previousPageRequest().beforeCursor(Cursor.forKey("50")); - page3.pageRequest().page(4); + page3.pageRequest().pageNumber(4); page3.pageRequest().size(7); page3.pageRequest().withTotal(); page3.pageRequest().afterCursor(Cursor.forKey("101")); - page3.nextPageRequest().page(5); + page3.nextPageRequest().pageNumber(5); page3.nextPageRequest().size(3); page3.nextPageRequest().withTotal(); page3.nextPageRequest().afterCursor(Cursor.forKey("115")); diff --git a/api/src/test/java/jakarta/data/page/impl/PageRecordTest.java b/api/src/test/java/jakarta/data/page/impl/PageRecordTest.java index f25216391..3d3e5d311 100644 --- a/api/src/test/java/jakarta/data/page/impl/PageRecordTest.java +++ b/api/src/test/java/jakarta/data/page/impl/PageRecordTest.java @@ -56,8 +56,8 @@ void shouldBeImmutable() { Page page4 = new PageRecord<>(page4Request, page4Content, 44); - // Modify the values that were supplied to the PageRecord constructor - page4Request.page(5); + // Verify that these methods do not modify the values of the original + page4Request.pageNumber(5); page4Request.size(6); page4Request.withoutTotal(); page4Request.afterCursor(Cursor.forKey("104")); @@ -72,8 +72,8 @@ void shouldBeImmutable() { .containsSequence(originalPage4Content); }); - // Modify values returned by the PageRecord - page4.pageRequest().page(3); + // Verify that these methods do not modify values of the original + page4.pageRequest().pageNumber(3); page4.pageRequest().size(7); page4.pageRequest().withoutTotal(); page4.pageRequest().beforeCursor(Cursor.forKey("100")); diff --git a/spec/src/main/asciidoc/repository.asciidoc b/spec/src/main/asciidoc/repository.asciidoc index 7c24dc2f4..1fae4da6d 100644 --- a/spec/src/main/asciidoc/repository.asciidoc +++ b/spec/src/main/asciidoc/repository.asciidoc @@ -381,7 +381,7 @@ This `PageRequest` specifies a starting page and maximum page size: [source,java] ---- -PageRequest pageRequest = PageRequest.ofPage(1).size(20); +PageRequest pageRequest = PageRequest.ofSize(20).pageNumber(1); List first20 = products.findByName(name, pageRequest, Order.by(_Product.price.desc(), _Product.id.asc())); @@ -581,7 +581,7 @@ Code Execution: People people; Page page = - people.findAll(PageRequest.ofPage(1).size(2), + people.findAll(PageRequest.ofSize(2).pageNumber(1), Order.by(Sort.asc("id"))); ---- @@ -660,8 +660,8 @@ Or you can obtain the next (or previous) page relative to a known entity, [source,java] ---- Customer c = ... -PageRequest p = PageRequest.ofPage(10) - .size(50) +PageRequest p = PageRequest.ofSize(50) + .pageNumber(10) .afterCursor(Cursor.forKey(c.lastName, c.firstName, c.id)); page = customers.findByZipcode(55902, p); ---- @@ -776,8 +776,8 @@ Order order = Order.by(_Product.price.asc(), _Product.id.asc()); PageRequest pageRequest = - PageRequest.ofPage(5) - .size(10) + PageRequest.ofSize(10) + .pageNumber(5) .afterCursor(Cursor.forKey(priceMidpoint, 0L)); CursoredPage moreExpensive = products.findByNameLike(pattern, pageRequest, order); @@ -828,8 +828,8 @@ The query results are ordered first by vehicle condition. All resulting entities [source,java] ---- PageRequest page2Request = PageRequest - .ofPage(2) // cosmetic when using a cursor - .size(25) + .ofSize(25) + .pageNumber(2) // cosmetic when using a cursor .afterCursor(Cursor.forKey(lastCar.vehicleCondition, lastCar.price, lastCar.vin)); diff --git a/tck/src/main/java/ee/jakarta/tck/data/standalone/entity/EntityTests.java b/tck/src/main/java/ee/jakarta/tck/data/standalone/entity/EntityTests.java index 5ce8dc5ca..1889482a2 100644 --- a/tck/src/main/java/ee/jakarta/tck/data/standalone/entity/EntityTests.java +++ b/tck/src/main/java/ee/jakarta/tck/data/standalone/entity/EntityTests.java @@ -696,7 +696,7 @@ public void testFinalPageOfUpTo10() { assertFalse(it.hasNext()); - assertEquals(5, page.pageRequest().page()); + assertEquals(5, page.pageRequest().pageNumber()); assertTrue(page.hasContent()); assertEquals(3, page.numberOfElements()); try { @@ -730,7 +730,7 @@ public void testFinalSliceOfUpTo5() { } } assertTrue(page.hasContent()); - assertEquals(5, page.pageRequest().page()); + assertEquals(5, page.pageRequest().pageNumber()); assertEquals(2, page.numberOfElements()); Iterator it = page.iterator(); @@ -779,7 +779,7 @@ public void testFindAllWithPagination() { } assertEquals(12, page2.numberOfElements()); - assertEquals(2, page2.pageRequest().page()); + assertEquals(2, page2.pageRequest().pageNumber()); assertEquals(List.of(11L, 10L, 9L, // square root rounds down to 3 24L, 23L, 22L, 21L, 20L, 19L, 18L, 17L, 16L), // square root rounds down to 4 @@ -1215,7 +1215,7 @@ public void testFirstPageOf10() { } } - assertEquals(1, page.pageRequest().page()); + assertEquals(1, page.pageRequest().pageNumber()); assertTrue(page.hasContent()); assertEquals(10, page.numberOfElements()); try { @@ -3319,7 +3319,7 @@ public void testThirdAndFourthPagesOf10() { } } - assertEquals(3, page.pageRequest().page()); + assertEquals(3, page.pageRequest().pageNumber()); assertTrue(page.hasContent()); assertEquals(10, page.numberOfElements()); try { @@ -3342,7 +3342,7 @@ public void testThirdAndFourthPagesOf10() { PageRequest fourth10 = page.nextPageRequest(); page = characters.findByNumericValueBetween(48, 90, fourth10, order); // 'N' to 'W' - assertEquals(4, page.pageRequest().page()); + assertEquals(4, page.pageRequest().pageNumber()); assertTrue(page.hasContent()); assertEquals(10, page.numberOfElements()); try { @@ -3382,7 +3382,7 @@ public void testThirdAndFourthSlicesOf5() { } } - assertEquals(3, page.pageRequest().page()); + assertEquals(3, page.pageRequest().pageNumber()); assertEquals(5, page.numberOfElements()); assertEquals(Arrays.toString(new Long[]{37L, 31L, 29L, 23L, 19L}), @@ -3395,7 +3395,7 @@ public void testThirdAndFourthSlicesOf5() { page = numbers.findByNumTypeAndFloorOfSquareRootLessThanEqual(NumberType.PRIME, 8L, fourth5, sort); - assertEquals(4, page.pageRequest().page()); + assertEquals(4, page.pageRequest().pageNumber()); assertEquals(5, page.numberOfElements()); assertEquals(Arrays.toString(new Long[]{17L, 13L, 11L, 7L, 5L}), diff --git a/tck/src/main/java/ee/jakarta/tck/data/standalone/entity/SortNullableTests.java b/tck/src/main/java/ee/jakarta/tck/data/standalone/entity/SortNullableTests.java index 5329e0aea..35ece1bf1 100644 --- a/tck/src/main/java/ee/jakarta/tck/data/standalone/entity/SortNullableTests.java +++ b/tck/src/main/java/ee/jakarta/tck/data/standalone/entity/SortNullableTests.java @@ -625,7 +625,7 @@ public void testMixedOrderByAndSortWithNullOrdering() { "OZ", Order.by(_Country.daylightTimeBegins.desc().nullsFirst(), _Country.code.asc()), - PageRequest.ofSize(25).page(2)); + PageRequest.ofSize(25).pageNumber(2)); } catch (IllegalArgumentException x) { if (type.capableOfSortingNullsFirst()) { throw x;