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

Fri Feb 21 15:04:44 UTC 2020

> 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