JDK-8339266 : Move rarely used constants out of ClassFile
  • Type: CSR
  • Component: core-libs
  • Sub-Component: java.lang.classfile
  • Priority: P4
  • Status: Proposed
  • Resolution: Unresolved
  • Submitted: 2024-08-29
  • Updated: 2024-09-23
Related Reports
CSR :  
JDK-8339260 - Move rarely used constants out of ClassFile
Relates :  
JDK-8334712 - JEP 484: Class-File API
Description
Summary
-------

Move constants rarely used in a regular user processing routine out of `java.lang.classfile.ClassFile`.

Problem
-------

`ClassFile` is currently the home of all class file constants, no matter where these constants appear. As such, it includes rarely used constants like `AEV` or `CRT` (which is not even in JVMS), or constants already modeled by other constructs, such as opcode or verification types.

These constants overwhelm new users, and hide the actually commonly-used constants (access flags and class file magic and versions). In addition, the name clash between `Opcode` enum constants and `ClassFile` opcode value constants means `Opcode` cannot be static imported if `ClassFile` is; this nuisance often happens in user class writing code.

`ClassFile.DEFAULT_CLASS_FLAGS` is an implementation detail. Its current value might not be suitable after integration of valhalla. We should hide it to avoid accidental impression that this value will stay the same forever.

In addition, some constants are values, and other constants are bit masks that are supposed to be combined with other masks but are not clarified to be so.

The `SimpleVerificationTypeInfo` enum constants with `ITEM_` prefixes are now not as convenient as `VT_` constants after they are moved to `VerificationTypeInfo`; we wish users to use the enum instead of the raw `VT_` constants after the move.

Solution
--------

These constants are moved elsewhere, usually as close as possible to the APIs that return these values. For example, the AEV values are now right by `AnnotationValue.tag()` that returns these values. Rename the constants to their local context after their move; i.e. to replace the generic `AEV` `CRT` prefixes with `TAG` or `FLAG`.

Remove the raw opcode constants. They are still accessible via `Opcode::bytecode`, and we can add back if there's need.

Remove `ClassFile.DEFAULT_CLASS_FLAGS` and keep it internal. Remove the constant pool tag for "unicode".

For bit mask constants (CRT and ACC), clarify they are bit masks.

Remove `ITEM_` prefix for `SimpleVerificationTypeInfo` items. In particular, `ITEM_` prefix was referring to the constant numbers instead of the verification types in https://docs.oracle.com/javase/specs/jvms/se22/html/jvms-4.html#jvms-4.7.4.


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

See attachment.
Comments
Updated to remove `OpcodeValues`; the opcode values are accessible via `Opcode::bytecode`.
23-09-2024
Moving this to proposed for initial review. [~asotona] reviewed, and objected the approach of holding `Opcode` constants in `OpcodeValues`, and recommended to access via `Opcode::code`. My objection is that `Opcode` contains some pseudo-codes from `wide` and thus misses `wide`, and these codes are still useful for the implementation. A potential solution may be to hold these constants in an implementation class (so users can still access via `Opcode::code`, and expose them and `wide` later if deemed necessary.
23-09-2024