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

Roman Marchenko · Paul Hohensee · commit 3bcf8e270c17 · 2023-02-15T15:51:12.000Z
Reviewed-by: phh
Backport-of: 15a14884013a975707008f648b8e4864e16006ed
diff --git a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/Extern.java b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/Extern.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1998, 2021, 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
@@ -108,6 +108,11 @@ private static class Item {
          */
         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
@@ -118,10 +123,11 @@ private static class Item {
          * 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;
         }
 
         /**
@@ -191,7 +197,7 @@ public DocLink getExternalLink(Element element, DocPath relativepath, String fil
         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);
     }
 
     /**
@@ -261,7 +267,7 @@ public void checkPlatformLinks(String linkPlatformProperties, Reporter reporter)
                 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);
@@ -272,6 +278,18 @@ public void checkPlatformLinks(String linkPlatformProperties, Reporter reporter)
         }
     }
 
+    /**
+     * 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
@@ -424,7 +442,7 @@ private void readElementListFromURL(String urlpath, URL elemlisturlpath) throws
         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);
@@ -443,7 +461,7 @@ private void readPackageListFromURL(String urlpath, URL elemlisturlpath) throws
         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);
@@ -467,27 +485,27 @@ private void readElementListFromFile(String path, DocFile elemListPath)
             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);
             }
@@ -507,7 +525,8 @@ private void readElementList(DocFile file, String path) throws Fault, DocFileIOE
      *                        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;
@@ -520,7 +539,7 @@ private void readElementList(InputStream input, String path, boolean relative, i
                     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('.', '/'));
@@ -538,7 +557,7 @@ private void readElementList(InputStream input, String path, boolean relative, i
                         } 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
                         issueWarning = false;
@@ -659,4 +678,65 @@ private InputStream open(URL url) throws IOException {
 
         return in;
     }
+
+    /**
+     * 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();
+    }
 }
diff --git a/test/langtools/jdk/javadoc/doclet/testClassCrossReferences/TestClassCrossReferences.java b/test/langtools/jdk/javadoc/doclet/testClassCrossReferences/TestClassCrossReferences.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2002, 2020, 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 void test() {
                     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 void test_warning() {
                     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\
diff --git a/test/langtools/jdk/javadoc/doclet/testExternalOverriddenMethod/TestExternalOverriddenMethod.java b/test/langtools/jdk/javadoc/doclet/testExternalOverriddenMethod/TestExternalOverriddenMethod.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2003, 2020, 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 void test() {
                 """
                     <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>"""
         );
diff --git a/test/langtools/jdk/javadoc/doclet/testHref/TestHref.java b/test/langtools/jdk/javadoc/doclet/testHref/TestHref.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2003, 2021, 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 void test() {
         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)\"""",
diff --git a/test/langtools/jdk/javadoc/doclet/testLinkOption/TestLinkOption.java b/test/langtools/jdk/javadoc/doclet/testLinkOption/TestLinkOption.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2002, 2021, 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 void test() {
         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>""",
                 """
diff --git a/test/langtools/jdk/javadoc/doclet/testLinkPlatform/TestLinkPlatform.java b/test/langtools/jdk/javadoc/doclet/testLinkPlatform/TestLinkPlatform.java
