Fish 10952 add support for pagination offset mode

[breakponchito]

Adding Implementation for Pagination offset mode

Description

This is a feature to provide the implementation of the Jakarta Data pagination for the offset mode, that is required to pass some of the TCK tests.

To have more details about this pagination model please check the following page: https://jakarta.ee/specifications/data/1.0/jakarta-data-1.0#_offset_based_pagination

for implementation now we can declare abstract methods on our repository interfaces to indicate that the pagination is required

`

to indicate that the pagination is required the return type must be Page. With that the implementation identify pagination and when calling the method the result will be evaluated as an instance of Page. Also it is important the sort criteria and we can add and instance of Order, Sort or array of Sort.

when calling those methods from for example a rest endpoint we need to provide the configuration of the PageRequest and the order, like this:

`
Sort s = null;
if (order.equals("asc")) {
s = Sort.asc(attribute);
} else {
s = Sort.desc(attribute);
}
Page page = personRepository.findPersonWithQueryAndMakePagination(firstName, PageRequest.ofPage(pageNumber).size(size),
Order.by(s));

`

A rule that is important to mention is that we can't combine order criteria from the Query mapped on the annotation and order from a parameter. we just need to declare just one. In case we provide both and exception will be thrown, like the following:

Important Info

Blockers

Testing

New tests

Testing Performed

Manual testing using the following reproducer attached here:
JakartaDataReproducer.zip

To start testing this we need to provide data to the database:

use the following endpoint to provide data: http://localhost:8080/JakartaDataReproducer-1.0-SNAPSHOT/api/personas/insertPersonasStream

this will add 4 rows to the table with the following data:

with this we can call simple pagination to return the first page of size 1 for the attribute firstName with the following endpoint:

http://localhost:8080/JakartaDataReproducer-1.0-SNAPSHOT/api/personas/findPersonsAndMakePaginationWithOderOfName/{page}/{size}/{attribute}/{order}

what I'm indicating with that configuration is the following: please five a page 1 of size 1 ordering the attribute firstName in ascending mode

from the logs we can see the output telling us the structure of the page:

`
[#|2025-06-11T09:32:40.316-0600|INFORMACIËN|Payara 7.2025.1.Alpha3|fish.payara.server.jakartadatareproducer.PersonasResource|_ThreadID=140;_ThreadName=http-thread-pool::http-listener-1(3);_TimeMillis=1749655960316;_LevelValue=800;|
Page:Page:1 From Entity:fish.payara.server.jakartadatareproducer.model.Person page size:1|#]

[#|2025-06-11T09:32:40.317-0600|INFORMACIËN|Payara 7.2025.1.Alpha3|fish.payara.server.jakartadatareproducer.PersonasResource|_ThreadID=140;_ThreadName=http-thread-pool::http-listener-1(3);_TimeMillis=1749655960317;_LevelValue=800;|
Number of Elements:1|#]

[#|2025-06-11T09:32:40.317-0600|INFORMACIËN|Payara 7.2025.1.Alpha3|fish.payara.server.jakartadatareproducer.PersonasResource|_ThreadID=140;_ThreadName=http-thread-pool::http-listener-1(3);_TimeMillis=1749655960317;_LevelValue=800;|
Request Total:true|#]

[#|2025-06-11T09:32:40.317-0600|INFORMACIËN|Payara 7.2025.1.Alpha3|fish.payara.server.jakartadatareproducer.PersonasResource|_ThreadID=140;_ThreadName=http-thread-pool::http-listener-1(3);_TimeMillis=1749655960317;_LevelValue=800;|
Total Elements:4|#]

[#|2025-06-11T09:32:40.317-0600|INFORMACIËN|Payara 7.2025.1.Alpha3|fish.payara.server.jakartadatareproducer.PersonasResource|_ThreadID=140;_ThreadName=http-thread-pool::http-listener-1(3);_TimeMillis=1749655960317;_LevelValue=800;|
Total Pages:4|#]
`

Here I will add other endpoints provided to test the functionality:

http://localhost:8080/JakartaDataReproducer-1.0-SNAPSHOT/api/personas/findPersonsAndMakePaginationWithOderOfName/{page}/{size}/{attribute}/{order}
this use order for sort criteria
http://localhost:8080/JakartaDataReproducer-1.0-SNAPSHOT/api/personas/findPersonsAndMakePaginationWithSortOfName/{page}/{size}/{attribute}/{order}
this use sort type to indicate sort criteria
http://localhost:8080/JakartaDataReproducer-1.0-SNAPSHOT/api/personas/findPersonAndMakePaginationWithArrayOfSortOfFirstNameAndLastName/{page}/{size}/{attribute1}/{order1}/{attribute2}/{order2}
this use two attributes for the ordering
http://localhost:8080/JakartaDataReproducer-1.0-SNAPSHOT/api/personas/findPersonWithQueryAndMakePagination/{firstName}/{page}/{size}/{attribute}/{order}
this is like the first one indicating the name that we need and also how to order the atribute for @query mapping
http://localhost:8080/JakartaDataReproducer-1.0-SNAPSHOT/api/personas/findPersonWithQueryAndMakePaginationWithTwoSorts/{firstName}/{page}/{size}/{attribute}/{order}
same as before
http://localhost:8080/JakartaDataReproducer-1.0-SNAPSHOT/api/personas/findPersonWithQueryAndMakePaginationFromWhere/{firstName}/{page}/{size}/{attribute}
using Where structur from @query mapping
http://localhost:8080/JakartaDataReproducer-1.0-SNAPSHOT/api/personas/findPersonWithQueryAndMakePaginationFromWhereWithMultipleFields/{firstName}/{lastName}/{page}/{size}/{attribute1}/{order1}/{attribute2}/{order2}
this will add two sorts criteria using two attributes
http://localhost:8080/JakartaDataReproducer-1.0-SNAPSHOT/api/personas/findPersonWithQueryAndMakePaginationWithPositionalParam/{firstName}/{page}/{size}
this is to test positional param for the query combined with pagination
http://localhost:8080/JakartaDataReproducer-1.0-SNAPSHOT/api/personas/findPersonWithQueryAndMakePaginationWithMultiplePositionalParam/{firstName}/{lastName}/{page}/{size}
this will test positional param with multiple fields on the query
http://localhost:8080/JakartaDataReproducer-1.0-SNAPSHOT/api/personas/findPersonWithQueryAndMakePaginationFromWithMultipleFields/{firstName}/{lastName}/{page}/{size}
this will test structure of the @query starting from FROM and with pagination
http://localhost:8080/JakartaDataReproducer-1.0-SNAPSHOT/api/personas/findPersonWithQueryAndMakePaginationFromSelectWithMultipleFields/{firstName}/{lastName}/{page}/{size}
this will test structure of the @Quey starting from SELECT and with pagination
http://localhost:8080/JakartaDataReproducer-1.0-SNAPSHOT/api/personas/findPersonWithQueryAndMakePaginationFromSelectWithMultipleFieldsPositionalParam/{firstName}/{lastName}/{page}/{size}
this will test structure of the @Quey starting from SELECT with multiple positional params and with pagination
http://localhost:8080/JakartaDataReproducer-1.0-SNAPSHOT/api/personas/findPersonWithQueryAndMakePaginationUsingGroupAndHaving/{firstName}/{page}/{size}
this will test structure of @query combining with Group By and Having with pagination

Testing Environment

Windows 11, zulu 21 jdk, maven 3.9.5

Documentation

Notes for Reviewers

[luiseufrasio]

LGTM!