On Wed, 31 Mar 2021 15:38:22 GMT, Daniel Fuchs <dfu...@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
