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

[Mandy Chung]

On Wed, 31 Mar 2021 15:38:22 GMT, Daniel Fuchs <dfuchs at openjdk.org> wrote:

>> 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.  [....]
>
> Hi Mandy, I have updated the PR with a revised version of the text above. Is that more in line what you had in mind?
> 
> best regards,
> -- daniel

This looks better.  I like a separate mapping section for records since the mapping rules are straight-forward.   The complexity comes if we want to support a record to implement `CompositeDataView` that allows a type to support more flexible conversion to `CompositeData` which is why you add records in the "Mappings for other types".   I am wondering if we really want to support records to implement `CompositeDataView` but we may want to avoid such a special case.

I suggest add subsections in "Mappings for other types":   There are two mapping rules: (1) _opentype(J)_ maps `J` to `CompositeType` (2) _opendata(J)_ maps `J` to `CompositeData`.   _opentype(J)_ for record class does not need to refer to other types.   The common cases for _opendata(J)_ for record class is using the canonical constructors.   The other less common cases like using non-canonical constructors and `CompositeDataView` can state that it follows the same rules as specified for other types.   "Mappings for other types" does not need any change for records.   

"Reconstructing an instance of Java type J from a CompositeData" section should be renamed to "Reconstructing an instance of Java type or record class J from a CompositeData"

Here is a minor tweaking on "Mappings for Records"

A record is convertible to a CompositeType if and only if all its components are 
convertible to open types. Otherwise, it is not convertible.

A record class is converted to a CompositeType with one item for every record component as follows.
- The type name of this CompositeType is determined by the type name rules detailed below. 
- Each record component of type T, the item in the CompositeType has the same name 
  as the record component and of type opentype(T).

The mapping from an instance of a record class to a CompositeData corresponding to 
the CompositeType is the same as specified as for other types (add a link).

A record is reconstructed from a CompositeData using its canonical constructor. 
The canonical constructor doesn't require the presence of @javax.management.ConstructorParameters 
or @java.beans.ConstructorProperties annotations. If these annotations are present on
the canonical constructor, they will be ignored.

If the CompositeData from which the record is reconstructed doesn't contain all the record components, 
the MXBean framework will attempt to reconstruct the record in the same way as specified for 
other types (add a link).

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

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