RFR(JAXP): 8165784: Deprecate the internal Catalog API in JDK 9

[Joe Wang]

Hi Daniel, Roger,

Thanks for the review!

The webrev is updated as we discussed. The deprecation message is in the 
main interface classes but stresses that the entire application under 
the resolver package and the util class (XMLCatalogResolver.java) are 
deprecated and subject to removal in a future release.

http://cr.openjdk.java.net/~joehw/jdk9/8165784/webrev/


As you noted, there's an internal usage in jaxws/jaxb. Aleksej and I 
have worked together to get the standalone updated with the new Catalog 
API. The JDK integration will happen soon.

The deprecation is not technically necessary for an internal API. Even 
without the JDK 9 encapsulation, the compiler has always produced a 
warning that the internal API is subject to change/removal, and should 
not be directly referenced. Unfortunately, this particular one is in a 
awkward situation. It was integrated along with jaxp from the Apache 
library without a public API. Internal and external users are therefore 
taken it as if it's okay to use. The encapsulation could be viewed 
similarly as the existing compiler warning. The deprecation message 
therefore serves as an enforcement that it is indeed in the plan to be 
removed.

Best,
Joe

On 9/14/16, 10:15 AM, Roger Riggs wrote:
> Hi,
>
> I don't see there is much point in deprecating an API that is not 
> exported.
> It doesn't show up in the javadoc and the compiler overrides with 
> -addexports would already be needed.
>
> The internal uses should be updated but that should not be a reason to 
> put off warning other
> consumers that a transition to another API is needed.  One of the 
> purposes of @deprecated is to start
> a very slow/long process moving.
>
> $.02, Roger
>
>
> On 9/14/2016 5:11 AM, Daniel Fuchs wrote:
>> Hi Joe,
>>
>> As much as I would like to support removing obsolete
>> classes, I wonder if the forRemoval=true is a bit
>> premature.
>>
>> I see that for instance, 
>> com.sun.org.apache.xml.internal.resolver.Catalog
>> seems to be still used at many places in our code base.
>>
>> It would be more convincing if we could first make our
>> own codebase stop using these classes: then we could
>> be confident that forRemoval=true is the better choice!
>>
>> best regards,
>>
>> -- daniel
>>
>> On 14/09/16 05:48, Joe Wang wrote:
>>> Hi,
>>>
>>> Please review the deprecation of the internal Catalog API.
>>>
>>> JBS: https://bugs.openjdk.java.net/browse/JDK-8165784
>>> webrev: http://cr.openjdk.java.net/~joehw/jdk9/8165784/webrev/
>>>
>>> Thanks,
>>> Joe
>>
>