8297437: javadoc cannot link to old docs (with old style anchors)

Reviewed-by: hannesw

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/Extern.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1998, 2022, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1998, 2023, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -103,6 +103,11 @@ public class Extern {
          */
         final boolean relative;
 
+        /**
+         * Indicates that docs use old-form of anchors.
+         */
+        final boolean useOldFormId;
+
         /**
          * Constructor to build a Extern Item object and map it with the element name.
          * If the same element name is found in the map, then the first mapped
@@ -113,10 +118,11 @@ public class Extern {
          * file is picked.
          * @param relative    True if path is URL, false if directory path.
          */
-        Item(String elementName, DocPath path, boolean relative) {
+        Item(String elementName, DocPath path, boolean relative, boolean useOldFormId) {
             this.elementName = elementName;
             this.path = path;
             this.relative = relative;
+            this.useOldFormId = useOldFormId;
         }
 
         /**
@@ -186,7 +192,7 @@ public class Extern {
         DocPath p = fnd.relative ?
                 relativepath.resolve(fnd.path).resolve(filename) :
                 fnd.path.resolve(filename);
-        return new DocLink(p, memberName);
+        return new DocLink(p, fnd.useOldFormId ? getOldFormHtmlName(memberName) : memberName);
     }
 
     /**
@@ -256,7 +262,7 @@ public class Extern {
                 reporter.print(Kind.WARNING, resources.getText("doclet.Resource_error", elementListPath.getPath()));
             } else {
                 try (InputStream in = open(elementListUrl)) {
-                    readElementList(in, docUrl, false, versionNumber);
+                    readElementList(in, docUrl, false, versionNumber, isOldFormPlatformDocs(versionNumber));
                 } catch (IOException exc) {
                     throw new Fault(resources.getText(
                             "doclet.Resource_error", elementListPath.getPath()), exc);
@@ -267,6 +273,18 @@ public class Extern {
         }
     }
 
+    /**
+     * Checks if platform docs for the specified version use old-form anchors.
+     * Old-form anchors are used by Oracle docs for JDKs 8 and 9.
+     * It can be checked on https://docs.oracle.com/javase/<version>/docs/api
+     *
+     * @param version
+     * @return True if docs use old-form anchors
+     */
+    private boolean isOldFormPlatformDocs(int version) {
+        return 8 == version || 9 == version;
+    }
+
     /**
      * Return the resource path for the package or element list for the given {@code version}.
      * @param version the platform version number
@@ -419,7 +437,7 @@ public class Extern {
         try {
             URL link = elemlisturlpath.toURI().resolve(DocPaths.ELEMENT_LIST.getPath()).toURL();
             try (InputStream in = open(link)) {
-                readElementList(in, urlpath, false, 0);
+                readElementList(in, urlpath, false, 0, false);
             }
         } catch (URISyntaxException | MalformedURLException exc) {
             throw new Fault(resources.getText("doclet.MalformedURL", elemlisturlpath.toString()), exc);
@@ -438,7 +456,7 @@ public class Extern {
         try {
             URL link = elemlisturlpath.toURI().resolve(DocPaths.PACKAGE_LIST.getPath()).toURL();
             try (InputStream in = open(link)) {
-                readElementList(in, urlpath, false, 0);
+                readElementList(in, urlpath, false, 0, true);
             }
         } catch (URISyntaxException | MalformedURLException exc) {
             throw new Fault(resources.getText("doclet.MalformedURL", elemlisturlpath.toString()), exc);
@@ -462,27 +480,27 @@ public class Extern {
             file = file.resolveAgainst(DocumentationTool.Location.DOCUMENTATION_OUTPUT);
         }
         if (file.exists()) {
-            readElementList(file, path);
+            readElementList(file, path, false);
         } else {
             DocFile file1 = elemListPath.resolve(DocPaths.PACKAGE_LIST);
             if (!(file1.isAbsolute() || linkoffline)) {
                 file1 = file1.resolveAgainst(DocumentationTool.Location.DOCUMENTATION_OUTPUT);
             }
             if (file1.exists()) {
-                readElementList(file1, path);
+                readElementList(file1, path, true);
             } else {
                 throw new Fault(resources.getText("doclet.File_error", file.getPath()), null);
             }
         }
     }
 
-    private void readElementList(DocFile file, String path) throws Fault, DocFileIOException {
+    private void readElementList(DocFile file, String path, boolean isOldFormDoc) throws Fault, DocFileIOException {
         try {
             if (file.canRead()) {
                 boolean pathIsRelative
                         = !isUrl(path)
                         && !DocFile.createFileForInput(configuration, path).isAbsolute();
-                readElementList(file.openInputStream(), path, pathIsRelative, 0);
+                readElementList(file.openInputStream(), path, pathIsRelative, 0, isOldFormDoc);
             } else {
                 throw new Fault(resources.getText("doclet.File_error", file.getPath()), null);
             }
@@ -502,7 +520,8 @@ public class Extern {
      *                        or {@code 0} if it does not belong to a platform libraries doc bundle.
      * @throws IOException if there is a problem reading or closing the stream
      */
-    private void readElementList(InputStream input, String path, boolean relative, int platformVersion)
+    private void readElementList(InputStream input, String path, boolean relative, int platformVersion,
+                                 boolean isOldFormDoc)
                          throws IOException {
         try (BufferedReader in = new BufferedReader(new InputStreamReader(input))) {
             String elemname;
@@ -515,7 +534,7 @@ public class Extern {
                     elempath = basePath;
                     if (elemname.startsWith(DocletConstants.MODULE_PREFIX)) {
                         moduleName = elemname.replace(DocletConstants.MODULE_PREFIX, "");
-                        Item item = new Item(moduleName, elempath, relative);
+                        Item item = new Item(moduleName, elempath, relative, isOldFormDoc);
                         moduleItems.put(moduleName, item);
                     } else {
                         DocPath pkgPath = DocPath.create(elemname.replace('.', '/'));
@@ -533,7 +552,7 @@ public class Extern {
                         } else {
                             actualModuleName = moduleName == null ? DocletConstants.DEFAULT_ELEMENT_NAME : moduleName;
                         }
-                        Item item = new Item(elemname, elempath, relative);
+                        Item item = new Item(elemname, elempath, relative, isOldFormDoc);
                         packageItems.computeIfAbsent(actualModuleName, k -> new TreeMap<>())
                             .putIfAbsent(elemname, item); // first-one-wins semantics
                         showDiagnostic = false;
@@ -662,4 +681,65 @@ public class Extern {
             case WARN -> configuration.getMessages().warning(key, arg);
         }
     }
+
+    /**
+     * Converts a name to an old-form HTML name (old-form id).
+     *
+     * @param name the string that needs to be converted to a valid HTML name
+     * @return old-form HTML name
+     */
+    private String getOldFormHtmlName(String name) {
+        /* The HTML 4 spec at http://www.w3.org/TR/html4/types.html#h-6.2 mentions
+         * that the name/id should begin with a letter followed by other valid characters.
+         * The HTML 5 spec (draft) is more permissive on names/ids where the only restriction
+         * is that it should be at least one character long and should not contain spaces.
+         * The spec draft is @ http://www.w3.org/html/wg/drafts/html/master/dom.html#the-id-attribute.
+         *
+         * For HTML 4, we need to check for non-characters at the beginning of the name and
+         * substitute it accordingly, "_" and "$" can appear at the beginning of a member name.
+         * The method substitutes "$" with "Z:Z:D" and will prefix "_" with "Z:Z".
+         */
+
+        if (null == name)
+            return name;
+
+        StringBuilder sb = new StringBuilder();
+        for (int i = 0; i < name.length(); i++) {
+            char ch = name.charAt(i);
+            switch (ch) {
+                case '(':
+                case ')':
+                case '<':
+                case '>':
+                case ',':
+                    sb.append('-');
+                    break;
+                case ' ':
+                case '[':
+                    break;
+                case ']':
+                    sb.append(":A");
+                    break;
+                // Any appearance of $ needs to be substituted with ":D" and not with hyphen
+                // since a field name "P$$ and a method P(), both valid member names, can end
+                // up as "P--". A member name beginning with $ needs to be substituted with
+                // "Z:Z:D".
+                case '$':
+                    if (i == 0)
+                        sb.append("Z:Z");
+                    sb.append(":D");
+                    break;
+                // A member name beginning with _ needs to be prefixed with "Z:Z" since valid anchor
+                // names can only begin with a letter.
+                case '_':
+                    if (i == 0)
+                        sb.append("Z:Z");
+                    sb.append(ch);
+                    break;
+                default:
+                    sb.append(ch);
+            }
+        }
+        return sb.toString();
+    }
 }

test/langtools/jdk/javadoc/doclet/testClassCrossReferences/TestClassCrossReferences.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2002, 2022, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2002, 2023, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -65,7 +65,7 @@ public class TestClassCrossReferences extends JavadocTester {
                     java/math/BigDecimal.html" title="class or interface in java.math" class="extern\
                     al-link"><code>Link to external class BigDecimal</code></a>""",
                 "<a href=\"" + uri + """
-                    java/math/BigInteger.html#gcd(java.math.BigInteger)" title="class or interface i\
+                    java/math/BigInteger.html#gcd-java.math.BigInteger-" title="class or interface i\
                     n java.math" class="external-link"><code>Link to external member gcd</code></a>""",
                 "<a href=\"" + uri + """
                     javax/tools/SimpleJavaFileObject.html#uri" title="class or interface in javax.to\
@@ -102,7 +102,7 @@ public class TestClassCrossReferences extends JavadocTester {
                     java/math/BigDecimal.html" title="class or interface in java.math" class="extern\
                     al-link"><code>Link to external class BigDecimal</code></a>""",
                 "<a href=\"" + uri + """
-                    java/math/BigInteger.html#gcd(java.math.BigInteger)" title="class or interface i\
+                    java/math/BigInteger.html#gcd-java.math.BigInteger-" title="class or interface i\
                     n java.math" class="external-link"><code>Link to external member gcd</code></a>""",
                 "<a href=\"" + uri + """
                     javax/tools/SimpleJavaFileObject.html#uri" title="class or interface in javax.to\

test/langtools/jdk/javadoc/doclet/testExternalOverriddenMethod/TestExternalOverriddenMethod.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2003, 2022, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2003, 2023, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -56,13 +56,13 @@ public class TestExternalOverriddenMethod extends JavadocTester {
                 """
                     <dt>Overrides:</dt>
                     <dd><code><a href=\"""" + uri + """
-                    /java/io/FilterReader.html#read()" title="class or interface in java.io" class="\
+                    /java/io/FilterReader.html#read--" title="class or interface in java.io" class="\
                     external-link">read</a></code>&nbsp;in class&nbsp;<code><a href=\"""" + uri + """
                     /java/io/FilterReader.html" title="class or interface in java.io" class="external-link">FilterReader</a></code></dd>""",
                 """
                     <dt>Specified by:</dt>
                     <dd><code><a href=\"""" + uri + """
-                    /java/io/DataInput.html#readInt()" title="class or interface in java.io" class="\
+                    /java/io/DataInput.html#readInt--" title="class or interface in java.io" class="\
                     external-link">readInt</a></code>&nbsp;in interface&nbsp;<code><a href=\"""" + uri + """
                     /java/io/DataInput.html" title="class or interface in java.io" class="external-link">DataInput</a></code></dd>"""
         );

test/langtools/jdk/javadoc/doclet/testHref/TestHref.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2003, 2022, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2003, 2023, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -53,7 +53,7 @@ public class TestHref extends JavadocTester {
         checkOutput("pkg/C1.html", true,
                 //External link.
                 """
-                    href="http://java.sun.com/j2se/1.4/docs/api/java/lang/Object.html#wait(long,int)\"""",
+                    href="http://java.sun.com/j2se/1.4/docs/api/java/lang/Object.html#wait-long-int-\"""",
                 //Member summary table link.
                 """
                     href="#method(int,int,java.util.ArrayList)\"""",

test/langtools/jdk/javadoc/doclet/testLinkOption/TestLinkOption.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2002, 2022, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2002, 2023, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -89,7 +89,7 @@ public class TestLinkOption extends JavadocTester {
         checkOutput("pkg/B.html", true,
                 """
                     <div class="block">A method with html tag the method <a href=\"""" + url + """
-                    java/lang/ClassLoader.html#getSystemClassLoader()" title="class or interface in \
+                    java/lang/ClassLoader.html#getSystemClassLoader--" title="class or interface in \
                     java.lang" class="external-link"><code><b>getSystemClassLoader()</b></code></a> \
                     as the parent class loader.</div>""",
                 """

test/langtools/jdk/javadoc/doclet/testLinkPlatform/TestLinkPlatform.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2020, 2022, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2020, 2023, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -23,7 +23,7 @@
 
 /*
  * @test
- * @bug 8216497
+ * @bug 8216497 8297437
  * @summary javadoc should auto-link to platform classes
  * @library /tools/lib ../../lib
  * @modules
@@ -103,11 +103,19 @@ public class TestLinkPlatform extends JavadocTester {
             // Make sure there is no message about missing element-list resource
             checkOutput(Output.OUT, false, "element-list");
             String url = getPlatformUrlString(version);
-            checkOutput("p/q/A.html", true,
+            if (version <= 9) {
-                    "<a href=\"" + url + "\"",
+                checkOutput("p/q/A.html", true,
-                    "<a href=\"" + url + "#clone()\" title=\"class or interface in java.lang\" class=\"external-link\">",
+                        "<a href=\"" + url + "\"",
-                    "<a href=\"" + url + "#equals(java.lang.Object)\" title=\"class or interface in java.lang\" class=\"external-link\">",
+                        "<a href=\"" + url + "#clone--\" title=\"class or interface in java.lang\" class=\"external-link\">",
-                    "<a href=\"" + url + "#finalize()\" title=\"class or interface in java.lang\" class=\"external-link\">");
+                        "<a href=\"" + url + "#equals-java.lang.Object-\" title=\"class or interface in java.lang\" class=\"external-link\">",
+                        "<a href=\"" + url + "#finalize--\" title=\"class or interface in java.lang\" class=\"external-link\">");
+            } else {
+                checkOutput("p/q/A.html", true,
+                        "<a href=\"" + url + "\"",
+                        "<a href=\"" + url + "#clone()\" title=\"class or interface in java.lang\" class=\"external-link\">",
+                        "<a href=\"" + url + "#equals(java.lang.Object)\" title=\"class or interface in java.lang\" class=\"external-link\">",
+                        "<a href=\"" + url + "#finalize()\" title=\"class or interface in java.lang\" class=\"external-link\">");
+            }
         }
     }
 
@@ -125,11 +133,19 @@ public class TestLinkPlatform extends JavadocTester {
 
             checkExit(Exit.OK);
             String url = getCustomPlatformUrlString(version);
-            checkOutput("p/q/A.html", true,
+            if (version <= 9) {
-                    "<a href=\"" + url + "\"",
+                checkOutput("p/q/A.html", true,
-                    "<a href=\"" + url + "#clone()\" title=\"class or interface in java.lang\" class=\"external-link\">",
+                        "<a href=\"" + url + "\"",
-                    "<a href=\"" + url + "#equals(java.lang.Object)\" title=\"class or interface in java.lang\" class=\"external-link\">",
+                        "<a href=\"" + url + "#clone--\" title=\"class or interface in java.lang\" class=\"external-link\">",
-                    "<a href=\"" + url + "#finalize()\" title=\"class or interface in java.lang\" class=\"external-link\">");
+                        "<a href=\"" + url + "#equals-java.lang.Object-\" title=\"class or interface in java.lang\" class=\"external-link\">",
+                        "<a href=\"" + url + "#finalize--\" title=\"class or interface in java.lang\" class=\"external-link\">");
+            } else {
+                checkOutput("p/q/A.html", true,
+                        "<a href=\"" + url + "\"",
+                        "<a href=\"" + url + "#clone()\" title=\"class or interface in java.lang\" class=\"external-link\">",
+                        "<a href=\"" + url + "#equals(java.lang.Object)\" title=\"class or interface in java.lang\" class=\"external-link\">",
+                        "<a href=\"" + url + "#finalize()\" title=\"class or interface in java.lang\" class=\"external-link\">");
+            }
         }
     }
 
@@ -147,11 +163,19 @@ public class TestLinkPlatform extends JavadocTester {
 
             checkExit(Exit.OK);
             String url = getCustomPlatformUrlString(version);
-            checkOutput("p/q/A.html", true,
+            if (version <= 9) {
-                    "<a href=\"" + url + "\"",
+                checkOutput("p/q/A.html", true,
-                    "<a href=\"" + url + "#clone()\" title=\"class or interface in java.lang\" class=\"external-link\">",
+                        "<a href=\"" + url + "\"",
-                    "<a href=\"" + url + "#equals(java.lang.Object)\" title=\"class or interface in java.lang\" class=\"external-link\">",
+                        "<a href=\"" + url + "#clone--\" title=\"class or interface in java.lang\" class=\"external-link\">",
-                    "<a href=\"" + url + "#finalize()\" title=\"class or interface in java.lang\" class=\"external-link\">");
+                        "<a href=\"" + url + "#equals-java.lang.Object-\" title=\"class or interface in java.lang\" class=\"external-link\">",
+                        "<a href=\"" + url + "#finalize--\" title=\"class or interface in java.lang\" class=\"external-link\">");
+            } else {
+                checkOutput("p/q/A.html", true,
+                        "<a href=\"" + url + "\"",
+                        "<a href=\"" + url + "#clone()\" title=\"class or interface in java.lang\" class=\"external-link\">",
+                        "<a href=\"" + url + "#equals(java.lang.Object)\" title=\"class or interface in java.lang\" class=\"external-link\">",
+                        "<a href=\"" + url + "#finalize()\" title=\"class or interface in java.lang\" class=\"external-link\">");
+            }
         }
     }