minimal API changes for 0-based offsets

[njr-11]

This PR starts with some of Gavin's updates from #1479 and pares down to a minimum the amount of API updates needed to accommodate a developer that wants to think about making PageRequests as a 0-based offset from the first page and defining Limits in terms of a 0-based offset from first result.

To achieve this, we really only need 2 methods.

pageOffset(offset) for PageRequest:

page0Request = PageRequest.ofSize(10).pageOffset(0);

limit.of(maxResults, offset) for Limit:

limitToFifthGroupOf10 = Limit.of(10, 40);

[otaviojava]

I am not sure about this one here.

1. the Long.MAX_VALUE still a valid number right?

Why is this not supported?

[njr-11]

1. the Long.MAX_VALUE still a valid number right?

Why is this not supported?

Of course it's a valid number. But an offset of Long.MAX_VALUE from the first result has a page number (Long.MAX_VALUE + 1) that is not representable as a positive long value. If we allowed it, what would you propose to return when a user/Data provider asks the API for the page number?

[gavinking]

10^19 is an implausible number of rows.

[FroMage]

You know, that's precisely how many rows I have. Make it work.

[njr-11]

Includes additional changes that were agreed to on the Jakarta Data meeting:

• .page() is deprecated in favor of a new .pageNumber()
• .page(num) is renamed .pageNumber(num) which is possible because the method is new in 1.1

Usage for page requests is now:

PageRequest.ofSize(10).pageNumber(1);

or

PageRequest.ofSize(10).pageOffset(0);

depending on whether you want 1-based or 0-based.