JDK 11's javadoc will look for element-list first, then package-list; static.javadoc.io's responses break it

[ljnelson]

JDK 11's javadoc appears to look first for an element-list file rooted at a URL supplied to it by the -link option. It does this via URL#openStream(). If that results in an IOException, then it will look for package-list. But static.javadoc.io's response doesn't trigger an IOException, so javadoc thinks that it has received a proper response. As an arbitrary example, point your browser here: https://static.javadoc.io/org.eclipse.microprofile.config/microprofile-config-api/1.3/element-list

Relevant source code: https://hg.openjdk.java.net/jdk-updates/jdk11u/file/7fa95481d1ce/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/Extern.java#l292

Because of this, -link arguments supplied to JDK 11's javadoc that point to static.javadoc.io will never work.

It would be nice if static.javadoc.io would respond in this one case with a 404 or whatever condition might be needed for javadoc 11 to function properly.

I'd submit a pull request, but it appears this repository is for issue tracking only.

Thanks for a great service!

[Atry]

Isn't 403 an IOException?

[maxcellent]

microprofile-config-api-1.3-javadoc.jar doesn't really contain element-list: http://central.maven.org/maven2/org/eclipse/microprofile/config/microprofile-config-api/1.3/microprofile-config-api-1.3-javadoc.jar

More likely this is duplicating #20

feel free to re-open if my understanding is wrong.

[ljnelson]

Nope; still present with a custom user agent.

I see from your response about a jar file not containing an element-list that perhaps you don't fully understand the issue.

The issue is that javadoc in JDK 11 will first request an element-list item, regardless of what package or project is in question. If that receives a 404 response, then it "falls back" to package-list. In static.javadoc.io's case, javadoc will never receive a 404 but an XML document. As far as javadoc (from JDK 11 forward) is concerned, this means that the element-list it has received (in this case a nonsensical XML document) contains zero packages. So all links fail.

The lack of a 404 response in this case means that javadoc will never "fall back" and ask for a package-list instead. You need to make static.javadoc.io respond with a 404 when there is no element-list present.

[ljnelson]

Note that the behavior I describe (of javadoc) is different in each version starting with JDK 9. To my knowledge, if I recall correctly, both JDK 9 and JDK 10's javadoc ask for package-list first. But JDK 11 (and perhaps JDK 12; haven't checked) begins what I assume is a trend: ask for element-list first, and if a 404 is received, fall back to package-list. The way that static.javadoc.io is set up prevents the tool from working properly for non-modular projects.

[Vampire]

I can second this, with Java 11 it is not workable, with Java 10 it works due to the described reason. Requesting element-list responds with 403 and an XML file and it does not work further on.

[Vampire]

And it is not the user-agent topic, Java 10 and Java 11 default user agents are not (yet) blocked by Cloudflare.

[onacit]

I believe I'm facing this problem.

Here comes the result with the -X option.

[DEBUG] Could not follow https://static.javadoc.io/org.mockito/mockito-core/2.27.0.
    Reason: Unexpected HTTP status code 403 getting resource
        https://static.javadoc.io/org.mockito/mockito-core/2.27.0.
[DEBUG] Could not follow https://static.javadoc.io/org.mockito/junit-jupiter/2.27.0.
    Reason: Unexpected HTTP status code 403 getting resource
        https://static.javadoc.io/org.mockito/junit-jupiter/2.27.0.

$ mvn -version
Apache Maven 3.6.1 (d66c9c0b3152b2e69ee9bac180bb8fcc8e6af555; 2019-04-05T04:00:29+09:00)
Maven home: /usr/local/Cellar/maven/3.6.1/libexec
Java version: 1.8.0_211, vendor: Oracle Corporation, runtime: /Library/Java/JavaVirtualMachines/jdk1.8.0_211.jdk/Contents/Home/jre
Default locale: en_KR, platform encoding: UTF-8
OS name: "mac os x", version: "10.14.4", arch: "x86_64", family: "mac"

I yet don't understand why javadoc tries to getting the resource of / not /package-list.

[ljnelson]

Hi, @maxcellent; I don't have the ability to re-open this bug, but as I hope you can see it needs to be addressed. Could you kindly re-open it?

[Vampire]

@onacit as you use Java 8, you are not facing this issue, as it does not happen with Java 8 or 9 or 10.