JDK-8038976 : javadoc requires a trailing / for links where java 7's javadoc didn't
  • Type: Bug
  • Component: tools
  • Sub-Component: javadoc(tool)
  • Affected Version: 8
  • Priority: P3
  • Status: Closed
  • Resolution: Fixed
  • OS: linux
  • CPU: x86_64
  • Submitted: 2014-03-31
  • Updated: 2014-07-29
  • Resolved: 2014-04-17
The Version table provides details related to the release that this issue/RFE will be addressed.

Unresolved : Release in which this issue/RFE will be addressed.
Resolved: Release in which this issue/RFE has been resolved.
Fixed : Release in which this issue/RFE has been fixed. The release containing this fix may be available for download as an Early Access Release or a General Availability Release.

To download the current JDK release, click here.
JDK 8 JDK 9
8u20Fixed 9 b10Fixed
Description
FULL PRODUCT VERSION :
java version "1.8.0"
Java(TM) SE Runtime Environment (build 1.8.0-b132)
Java HotSpot(TM) 64-Bit Server VM (build 25.0-b70, mixed mode)


ADDITIONAL OS VERSION INFORMATION :
Ubuntu Linux 13.10, x86_64

A DESCRIPTION OF THE PROBLEM :
First noticed with gradle while building the javadoc for one of my projects. From the debug file:

----
11:59:45.949 [INFO] [org.gradle.process.internal.DefaultExecHandle] Starting process 'command '/opt/sunjdk/1.8/jdk1.8.0/bin/javadoc''. Working directory: /home/fge/src/perso/largetext Command: /opt/sunjdk/1.8/jdk1.8.0/bin/javadoc @/home/fge/src/perso/largetext/build/tmp/javadoc/javadoc.options
----

The javadoc.options file contains the following:

----
-classpath '/home/fge/src/perso/largetext/build/classes/main:/home/fge/src/perso/largetext/build/resources/main:/home/fge/.gradle/caches/modules-2/files-2.1/com.google.guava/guava/16.0.1/5fa98cd1a63c99a44dd8d3b77e4762b066a5d0c5/guava-16.0.1.jar:/home/fge/.gradle/caches/modules-2/files-2.1/com.google.code.findbugs/jsr305/2.0.1/516c03b21d50a644d538de0f0369c620989cd8f0/jsr305-2.0.1.jar'
-d '/home/fge/src/perso/largetext/build/docs/javadoc'
-doctitle 'largetext 0.1-SNAPSHOT API'
-link 'http://docs.oracle.com/javase/7/docs/api'
-link 'http://jsr-305.googlecode.com/svn/trunk/javadoc'
-link 'http://docs.guava-libraries.googlecode.com/git-history/v16.0.1/javadoc'
-quiet 
-overview 'src/main/java/overview.html'
-windowtitle 'largetext 0.1-SNAPSHOT API'
'/home/fge/src/perso/largetext/src/main/java/com/github/fge/largetext/LargeTextFactory.java'
[ etc etc]
---

But the javadoc process does not find the links. From the debug file again:

----
11:59:47.959 [ERROR] [system.err] javadoc: warning - Error fetching URL: http://docs.oracle.com/javase/7/docs/api
11:59:48.217 [ERROR] [system.err] javadoc: warning - Error fetching URL: http://jsr-305.googlecode.com/svn/trunk/javadoc
11:59:48.472 [ERROR] [system.err] javadoc: warning - Error fetching URL: http://docs.guava-libraries.googlecode.com/git-history/v16.0.1/javadoc
----

The workaround is to add trailing slashes to the links, ie:

http://docs.oracle.com/javase/7/docs/api/

instead of:

http://docs.oracle.com/javase/7/docs/api

Java 7's javadoc didn't have this problem.

REGRESSION.  Last worked in version 7u51

STEPS TO FOLLOW TO REPRODUCE THE PROBLEM :
Write an options file for the javadoc tool; add in it:

----
-link 'http://docs.oracle.com/javase/7/docs/api'
----

and all other relevant options. Launch the javadoc tool with "javadoc @path/to/optionfile".

See that the command generates a warning on stderr:

warning - Error fetching URL: http://docs.oracle.com/javase/7/docs/api


EXPECTED VERSUS ACTUAL BEHAVIOR :
EXPECTED -
The javadoc is generated properly, with external links
ACTUAL -
The javadoc tool is unable to find the links

ERROR MESSAGES/STACK TRACES THAT OCCUR :
warning - Error fetching URL: http://docs.oracle.com/javase/7/docs/api
warning - Error fetching URL: http://jsr-305.googlecode.com/svn/trunk/javadoc
warning - Error fetching URL: http://docs.guava-libraries.googlecode.com/git-history/v16.0.1/javadoc


REPRODUCIBILITY :
This bug can be reproduced always.

---------- BEGIN SOURCE ----------
not relevant here
---------- END SOURCE ----------

CUSTOMER SUBMITTED WORKAROUND :
Add a trailing / to each link option, ie:

-link http://docs.oracle.com/javase/7/docs/api/

instead of:

-link http://docs.oracle.com/javase/7/docs/api


Comments
ManualVerify: Bug verified manually in promoted results for build JDK9-b10
10-07-2014

291 presumes path ends with a '/'
10-04-2014

I think 291 is ok, it is replacing the . with / and appending a / at the end only for package names such that one will get for instance: from http://blah/docs/api/ and java.awt.color we get http://......./docs/api/java/awt/color/
10-04-2014

I'm still worried by the string arithmetic at line 291.
09-04-2014

From a purist point of view, my comment re: toURL stands. From a practical point of view, I only see one usage. How about a compromise -- do the fix in toURL but make it conditional on a new boolean parameter. readPackageListFromURL(url, toURL(pkglisturl, true));
09-04-2014

your suggested fix is too late, the error occurs here: URL link = pkglisturlpath.toURI().resolve(DocPaths.PACKAGE_LIST.getPath()).toURL(); <-- Error, the concat is wrong readPackageList(link.openStream(), urlpath, false); <--- Exception in link.openStream() if toURL is too generic a place, then we could do this: readPackageListFromURL(url, toURL(adjustEndFileSeparator(pkglisturl)));
09-04-2014

Look at this string arithmetic (blech) in Extern.java, readPackageList, round about line 291 String packpath = path + packname.replace('.', '/') + '/'; Should be more like String packpath = adjustEndFileSeparator(path) + packname.replace('.', '/') + '/';
09-04-2014

That would add / to the end of ALL URLs. You should only do that when the URL is going to be resolved against. In file system terms, it's like you're proposing to put a file separator at the end of all file names e.g. myfile.txt/ . Instead, you should only do it when you want to treat the file name as a directory.
09-04-2014

Root cause: http://hg.openjdk.java.net/jdk9/dev/langtools/rev/217c265158fe Possible fix: diff --git a/src/share/classes/com/sun/tools/doclets/internal/toolkit/util/Extern.java b/src/share/classes/com/sun/tools/doclets/internal/toolkit/util/Extern.java --- a/src/share/classes/com/sun/tools/doclets/internal/toolkit/util/Extern.java +++ b/src/share/classes/com/sun/tools/doclets/internal/toolkit/util/Extern.java @@ -190,7 +190,7 @@ private URL toURL(String url) throws Fault { try { - return new URL(url); + return new URL(adjustEndFileSeparator(url)); } catch (MalformedURLException e) { throw new Fault(configuration.getText("doclet.MalformedURL", url), e); }
09-04-2014

This was introduced in jdk8-b64, and this needs to be fixed, committing this to 9, will create backport for 8u20 when the fix is pushed to 9.
09-04-2014