RFR: 8308753: Class-File API transition to Preview [v3]

[Maurizio Cimadamore]

On Mon, 2 Oct 2023 08:34:19 GMT, Adam Sotona <asotona at openjdk.org> wrote:

>> 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](https://bugs.openjdk.org/browse/JDK-8308754): Class-File API (Preview) (CSR)
>> and [JDK-8280389](https://bugs.openjdk.org/browse/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
>
> Adam Sotona has updated the pull request incrementally with one additional commit since the last revision:
> 
>   fixed javadoc typo

src/java.base/share/classes/java/lang/classfile/package-info.java line 389:

> 387:  * To achieve stability of transformations in future JDK releases it is desired
> 388:  * to set appropriate response to potential new classfile elements appearing.
> 389:  * Transformation designed to handle all situation should be implemented strict way,

"handle all situations" - I couldn't make much sense of it. I only got it when reading the text that follows, which says "transformation selectively interested in ...". This para should be rephrased for better clarity. E.g.
"Classfile transforms that are interested in consuming _all_ classfile elements should be implemented in a strict fashion, so that new exceptions will be issued, should a new and unknown classfile element appear ... Conversely, classfile transforms that are only interested in consuming a portion of classfile elements do not need to concern with new and unknown classfile elements ... because ... "

-------------

PR Review Comment: https://git.openjdk.org/jdk/pull/15706#discussion_r1342737274