> On Jun 14, 2017, at 9:29 PM, huizhe wang <huizhe.w...@oracle.com> wrote: > > > On 6/14/2017 4:58 PM, Mandy Chung wrote: >>> On Jun 14, 2017, at 4:19 PM, huizhe wang <huizhe.w...@oracle.com> wrote: >>> >>> Hi, >>> >>> Please review new package descriptions for jdk.xml.dom module. Note that >>> the link to the XPath specificaiton in xpath/package-info.java is the >>> formal release that is different from the one in the classes. The later was >>> a working release now requires a login [1]. The only difference in the >>> formal release is that the error numbers in XPathException were changed >>> from 1 and 2 to 51 and 52. We may consider updating to the formal release >>> in JDK 10. >>> >> The org/w3c/dom/xpath/* classes all have the link to [1]. The package >> summary should explain the difference between two versions i.e. >> XPathException spec difference as it includes an accessible link. > > The link may indeed be a source of confusion. Explaining details on the > differences can also be troublesome because questions can be asked as why > then we didn't update the package. So instead, I updated the module > description to explain why these packages are here, and removed the links to > avoid any potential confusion. In general, the only purpose of the module is > to hold the APIs that old applications may have dependency on.
Removing the link is a good alternative. I suggest to mention it a working release and its date. >> >>> JBS: https://bugs.openjdk.java.net/browse/JDK-8182111 >>> webrevs: http://cr.openjdk.java.net/~joehw/jdk9/8182111/webrev/ >>> >> These APIs are supported @since 9. They were not officially supported in >> the previous releases. > > These were not SE APIs, and still are not SE APIs in 9. But they were indeed > included in the JDK since 1.4, which is why we put them in this module that's > for backward compatibility only. I therefore think it shall reflect the fact > that they've been in the JDK @since 1.4. "@since 9" would give an impression > that they are introduced in 9. This indeed has been a confusing story. JDK-8042244 promotes these packages to be supported in JDK 9. I suggest @since 9 since 9 is the first release these APIs are promoted whereas previously are not supported. > > Here's updated webrev: > http://cr.openjdk.java.net/~joehw/jdk9/8182111/webrev01/ The change in module-info.java seems unnecessary and in fact it’s not for backward compatibility. They are exported APIs and they are not endorsed by JAXP (hence not in java.xml). I think the original module-info.java is adequate. Mandy
