adding rsockets support into JDK

[Daniel Fuchs]

Hi Lucy,

I'm assuming that the classes in questions should
eventually have javadoc generated for them in the
as a JDK implementation-specific supported API, yes?

If so you might want to try and figure out how the javadoc
generation of the jdk.httpserver modules is hooked up in the
build system - possibly using find/grep to see where
jdk.httpserver appears in the makefile - as this is an
example of such API for which javadoc is produced.

Then you could can call `make docs` to generate the javadoc
of the whole jdk, including that of your module.

The api doc will be put under build/<platform>/images/docs/api

Then you can copy over those HTML files you want to share to your
account on cr.openjdk.java.net.

The trick is to preserve the directory structure of the api doc,
and to copy the stylesheet.css which is at the root of the hierarchy
as well, for instance if you wanted to copy the javadoc of
`some.module/some.package.MyClass`  to a directory `xxx`:

xxx/stylesheet.css
xxx/some.module/some/package/MyClass.html


hope this helps,

-- daniel

On 16/11/2018 14:29, Lu, Yingqi wrote:
> Hi Chris,
> 
> I gave a try on generating Javadoc...
> 
> The command I did was:
> javadoc -d /home/RDMA/jdk12-8195160-version17/html  -sourcepath /home/RDMA/jdk12-8195160-version17/src/jdk.net/share/classes/  jdk.net
> 
> Then, I got following errors. I tried using --add-module and -classpath flags, but either helped me. Would you please help point out what I missed here?
> 
> /home/RDMA/jdk12-8195160-version17/src/jdk.net/share/classes/jdk/net/ExtendedSocketOptions.java:36: error: package jdk.internal.access does not exist
> import jdk.internal.access.JavaIOFileDescriptorAccess;
>                            ^
> /home/RDMA/jdk12-8195160-version17/src/jdk.net/share/classes/jdk/net/ExtendedSocketOptions.java:37: error: package jdk.internal.access does not exist
> import jdk.internal.access.SharedSecrets;
>                            ^
> /home/RDMA/jdk12-8195160-version17/src/jdk.net/share/classes/jdk/net/ExtendedSocketOptions.java:265: error: cannot find symbol
>      private static final JavaIOFileDescriptorAccess fdAccess =
>                           ^
>    symbol:   class JavaIOFileDescriptorAccess
>    location: class ExtendedSocketOptions
> /home/RDMA/jdk12-8195160-version17/src/jdk.net/share/classes/jdk/net/RdmaSocketOptions.java:35: error: package jdk.internal.access does not exist
> import jdk.internal.access.JavaIOFileDescriptorAccess;
>                            ^
> /home/RDMA/jdk12-8195160-version17/src/jdk.net/share/classes/jdk/net/RdmaSocketOptions.java:36: error: package jdk.internal.access does not exist
> import jdk.internal.access.SharedSecrets;
>                            ^
> /home/RDMA/jdk12-8195160-version17/src/jdk.net/share/classes/jdk/net/RdmaSocketOptions.java:218: error: cannot find symbol
>      private static final JavaIOFileDescriptorAccess fdAccess =
>                           ^
>    symbol:   class JavaIOFileDescriptorAccess
>    location: class RdmaSocketOptions
> 6 errors
> 
> Thanks,
> Lucy
> 
> 
>> -----Original Message-----
>> From: nio-dev [mailto:nio-dev-bounces at openjdk.java.net] On Behalf Of Lu,
>> Yingqi
>> Sent: Friday, November 16, 2018 5:49 AM
>> To: Chris Hegarty <chris.hegarty at oracle.com>
>> Cc: nio-dev at openjdk.java.net; Viswanathan, Sandhya
>> <sandhya.viswanathan at intel.com>; Aundhe, Shirish
>> <shirish.aundhe at intel.com>; Kaczmarek, Eric <eric.kaczmarek at intel.com>
>> Subject: RE: adding rsockets support into JDK
>>
>> Hi Chris,
>>
>> I already updated RdmaSockets.java in the version 17 of the patch with your
>> suggestions. http://cr.openjdk.java.net/~ylu/8195160.17/
>>
>> I have not generated Javadoc before. Would you please let me know what
>> kind of flags/options I need to use for the two classes?
>>
>> Also, in addition to attach the Javadocs for the two classes, anything else I
>> need to modify the CSR?
>>
>> Thanks,
>> Lucy
>>
>>> -----Original Message-----
>>> From: Chris Hegarty [mailto:chris.hegarty at oracle.com]
>>> Sent: Friday, November 16, 2018 3:19 AM
>>> To: Lu, Yingqi <yingqi.lu at intel.com>
>>> Cc: nio-dev at openjdk.java.net; Viswanathan, Sandhya
>>> <sandhya.viswanathan at intel.com>; Aundhe, Shirish
>>> <shirish.aundhe at intel.com>; Kaczmarek, Eric <eric.kaczmarek at intel.com>
>>> Subject: Re: adding rsockets support into JDK
>>>
>>> Lucy,
>>>
>>>
>>> On 15/11/18 19:12, Lu, Yingqi wrote:
>>>> Hi Chris,
>>>>
>>>> Here is the version 17 of the patch:
>>>> http://cr.openjdk.java.net/~ylu/8195160.17/
>>>
>>> This looks much better. Some final spec comments:
>>>
>>> 1) src/jdk.net/share/classes/jdk/net/RdmaSocketOptions.java
>>>
>>>    Looks good.
>>>
>>> 2) src/jdk.net/share/classes/jdk/net/RdmaSockets.java
>>>
>>>   a) class-level description now seems a little odd, and heavily weighted
>>>      towards channels, how about something like:
>>>
>>>     /**
>>>      * Factory methods for creating RDMA-based TCP sockets and channels.
>>>      *
>>>      * <p> The {@link #openSocket() openSocket} and {@link
>>>      * #openServerSocket() openServerSocket} methods create RDMA-based
>>>      * TCP sockets.
>>>      *
>>>      * <p> The {@link #openSelector() openSelector ...
>>>
>>>    b) Maybe put the security manager verbiage in its own paragraph, since
>>>       it relates to both sockets and channels.
>>>
>>>      * <p> When a security manager is installed ...
>>>
>>>    c) Please remove the trailing <p> on line L60.
>>>
>>>    d) openSocket: "Creates an unconnected RDMA socket."
>>>
>>>      Given that the socket options mention that the option is allowed to
>>>      be "set before the socket is bound or connected", then maybe this
>>>      opening sentence should be:
>>>          "Creates an unbound and unconnected RDMA socket.
>>>      Note: the other factory methods are clear on this point already.
>>>
>>>   3) Minor: personally I'd remove the @see ...NetworkChannel
>>>      It adds no value.
>>>
>>> That's it.
>>>
>>> Is it possible to generate the javadoc for these classes? It would be
>>> useful to have to attach to the CSR, or even to be viewable as a link from the
>> CSR.
>>>
>>> Can you please update the CSR and I will then add myself as reviewer?
>>>
>>> -Chris.