jmx-dev RFR: 8264124: Update MXBean specification and implementation to extend mapping of CompositeType to records [v2]

[Daniel Fuchs]

On Sat, 27 Mar 2021 01:49:38 GMT, Mandy Chung <mchung at openjdk.org> wrote:

>> src/java.management/share/classes/javax/management/MXBean.java line 757:
>> 
>>> 755: 
>>> 756:     <p>If the class is a {@link Record}, its getters are the
>>> 757:       accessors for the record components. Otherwise, the
>> 
>> It may be good to add a link like {@linkplain RecordComponent record components}
>
> You add record in "Mappings for other types".  I think it deserves a separate section "Mappings for record classes" (maybe after primitive types).   It's useful to add a row for record in the summary table above "Mappings for primitive types"

Link added. With respect to adding a section for records, it's a bit difficult to separate that from the "Mapping for other types" without a lot of duplication. I can add a row in the summary table, and then add a new section "Mapping for records" just before "Mapping for other types", that just gives a brief overview and refers to the mapping for other types below. 

Something like this - what do you think?

    <h3 id="records">Mappings for Records</h3>

    <p>A {@linkplain Record record} <em>R</em> whose {@linkplain
      Class#getRecordComponents() components} are
      all convertible to open types, is itself convertible to a
      {@link CompositeType} as follows.
      The type name of this {@code CompositeType}
      is determined by the same <a href="#type-names">type name rules</a>
      defined by the <a href="#composite-map">Mapping for other types</a>
      below. Its getters are the accessors for the {@linkplain
      RecordComponent record components}, and the record is reconstructed
      using its canonical constructor, without needing any annotation.</p>

    <p>A record may also expose additional non-canonical constructors, which
      can be used to reconstruct the record if the composite data does
      not exactly contain all the components expected by the
      canonical constructor. However, in order to be taken into account
      by the MXBean framework, such non-canonical constructors
      need to be annotated with either the {@link ConstructorParameters
      @javax.management.ConstructorParameters} or
     {@code @java.beans.ConstructorProperties} annotation.</p>

    <p>The complete rules for the mapping are detailed as part
      of the <a href="#composite-map">Mapping for other types</a>
      below.</p>

    <h3 id="composite-map">Mappings for other types</h3>

    <p>Given a record, or a Java class or interface <em>J</em> that does not match the other
      rules in the table above, the MXBean framework will attempt to map
      it to a {@link CompositeType} as follows.  [....]

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

PR: https://git.openjdk.java.net/jdk/pull/3201