JDK-8336034 : CompoundElement API cleanup
  • Type: CSR
  • Component: core-libs
  • Sub-Component: java.lang.classfile
  • Priority: P4
  • Status: Closed
  • Resolution: Approved
  • Fix Versions: 24
  • Submitted: 2024-07-09
  • Updated: 2024-07-13
  • Resolved: 2024-07-13
Related Reports
CSR :  
Description
Summary
-------

Remove redundant `elements` and `forEachElement` from `CompoundElement`.

Problem
-------

`CompoundElement` is already `Iterable`, yet it has an `Iterable elements()`. It already has `forEach(Consumer<? super E>)` but it additionally declares a `forEachElement(Consumer<E>)`. According to [~asotona], `CompoundElement` was refitted to `Iterable`, so these vestiges can be removed.

Solution
--------

Remove `CompoundElement::elements` and `CompoundElement::forEachElement`. References in code and specification are accordingly updated.

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

    diff --git a/src/java.base/share/classes/java/lang/classfile/ClassModel.java b/src/java.base/share/classes/java/lang/classfile/ClassModel.java
    index 282392a8c5e..c289f72f560 100644
    --- a/src/java.base/share/classes/java/lang/classfile/ClassModel.java
    +++ b/src/java.base/share/classes/java/lang/classfile/ClassModel.java
    @@ -37,7 +37,7 @@
     
     /**
      * Models a classfile.  The contents of the classfile can be traversed via
    - * a streaming view (e.g., {@link #elements()}), or via random access (e.g.,
    + * a streaming view, or via random access (e.g.,
      * {@link #flags()}), or by freely mixing the two.
      *
      * @since 22
    diff --git a/src/java.base/share/classes/java/lang/classfile/CodeModel.java b/src/java.base/share/classes/java/lang/classfile/CodeModel.java
    index b48802d02ac..45488561c1a 100644
    --- a/src/java.base/share/classes/java/lang/classfile/CodeModel.java
    +++ b/src/java.base/share/classes/java/lang/classfile/CodeModel.java
    @@ -36,8 +36,7 @@
     
     /**
      * Models the body of a method (the {@code Code} attribute).  The instructions
    - * of the method body are accessed via a streaming view (e.g., {@link
    - * #elements()}).
    + * of the method body are accessed via a streaming view.
      *
      * @since 22
      */
    diff --git a/src/java.base/share/classes/java/lang/classfile/CompoundElement.java b/src/java.base/share/classes/java/lang/classfile/CompoundElement.java
    index 42f0fabadc6..12904c9dd59 100644
    --- a/src/java.base/share/classes/java/lang/classfile/CompoundElement.java
    +++ b/src/java.base/share/classes/java/lang/classfile/CompoundElement.java
    @@ -40,7 +40,7 @@
      * class.  When encountering a {@linkplain CompoundElement}, clients have the
      * option to treat the element as a single entity (e.g., an entire method)
      * or to traverse the contents of that element with the methods in this class
    - * (e.g., {@link #elements()}, {@link #forEachElement(Consumer)}, etc.)
    + * (e.g., {@link #forEach(Consumer)}, etc.)
      * @param <E> the element type
      *
      * @sealedGraph
    @@ -55,15 +55,8 @@ public sealed interface CompoundElement<E extends ClassFileElement>
          * compound element
          * @param consumer the handler
          */
    -    void forEachElement(Consumer<E> consumer);
    -
    -    /**
    -     * {@return an {@link Iterable} describing all the elements contained in this
    -     * compound element}
    -     */
    -    default Iterable<E> elements() {
    -        return elementList();
    -    }
    +    @Override
    +    void forEach(Consumer<? super E> consumer);
     
         /**
          * {@return an {@link Iterator} describing all the elements contained in this
    diff --git a/src/java.base/share/classes/java/lang/classfile/FieldModel.java b/src/java.base/share/classes/java/lang/classfile/FieldModel.java
    index cb2e167b9cf..35465dfe97d 100644
    --- a/src/java.base/share/classes/java/lang/classfile/FieldModel.java
    +++ b/src/java.base/share/classes/java/lang/classfile/FieldModel.java
    @@ -35,7 +35,7 @@
     
     /**
      * Models a field.  The contents of the field can be traversed via
    - * a streaming view (e.g., {@link #elements()}), or via random access (e.g.,
    + * a streaming view, or via random access (e.g.,
      * {@link #flags()}), or by freely mixing the two.
      *
      * @since 22
    diff --git a/src/java.base/share/classes/java/lang/classfile/MethodModel.java b/src/java.base/share/classes/java/lang/classfile/MethodModel.java
    index 49cbb6ac7fd..3d91683e218 100644
    --- a/src/java.base/share/classes/java/lang/classfile/MethodModel.java
    +++ b/src/java.base/share/classes/java/lang/classfile/MethodModel.java
    @@ -35,7 +35,7 @@
     
     /**
      * Models a method.  The contents of the method can be traversed via
    - * a streaming view (e.g., {@link #elements()}), or via random access (e.g.,
    + * a streaming view, or via random access (e.g.,
      * {@link #flags()}), or by freely mixing the two.
      *
      * @since 22
    
Comments
Moving to Approved.
13-07-2024

I can't find any reasons to keep these duplicate methods. It is a nice API cleanup.
12-07-2024