RFR: 8207851: Implement JEP 352

[Alan Bateman]

On 28/05/2019 16:00, Andrew Dinn wrote:
> :
> Yes, I'll raise one ASAP. Could you clarify  what changes I need to
> document in the CSR? Here are my current thoughts:
>
> ManagementFactoryHelper/FileChannelImpl
> I am assuming the change that exposes the new MXBean needs to be
> mentioned somwehere. However, that change doesn't actually affect any
> API. It just means that a new bean with a new name appears in the list
> of memory beans. I don't see anything which documents those bean names.
> Am I missing something? (probably :).
It's not the main event but I think useful to list it in the CSR. You 
are right that the existing "direct" and "mapped" aren't documented 
anywhere but it wouldn't be too surprising to find tools that rely on them.

>
> com/sun/nio/file/ExtendedMapMode (in jdk.unsupported)
>
> I'm assuming the CSR needs to propose javadoc for the 2 exposed MapMode
> values, explaining what these modes are used for and which exceptions
> documented in FileChannel.map get thrown for the cases where their use
> is unsupported by the JVM or the OS, respectively. Is that correct?
Yes, including the javadoc for the class and the two new map modes. The 
javadoc for both modes can reference the UOE thrown by FileChannel.map 
when the mode is not supported.


>
> jdk/internal/misc/ExtendedMapMode (in java.base)
>
> Do I need to provide javadoc for the two new MapMode values and include
> them in the CSR? I was assuming not.
Right, it's JDK internal so no need to list that.

>
> FileChannelImpl method map
> The javadoc in FileChannel lists the new exceptions that might be thrown
> by this implementation but does not mention any specifics to say how
> they might relate to use of the XXX_SYNC MapModes. Do I need to propose
> updates for the FileChannel javadoc in the CSR or am I ok to provide
> that detail in the doc for com/sun/nio/file/ExtendedMapMode?
JDK-8221397 had the "enabling" changes so no changes to FileChannel.map, 
just the reference from ExtendedMapMode.


>
> Unsafe method writebackMemory
> I was assuming Unsafe.writebackMemory is internal to the JDK so does not
> need a mention in the CSR. Is that correct?
That's right.

-Alan