Skip to content

Commit

Permalink
8297437: javadoc cannot link to old docs (with old style anchors)
Browse files Browse the repository at this point in the history
Reviewed-by: hannesw
  • Loading branch information
Roman Marchenko authored and hns committed Jan 26, 2023
1 parent b0376a5 commit 15a1488
Show file tree
Hide file tree
Showing 6 changed files with 144 additions and 40 deletions.
@@ -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
Expand Down Expand Up @@ -103,6 +103,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
Expand All @@ -113,10 +118,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;
}

/**
Expand Down Expand Up @@ -186,7 +192,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);
}

/**
Expand Down Expand Up @@ -256,7 +262,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);
Expand All @@ -267,6 +273,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
Expand Down Expand Up @@ -419,7 +437,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);
Expand All @@ -438,7 +456,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);
Expand All @@ -462,27 +480,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);
}
Expand All @@ -502,7 +520,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;
Expand All @@ -515,7 +534,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('.', '/'));
Expand All @@ -533,7 +552,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
showDiagnostic = false;
Expand Down Expand Up @@ -662,4 +681,65 @@ private void printModularityMismatchDiagnostic(String key, Object arg) {
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();
}
}
@@ -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
Expand Down Expand Up @@ -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\
Expand Down Expand Up @@ -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\
Expand Down
@@ -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
Expand Down Expand Up @@ -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>"""
);
Expand Down
4 changes: 2 additions & 2 deletions 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
Expand Down Expand Up @@ -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)\"""",
Expand Down
@@ -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
Expand Down Expand Up @@ -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>""",
"""
Expand Down

1 comment on commit 15a1488

@openjdk-notifier
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please sign in to comment.