RFR: 8232438: Remove ?is-external=true from external links

Fri Feb 21 16:58:33 UTC 2020

Pavel,

Thanks for researching the background.

-- Jon

On 2/21/20 7:04 AM, Pavel Rappo wrote:
>> On 20 Feb 2020, at 17:49, Jonathan Gibbons <jonathan.gibbons at oracle.com> wrote:
>>
>> On 2/20/20 7:14 AM, Pavel Rappo wrote:
>>> Hi Hannes,
>>>
>>> What is the background of this "?is-external=true" feature? How was it used in
>>> the first place? Is there anything I can read on that?
>> My recollection/impression is that this may have been related to the frames feature
>> and to support for updating the window title.  If you want to follow up, I recommend
>> getting an older copy of the source and look for occurrences of the string, particularly
>> in .js files.
> Thanks, Jon. It turns out that "?is-external=true" is exclusively used for
> displaying external documentation in the framed version of generated HTML pages.
> We did away with frames in Standard Doclet in JDK-8215599, so there should be no
> repercussions for removing this leftover bit.
>
> A bit of background
> ===================
>
> Javadoc can be instructed to use external referenced classes [1]:
>
>      *Note*: External referenced classes are classes that are not passed into
>      the javadoc command on the command line. Links in the generated
>      documentation to external referenced classes are called external references
>      or external links. For example, if you run the javadoc command on only the
>      java.awt package, then any class in java.lang, such as Object, is an
>      external referenced class. Use the -link and -linkoffline options to link
>      to external referenced classes. The source comments of external referenced
>      classes are not available to the javadoc command run.
>
> That "?is-external=true" portion of the URL was used for deciding if a page
> should set its title to the parent window (the container of all the frames).
>
> The code that used to handle this was a tiny JavaScript function generated by
> (currently extinct) HtmlWriter.java
>
>      098      /**
>      099       * Print the script code to be embeded before the  </HEAD> tag.
>      100       */
>      101      protected void printWinTitleScript(String winTitle){
>      102          if(winTitle != null && winTitle.length() > 0) {
>      103              script();
>      104              println("function windowTitle()");
>      105              println("{");
>      106              println("    if (location.href.indexOf('is-external=true') == -1) {");
>      107              println("        parent.document.title=\"" + winTitle + "\";");
>      108              println("    }");
>      109              println("}");
>      110              scriptEnd();
>      111              noScript();
>      112              noScriptEnd();
>      113          }
>      114      }
>
> This function was then inserted into HTML pages that were describing types.
> For example, here is an excerpt from String.html [2]:
>
>      ...
>      <body>
>      <script type="text/javascript"><!--
>          try {
>              if (location.href.indexOf('is-external=true') == -1) {
>                  parent.document.title="String (Java Platform SE 8 )";
>              }
>          }
>          catch(err) {
>          }
>      //-->
>      ...
>
> -------------------------------------------------------------------------------
> [1] https://docs.oracle.com/javase/8/docs/technotes/tools/windows/javadoc.html
> [2] https://docs.oracle.com/javase/8/docs/api/java/lang/String.html
>
>>> I'm surprised to see the tests' @bug tags are updated to include this bug number.
>>>
>>> I thought that an @bug tag needs to be updated when the test has been meaningfully
>>> changed. In other words, when the relation between the test and the bug is
>>> stronger than mere "updated because otherwise fails".
>> Agreed,
>>> I appreciate that the semantics of @bug might depend on the area, still:
>>>
>>>    https://openjdk.java.net/jtreg/faq.html#when-should-i-update-the-bug-entry-in-a-test-description
>> I think opinions have differed over time, and there is room for a range of opinion.
>> I think the best way to look at this is to ask, if I want to select and run the tests related
>> to a specific bug fix, should I include this test. That is what the `@bug` tag and the
>> corresponding `-bug` option are for.
>>
>>> -Pavel
>>>
>>>> On 20 Feb 2020, at 13:09, Hannes Wallnöfer <hannes.wallnoefer at oracle.com> wrote:
>>>>
>>>> Please review:
>>>>
>>>> JBS: https://bugs.openjdk.java.net/browse/JDK-8232438
>>>> Webrev: http://cr.openjdk.java.net/~hannesw/8232438/webrev.00/
>>>>
>>>> The is-external=true query was the only use of query functionality in DocLink, so I removed support for query strings in DocLink. The rest of the patch consists of removing the query string from test fixtures.
>>>>
>>>> Thanks,
>>>> Hannes