JDK-8334720 : Implement JEP 484: Class-File API
  • Type: CSR
  • Component: core-libs
  • Sub-Component: java.lang.classfile
  • Priority: P4
  • Status: Closed
  • Resolution: Approved
  • Fix Versions: 24
  • Submitted: 2024-06-21
  • Updated: 2024-11-14
  • Resolved: 2024-11-14
Related Reports
CSR :  
JDK-8334714 - Implement JEP 484: Class-File API
Relates :  
JDK-8334712 - JEP 484: Class-File API
Relates :  
JDK-8342465 - Improve API documentation for java.lang.classfile
Description
Summary
-------

Class-File API is leaving preview.

Problem
-------

- All `@PreviewFeature` annotations must be removed from Class-File API.
- All `@since` tags of Class-File API classes and packages must be updated to the actual version.
- `jdk.internal.javac.PreviewFeature.Feature.CLASSFILE_API` must be removed.

Solution
--------

- Remove all `@PreviewFeature` annotations from Class-File API
- Update all  `@since` tags in Class-File API.
- Remove  `jdk.internal.javac.PreviewFeature.Feature.CLASSFILE_API`.

Specification
-------------

Patch is too big to inline, so attached as `pr19826.patch`.
Comments
Thank you for the review! > Does the design of the API impose additional constraints on JVM evolution for the sort of changes that are anticipated to be made in the future? We evaluated the impact of planned JVM changes and designed the API with best efforts to not impose any restrictions on JVM changes over the horizon. Currently we are not aware of any. All comments on the documentation will be reflected in the upcoming PRs.
14-11-2024
Moving to Approved, with comments. Does the design of the API impose additional constraints on JVM evolution for the sort of changes that are anticipated to be made in the future? For `AnnotationValue`, the `TAG_FOO` constants would be better if the javadoc specification contained an `{@value }` tags with the int formatted to the corresponding character. Similar feedback for types like AnnotationValue.OfAnnotation. IMO, "The tag of this value is 64." would be better as "The tag of this value is `@`." Also for the ClassFile interface the various constants could have hex value displayed for them using a formatting `@value` tag, as done in java.lang.reflect.AccessFlag, e.g. "...with a mask value of <code>{@value "0x%04x" Modifier#PUBLIC}</code>" (Since the interfaces in the API are sealed and not user extensible, generally don't need implSpec tags for the default methods.) At least one of the API elements that refer to the opcode would benefit from having `@jvms` links to the opcode. A formatting nit, in javadoc replacing i'th with <i>i</i><sup>th</sup> renders to a more pleasing result, IMO.
14-11-2024
We believe we have finished our changes. The main changes made besides smaller removals include: - Moving around of constant fields to promote using abstraction instead of raw values - Make Opcode more algebraic - loadConstant for performance and specific computational types on stack - Hide internal writing hooks WritableElement from API - TypeKind facelift (enum naming style, utility methods, subword treatments in docs) - AnnotationConstantValue methods to emphasize representational difference (subwords mainly) - TypeAnnotation remodel - Hide transform implementation hooks - CodeBuilder::if_nonnull and if_null didn't match mnemonic ifnonnull ifnull - ClassFile::transform to transformClass, consistency with builder transformXxx and avoid confusion with builder transform - Remove AccessFlag factories to avoid ambiguous interpretation with valhalla IDENTITY bit in the future Changes we decided against: - Remove AnnotationConstantValueEntry - Enhanced exception type with OOB label offsets or bad CP index getters - Extended encapsulation of ClassReader to prohibit reading out of the range of an attribute, etc. - Proposal to rename StackMapsOption elements (its transformation and direct write behaviors were a bit different) Other future considerations (non-blocking): - Access to Labels in attribute read/write - Explicit Code counters in writing - Instruction.sizeInBytes for unbound switches - Identity of bound instructions loaded from Code attribute (ease for instr-based mappings, such as in Babylon) [~asotona] Do you think we should move this CSR to proposed?
26-09-2024
Moving to Provisional.
03-07-2024
This is a purely procedural CSR for removing the `@PreviewFeature` annotations from the Class-File API and bumping the `@since` tags. It does not contain any other changes to the API nor documentation. Any API or documentation changes will be discussed individually, solved in individual CSRs and linked to the [JEP bug](https://bugs.openjdk.org/browse/JDK-8334712).
21-06-2024