Review Request: 8156960 Deprecate JSObject.getWindow(Applet) method

Stuart Marks stuart.marks at oracle.com
Fri Jun 10 16:58:07 UTC 2016 

Hi, sorry I had missed this earlier.

It's surprising if forRemoval=true were to be added to this API when the rest of 
the Applet API has forRemoval=false. Is it the intent, for example, to have 
JSObject.getWindow() removed from JDK 10 but to have the rest of the Applet API 
remain?

My understanding of the plan was to deprecate the Applet API in JDK 9 with 
forRemoval=false. Then, in a future release, when removal plans become more 
definite, to change forRemoval to true, and in a subsequent release, to remove 
the Applet APIs. I'd think that plan would apply here as well.

Put another way, I'd recommend that we set forRemoval=true only when the plan is 
more definite than "we plan to remove this in some future, as yet unspecified 
release."

s'marks


On 6/8/16 5:34 PM, Daniil Titov wrote:
> Hello,
>
> Please review the new version of the fix for JDK9.
>
> 1. "forRemoval = true" is added to @Deprecated annotation for JSObject.getWindow(Applet) method.
> 2.  A new doc bundle for JSObject documentation is added in the docs build.
>
> Webrev: http://cr.openjdk.java.net/~dtitov/8156960/jdk/webrev.01
>         http://cr.openjdk.java.net/~dtitov/8156960/webrev.01
>
>
> Bug: https://bugs.openjdk.java.net/browse/JDK-8156960
>
> Thank you!
>
> Best regards,
> Daniil
>
> -----Original Message-----
> From: Mandy Chung
> Sent: Wednesday, June 08, 2016 3:09 PM
> To: Daniil Titov
> Cc: David Dehaven; Stuart Marks; Erik Joelsson; build-dev; build-infa-dev at openjdk.java.net; awt-dev; Kevin Rushforth
> Subject: Re: Review Request: 8156960 Deprecate JSObject.getWindow(Applet) method
>
> That’s right.  It requires to add a new doc bundle in the docs build.  What you did was the right direction.  Can you update the webrev?
>
> FYI.  There is an effort under discussion to revisit the number of docs bundle generated and clean up the docs build.
>
> Mandy
>
>> On Jun 8, 2016, at 2:48 PM, Daniil Titov <daniil.x.titov at oracle.com> wrote:
>>
>> NON_CORE_PKGS variable is not used in make/Javadoc.gmk, so just adding a new package in this variable will not make this package included in any docs. We will need to create a new javadoc target for JSObject documentation ( or add it to some existing target, but it doesn't look like there is one that fits it). For example:
>>
>>
>> diff -r 389c2d2842a5 make/Javadoc.gmk
>> --- a/make/Javadoc.gmk	Wed May 25 12:53:26 2016 +0200
>> +++ b/make/Javadoc.gmk	Thu Jun 02 16:20:35 2016 -0700
>> @@ -82,7 +82,7 @@
>> PLUGIN2_FIRST_COPYRIGHT_YEAR = 2007
>> JDKNET_FIRST_COPYRIGHT_YEAR = 2014
>> JACCESSAPI_FIRST_COPYRIGHT_YEAR = 2002
>> -
>> +JSOBJECT_FIRST_COPYRIGHT_YEAR = 1993
>>
>> # Oracle name
>> FULL_COMPANY_NAME = Oracle and/or its affiliates @@ -1031,6 +1031,64
>> @@
>>
>> #############################################################
>> #
>> +# jsobjectdocs
>> +#
>> +
>> +ALL_OTHER_TARGETS += jsobjectdoc
>> +
>> +JSOBJECT_DOCDIR := $(JRE_API_DOCSDIR)/plugin/jsobject
>> +JSOBJECT2COREAPI := ../../../$(JDKJRE2COREAPI) JSOBJECT_DOCTITLE :=
>> +Java$(TRADEMARK) JSObject Doc JSOBJECT_WINDOWTITLE := Java JSObect
>> +Doc JSOBJECT_HEADER := <strong>Java JSObject Doc</strong>
>> +JSOBJECT_BOTTOM := $(call
>> +CommonBottom,$(JSOBJECT_FIRST_COPYRIGHT_YEAR))
>> +# JSOBJECT_PKGS is located in NON_CORE_PKGS.gmk
>> +
>> +JSOBJECT_INDEX_HTML = $(JSOBJECT_DOCDIR)/index.html
>> +JSOBJECT_OPTIONS_FILE = $(DOCSTMPDIR)/jsobject.options
>> +JSOBJECT_PACKAGES_FILE = $(DOCSTMPDIR)/jsobject.packages
>> +
>> +# The modules required to be documented JSOBJECT_MODULES =
>> +jdk.jsobject
>> +
>> +jsobjectdocs: $(JSOBJECT_INDEX_HTML)
>> +
>> +# Set relative location to core api document root
>> +$(JSOBJECT_INDEX_HTML): GET2DOCSDIR=$(JSOBJECT2COREAPI)/..
>> +
>> +# Run javadoc if the index file is out of date or missing
>> +$(JSOBJECT_INDEX_HTML): $(JSOBJECT_OPTIONS_FILE) $(JSOBJECT_PACKAGES_FILE) $(COREAPI_INDEX_FILE)
>> +	$(prep-javadoc)
>> +	$(call JavadocSummary,$(JSOBJECT_OPTIONS_FILE),$(JSOBJECT_PACKAGES_FILE))
>> +	$(JAVADOC_CMD_SMALL) -d $(@D) \
>> +	    @$(JSOBJECT_OPTIONS_FILE) @$(JSOBJECT_PACKAGES_FILE)
>> +
>> +# Create file with javadoc options in it
>> +$(JSOBJECT_OPTIONS_FILE):
>> +	$(prep-target)
>> +	@($(call COMMON_JAVADOCFLAGS) ; \
>> +          $(call COMMON_JAVADOCTAGS) ; \
>> +	  $(call OptionOnly,-Xdoclint:none) ; \
>> +          $(call OptionPair,-system,none) ; \
>> +	  $(call OptionPair,-modulesourcepath,$(RELEASEDOCS_MODULESOURCEPATH)) ; \
>> +	  $(call OptionPair,-addmods,$(JSOBJECT_MODULES)) ; \
>> +	  $(call OptionPair,-encoding,ascii) ; \
>> +	  $(call OptionOnly,-nodeprecatedlist) ; \
>> +	  $(call OptionPair,-doctitle,$(JSOBJECT_DOCTITLE)) ; \
>> +	  $(call OptionPair,-windowtitle,$(JSOBJECT_WINDOWTITLE) $(DRAFT_WINTITLE)); \
>> +	  $(call OptionPair,-header,$(JSOBJECT_HEADER)$(DRAFT_HEADER)); \
>> +	  $(call OptionPair,-bottom,$(JSOBJECT_BOTTOM)$(DRAFT_BOTTOM)); \
>> +	  $(call OptionTrip,-linkoffline,$(JSOBJECT2COREAPI),$(COREAPI_DOCSDIR)/); \
>> +	) >> $@
>> +
>> +# Create a file with the package names in it
>> +$(JSOBJECT_PACKAGES_FILE): $(call PackageDependencies,$(JSOBJECT_PKGS))
>> +	$(prep-target)
>> +	$(call PackageFilter,$(JSOBJECT_PKGS))
>> +
>> +
>> +#############################################################
>> +#
>> # mgmtdocs
>> #
>>
>>
>> Best regards,
>> Daniil
>>
>>
>>
>> -----Original Message-----
>> From: David DeHaven
>> Sent: Wednesday, June 08, 2016 1:23 PM
>> To: Mandy Chung
>> Cc: Daniil Titov; Stuart Marks; Erik Joelsson; build-dev;
>> build-infa-dev at openjdk.java.net; awt-dev; Kevin Rushforth
>> Subject: Re: Review Request: 8156960 Deprecate
>> JSObject.getWindow(Applet) method
>>
>>
>> How about NON_CORE_PKGS.gmk for javadoc?
>>
>> Something like:
>>
>> diff --git a/make/common/NON_CORE_PKGS.gmk
>> b/make/common/NON_CORE_PKGS.gmk
>> --- a/make/common/NON_CORE_PKGS.gmk
>> +++ b/make/common/NON_CORE_PKGS.gmk
>> @@ -44,6 +44,8 @@
>>     org.w3c.dom.events \
>>     org.w3c.dom.views
>>
>> +JSOBJECT_PKGS = netscape.javascript
>> +
>> JDI_PKGS = com.sun.jdi \
>>     com.sun.jdi.event \
>>     com.sun.jdi.request \
>> @@ -113,6 +115,7 @@
>>
>> # non-core packages in rt.jar
>> NON_CORE_PKGS = $(DOMAPI_PKGS) \
>> +    $(JSOBJECT_PKGS) \
>>     $(MGMT_PKGS) \
>>     $(JAAS_PKGS) \
>>     $(JGSS_PKGS) \
>>
>> -DrD-
>>
>>> The client team owns jdk.jsobject module and so I add awt-dev to this thread.  And bcc jdk9-dev.
>>>
>>> It is not Java SE API and it should not add to CORE-PKGS.gmk.  As for @Deprecated, I believe the plan is to remove the getWindows method in a future release. Kevin and Dave can confirm.
>>>
>>> Mandy
>>>
>>>> On Jun 8, 2016, at 12:33 PM, Daniil Titov <daniil.x.titov at oracle.com> wrote:
>>>>
>>>> Hello,
>>>>
>>>>
>>>>
>>>> Please review the fix for JDK 9.
>>>>
>>>>
>>>>
>>>> The fix adds @Deprecated annotation to netscape.javascript.JSObject.getWindow(Applet) method and ensures that netscape.javascript package is included in the generated docs.
>>>>
>>>>
>>>>
>>>> Bug: https://bugs.openjdk.java.net/browse/JDK-8156960
>>>>
>>>>
>>>>
>>>> Webrev:   http://cr.openjdk.java.net/~dtitov/8156960/jdk/webrev.00/
>>>>
>>>>        http://cr.openjdk.java.net/~dtitov/8156960/webrev.00/
>>>>
>>>>
>>>>
>>>>
>>>>
>>>> Best regards,
>>>>
>>>> Daniil
>>>
>>
>

More information about the build-dev mailing list