Apple Extensions are not documented in Java 7 API Docs

[Mike Swingler]

On Aug 13, 2012, at 6:26 AM, Artem Ananiev <artem.ananiev at oracle.com> wrote:

> On 8/9/2012 8:13 PM, Andrew Hughes wrote:
>> 
>> ----- Original Message -----
>>> 
>>> On 8/9/2012 3:09 PM, Hendrik Schreiber wrote:
>>>> On Aug 9, 2012, at 12:59 PM, Artem Ananiev wrote:
>>>>> 
>>>>> Apple extensions are not a part of JDK specification, and I really
>>>>> doubt they will ever be. Applications should be ready to work
>>>>> without them at all.
>>>> 
>>>> Yes, they are not part of the specs.
>>>> 
>>>> But: It would be a huge mistake to remove them as they effectively
>>>> allow developers to write halfway decent desktop apps.
>>>> Making them unavailable would cripple the platform unecessarily.
>>> 
>>> I didn't say anything about confirmed plans to remove or keep them in
>>> JDK. I completely agree these classes allow Java applications behave
>>> and
>>> look more native.
>>> 
>>> My statement was to make sure everybody understands official status
>>> of
>>> any piece of code that is not public API.
>>> 
>> 
>> I don't see any reason these APIs couldn't be documented under "Non-core APIs"
>> along with the others: http://www.oracle.com/technetwork/java/javase/documentation/api-jsp-136079.html
> 
> The reason is that it's not API, i.e. something we (AWT team) commit to support in the future. To commit, we should at least make sure API can be implemented in JDK7, which is very different from Apple's JDK6, where they could potentially use private Mac OS X functions.

These can be perfectly well supported and documented as non-core API, as Andrew suggests. OpenJDK 7 currently has the all the sources to the complete eAWT, and they are implemented in terms of public Apple framework API.

I think the best course of action is for the eAWT to be clearly documented, with pieces of it being marked as deprecated as there are replacements available in actual core APIs.

Regards,
Mike Swingler
Apple Inc.