RFR: 8265226: (dc) API note in DatagramChannel.open should link to StandardProtocolFamily.UNIX

[Michael McMahon]

On Thu, 15 Apr 2021 08:22:43 GMT, Alan Bateman <alanb at openjdk.org> wrote:

>> Hi,
>> 
>> Could I get the following change reviewed please (which may need a CSR)?
>> 
>> It should have been considered as part of (8262883) which was integrated earlier today.
>> Any other comments on that change can be considered here too.
>> 
>> This is the change:
>> 
>> 
>> diff a/src/java.base/share/classes/java/nio/channels/DatagramChannel.java b/src/java.base/share/classes/java/nio/channels/DatagramChannel.java
>> --- a/src/java.base/share/classes/java/nio/channels/DatagramChannel.java
>> +++ b/src/java.base/share/classes/java/nio/channels/DatagramChannel.java
>> @@ -170,12 +170,11 @@
>>       * java.nio.channels.spi.SelectorProvider#openDatagramChannel(ProtocolFamily)
>>       * openDatagramChannel} method of the system-wide default {@link
>>       * java.nio.channels.spi.SelectorProvider} object.  The channel will not be
>>       * connected.
>>       *
>> -     * @apiNote {@linkplain java.net.UnixDomainSocketAddress Unix domain} sockets
>> -     * are not supported by DatagramChannel.
>> +     * @apiNote {@link java.net.StandardProtocolFamily#UNIX} is not supported.
>>       *
>>       * @param   family
>>       *          The protocol family
>>       *
>>       * @return  A new datagram channel
>> 
>> 
>> Thanks,
>> 
>> Michael.
>
> src/java.base/share/classes/java/nio/channels/DatagramChannel.java line 175:
> 
>> 173:      * connected.
>> 174:      *
>> 175:      * @apiNote {@link java.net.StandardProtocolFamily#UNIX} is not supported.
> 
> It might be clearer to restore the original text ("Unix domain sockets are not support by DatagramChannel") and add something like "; invoking this method with the UNIX protocol family throws UnsupportedOperationException". 
> 
> (btw: I had changed the description of the JBS issue to reflect what this issue about, hopefully the commit can use the same description).

I've updated the PR to be the same as the bug report. But, is it necessary to mention UOE, given that the @throws already says:

     * @throws  UnsupportedOperationException
     *          If the specified protocol family is not supported. For example,
     *          suppose the parameter is specified as {@link
     *          java.net.StandardProtocolFamily#INET6 StandardProtocolFamily.INET6}
     *          but IPv6 is not enabled on the platform.

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

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