[Use Case]: zero-based indexing

[gavinking]

As a ...

• Application user/user of the configuration itself
• API user (application developer)
• SPI user (container or runtime developer)
• Specification implementer

I need to be able to ...

count from zero if I feel like it.

Which enables me to ...

pretend I'm Donald Knuth.

Additional information

Folks with CS degrees have a weird fetish for counting from 0 instead of from 1 like mathematicians and other normal people. This came up in #941.

Since Jakarta Data is an inclusive specification, we should consider catering to the needs of both nerds and normies. I would do this not by some 🤮global configuration property (as previously proposed), but rather by exposing both "page numbers" and "page indexes" in the PageRequest interface.

This would involve something the following additions:

    default long index() {
        return page() - 1;
    }

    default PageRequest index(long pageIndex) {
        return page(pageIndex + 1);
    }

    static PageRequest atIndex(long index) {
        return ofPage(index + 1);
    }

    static PageRequest atIndex(long index, int maxPageSize, boolean requestTotal) {
        return ofPage(index + 1, maxPageSize, requestTotal);
    }

Perhaps something similar should be done in Limit.

cc @FroMage

[njr-11]

Very amusing writeup!
If we need to add zero-based page indexes for similarity/compatibility with existing, this seems like a good way to achieve it given that it is isolated to the PageRequest instance that the application is using. The alternative of configuration (which isn't even available yet) is worse because it risks being out of sync with application logic.

We could probably get away with adding only the first two default methods and not the two static ones given that the former is enough to let the application both specify a page index on a new PageRequest and retrieve the page index from the PageRequest of a next or previous Page. I think it is more natural to start out with a page size before deciding which page you want, PageRequest.ofSize(20).index(5) vs very unnatural first knowing the page index and then deciding what size the pages are, PageRequest.atIndex(5).ofSize(20). So I would propose to not add the static methods that start out with an index.

I'm also going back and forth on whether we might want to name these methods pageIndex rather than index because then autocomplete would help the developer understand that there are two related options to choose from (page number vs page index) when starting to type PageRequest.ofSize(20).p...

[gavinking]

I think it is more natural to start out with a page size before deciding which page you want

Yes, I 100% agree with this, I don't actually like the ofPage() method at all.

[FroMage]

Folks with CS degrees have a weird fetish for counting from 0 instead of from 1 like mathematicians and other normal people

Oh, if we're going to use snark, then gloves are off, and the use case is actually about sane people that can read a room and recognise that, in the context of a programming language where 99% of the APIs are zero-based, it makes zero sense (or 1, I guess, if you keep up this nonsense) to have part of your API be 1-based, and let users rely on a coin toss as to wether requests are 1-based or not, given that all results are 0-based (arrays, List).

I don't think you can hide behind Math to justify this oversight. Let's just be consistent.

I can get on board with adding index on top of the existing confusing whatever name, if backwards compatibility with the existing overwhelming users of Jakarta Data, but I'd also argue that this is still a very early phase of adoption, and so we could afford to do the right thing and deprecate the 1-based methods, even if we only remove them later, because having two APIs (0-based and 1-based) is going to prove confusing to users in the long term, for the same reasons that having part of your API be 0-based and 1-based as it currently is.

Respectfully 😘

More seriously, though, thanks for considering this :)