8308753: Class-File API transition to Preview

[asotona]

Classfile API is an internal library under package jdk.internal.classfile in JDK 21.
This pull request turns the Classfile API into a preview feature and moves it into java.lang.classfile.
It repackages all uses across JDK and tests and adds lots of missing Javadoc.

This PR goes in sync with JDK-8308754: Class-File API (Preview) (CSR)
and JDK-8280389: Class-File API (Preview) (JEP).

Online javadoc is available at: 
https://cr.openjdk.org/~asotona/JDK-8308753-preview/api/java.base/java/lang/classfile/package-summary.html

In addition to the primary transition to preview, this pull request also includes:

• All Classfile* classes ranamed to ClassFile* (based on JEP discussion).
• A new preview feature, CLASSFILE_API, has been added.
• Buildsystem tool required a little patch to support annotated modules.
• All JDK modules using the Classfile API are newly participating in the preview.
• All tests that use the Classfile API now have preview enabled.
• A few Javac tests not allowing preview have been partially reverted; their conversion can be re-applied when the Classfile API leaves preview mode.

Despite the number of affected files, this pull request is relatively straight-forward. The preview version of the Classfile API is based on the internal version of the library from the JDK master branch, and there are no API features added.

Please review this pull request to help the Classfile API turn into a preview.

Any comments are welcome.

Thanks,
Adam

---

Progress

• Change must not contain extraneous whitespace
• Commit message must refer to an issue
• Change requires CSR request JDK-8308754 to be approved
• Change must be properly reviewed (2 reviews required, with at least 1 Reviewer, 1 Author)

Issues

• JDK-8308753: Class-File API transition to Preview (Sub-task - P4)
• JDK-8308754: Class-File API (Preview) (CSR)

Reviewers

• Magnus Ihse Bursie (@magicus - Reviewer) ⚠️ Review applies to 6594ee74
• Mandy Chung (@mlchung - Reviewer) ⚠️ Review applies to a6a73b37
• Vicente Romero (@vicente-romero-oracle - Reviewer) ⚠️ Review applies to a6a73b37

Reviewing

Using git

Checkout this PR locally:
$ git fetch https://git.openjdk.org/jdk.git pull/15706/head:pull/15706
$ git checkout pull/15706

Update a local copy of the PR:
$ git checkout pull/15706
$ git pull https://git.openjdk.org/jdk.git pull/15706/head

Using Skara CLI tools

Checkout this PR locally:
$ git pr checkout 15706

View PR using the GUI difftool:
$ git pr show -t 15706

Using diff file

Download this PR as a diff file:
https://git.openjdk.org/jdk/pull/15706.diff

Webrev

Link to Webrev Comment

[kwin]

You can simply call ClassFile.of().parse(inputStream.readAllBytes()) instead.

I know, but for memory consumption reasons everyone should prefer just passing an InputStream. Is the memory consumption with ClassFile.of().parse(Path) any better (i.e. are you using a java.io.RandomAccessFile or java.nio.channels.SeekableByteChannel under the hood)? I think that deserves a sentence in the javadoc.

[liach]

I know, but for memory consumption reasons everyone should prefer just passing an InputStream. Is the memory consumption with ClassFile.of().parse(Path) any better (i.e. are you using a java.io.RandomAccessFile or java.nio.channels.SeekableByteChannel under the hood)? I think that deserves a sentence in the javadoc.

FYI parse(Path) is just a shortcut to read all bytes from a file, like parse(Files.readAllBytes(path)). Classfile implementation fetches the byte array very often (constant pool reading, lazy expansion) so keeping the bytes in a in-memory array is better.

[minborg]

Is there a more scalable way to express the major class version? The current approach means we have to add two fields per year. Maybe a lookup function would be better?

[asotona]

This is explicit list of supported class file versions, so I don't see any other way.

[minborg]

Would it not be possible to expose an immutable Map<Integer, Integer> that maps from Java version to major class version?

[asotona]

This is actually out of scope of this PR. Feel free to request a new ClassFile API feature.

[openjdk]

@asotona This change now passes all automated pre-integration checks.

ℹ️ This project also has non-automated pre-integration requirements. Please see the file CONTRIBUTING.md for details.

After integration, the commit message for the final commit will be:

8308753: Class-File API transition to Preview

Reviewed-by: ihse, mchung, vromero

You can use pull request commands such as /summary, /contributor and /issue to adjust it as needed.

At the time when this comment was updated there had been no new commits pushed to the master branch. If another commit should be pushed before you perform the /integrate command, your PR will be automatically rebased. If you prefer to avoid any potential automatic rebasing, please check the documentation for the /integrate command for further details.

➡️ To integrate this PR with the above commit message to the master branch, type /integrate in a new comment.

[asotona]

/integrate

[openjdk]

Going to push as commit 2b00ac0.

[openjdk]

@asotona Pushed as commit 2b00ac0.

💡 You may see a message that your pull request was closed with unmerged commits. This can be safely ignored.