RFR(JAXP) 8182111: Package summary is missing in jdk.xml.dom module

[huizhe wang]

On 6/14/2017 4:58 PM, Mandy Chung wrote:
>> On Jun 14, 2017, at 4:19 PM, huizhe wang <huizhe.wang at 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.
>
>> 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.

Here's updated webrev:
http://cr.openjdk.java.net/~joehw/jdk9/8182111/webrev01/

Best,
Joe

>
> Mandy
>
>> [1] http://www.w3.org/2002/08/WD-DOM-Level-3-XPath-20020820
>>
>> Thanks,
>> Joe
>>