[MSHARED-1251] - Deprecate the JAR Index feature (JDK-8302819)

[jorsol]

Following this checklist to help us incorporate your
contribution quickly and easily:

• Make sure there is a JIRA issue filed
  for the change (usually before you start working on it). Trivial changes like typos do not
  require a JIRA issue. Your pull request should address just this issue, without
  pulling in other changes.
• Each commit in the pull request should have a meaningful subject line and body.
• Format the pull request title like [MSHARED-XXX] - Fixes bug in ApproximateQuantiles,
  where you replace MSHARED-XXX with the appropriate JIRA issue. Best practice
  is to use the JIRA issue title in the pull request title and in the first line of the
  commit message.
• Write a pull request description that is detailed enough to understand what the pull request does, how, and why.
• Run mvn clean verify to make sure basic checks pass. A more thorough check will
  be performed on your pull request automatically.
• You have run the integration tests successfully (mvn -Prun-its clean verify).

If your pull request is about ~20 lines of code you don't need to sign an
Individual Contributor License Agreement if you are unsure
please ask on the developers list.

To make clear that you license your contribution under
the Apache License Version 2.0, January 2004
you have to acknowledge this by using the following check-box.

• I hereby declare this contribution to be licenced under the Apache License Version 2.0, January 2004

• In any other case, please file an Apache Individual Contributor License Agreement.

[elharo]

no real need to deprecate a private field

[jorsol]

It's an internal mark that the field should no longer be used, it helps to detect the places where it's used and is a reminder that in the future it could be removed.

[khmarbaise]

The point is that the usage of index.list has been marked deprecated and is not being used starting with JDK18 https://www.oracle.com/java/technologies/javase/18-relnote-issues.html

Furthermore as already referenced in JDK21 it will be completely being removed. Also it's good to have a reminder here...

[elharo]

Deprecating the method is enough. Private fields can be changed freely without worrying about compatibility when they're no longer used. Adding Javadoc to private fields, deprecation warnings included, is painting the lily.

[jorsol]

Well, adding Javadoc to private fields could be helpful in some cases, especially if the comment is succinct.

Yet, even if adding a Javadoc on a private field is just a cosmetic change, it doesn't hurt in any way to have it, more when it signals to future developers that touch the code that the field should no longer be used for anything (or with extra care).

I don't mind removing the Javadoc from the field, but there is no real need to remove it, in the end, is just a matter of code convention, just like adding Javadoc to a private method is valid.

Maven plugins even recommend adding Javadoc on private fields as the documentation of @Parameter is generated from there.