forRemoval=true indicates that the API will be removed in a future release and does not mean it will be removed in N+1.
Hope this clears the confusion. Mandy > On Jun 13, 2016, at 9:17 AM, David DeHaven <david.deha...@oracle.com> wrote: > > [removed bad email address..] > > Ok, my understanding was that forRemoval was intended for the next release, > so setting it to true meant we were saying "removing in JDK 10." If that's > NOT the case then we should set it to true for this particular case since > this method is tied specifically to the plugin and not Applet. > > I just don't want to hear any whining when it comes around to JDK 11 and it > hasn't been removed yet ;) > > I still don't know about Applet as anyone using it outside of plugin has been > very quiet and I suspect we WON'T hear anything until JDK 9 gets released and > developers start using it, it seems safer to leave it false for now and > revisit marking for removal in 10 when hopefully we've had some feedback. > > -DrD- > >> Yes, ultimately the decision is up to Kevin and Dave (or whoever is in >> charge of technical decision-making in this area). >> >> I wanted to provide some clarity on the use of forRemoval=true. >> >> The specification is fairly neutral, saying only that there is "intent to >> remove" the API "in a future version." >> >> In practice, for the JDK, I'm trying to make sure we set forRemoval=true >> only when there are definite plans for removal in the near future, for >> example, in the following release. I want to avoid a situation where there >> are a bunch of APIs in the JDK that have forRemoval=true but that are >> hanging around for several releases before they are eventually removed. (Or >> not.) >> >> When I discussed this issue with the team with respect to the Applet API, I >> asked whether Applets would be removed in the next release (after JDK 9). >> There was some hemming and hawing, and eventually it emerged that there were >> still some narrow use cases that would probably still need to be supported >> even in the next release, and they weren't entirely sure when Applet could >> actually be removed. Based on that discussion we deprecated Applet with >> forRemoval=false in JDK 9, and we'll revisit this in the future when plans >> are more definite. >> >> I had thought that the plugin and Applets were closely related enough so >> that they ought to be treated the same. This would argue that this API >> should also be deprecated in JDK 9 with forRemoval=false, and revisited at >> the same time as Applet. But I could be mistaken, and it might make sense to >> treat the plugin separately from Applet. >> >> s'marks >> >> On 6/10/16 11:30 AM, Mandy Chung wrote: >>> This method is about the fate of plugin support in a future regardless of >>> the presence of java.applet.Applet API. The @deprecated note may cause the >>> confusion. >>> >>> What I understand from the past discussion with Kevin and Dave, we want >>> this method to be removed in a future release - the earliest possible >>> release would be N+1 when it’s deprecated for removal in JDK N. >>> >>> I’ll let Kevin and Dave to clear this up and make the final call. >>> >>> Mandy >>> >>>> On Jun 10, 2016, at 9:58 AM, Stuart Marks <stuart.ma...@oracle.com> wrote: >>>> >>>> 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-...@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.ti...@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-...@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.ti...@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 >>>>>>> >>>>>> >>>>> >>> >
