[External] : Re: Missing element-list for https://docs.oracle.com/javase/8/docs/jre/api/security/jgss/spec

Thu Jun 6 23:11:56 UTC 2024

On 6/5/24 2:51 AM, Osipov, Michael wrote:
> On 2024-05-31 21:38, Jonathan Gibbons wrote:
>> Michael,
>>
>> There is no `element-list` file for any version of JDK before JDK 9.
>> Before JDK 9, the appropriate information was in the `package-list`
>> file. In JDK 9, with the introduction of modules, the format of the file
>> was updated to include modules, and because this was an incompatible
>> change, the file was renamed as well, to `element-list`.
>>
>> It is an annoying misconfiguration of `docs.oracle.com` that you are
>> seeing `302 Moved Temporarily` instead of `404 Not Found` which would be
>> a more semantically accurate response.
>>
>> That leaves the question of why whatever you were doing was looking for
>> `element-list` in JDK 8. To answer that, we need more info, to determine
>> whether it is just a command-line error on your part, or any error in
>> the `javadoc` tool itself. What version of JDK and javadoc are you
>> using; what external libraries were you referencing in `-link` or `-
>> linkoffline` options; and what source level were you using, with either
>> the `-source` or `--release` options?
> John,
>
> thanks for the elaboration. Let me better clarify what happens.
>
> The code is question with a modification for you is available at:
> https://urldefense.com/v3/__https://github.com/michael-o/tomcatspnegoad/tree/javadoc-issue__;!!ACWV5N9M2RV99hQ!L6MibNz6g0M99jnVOo2O_Zs2vP8-4CM-NS4WNUmHmL5dB30i0qaSfDJBHW4S_bxjOhImERJfBWGpStJ6WrwE0WAva10xtV86PQ$  
>
> Class net.sf.michaelo.tomcat.pac.asn1.AdIfRelevantAsn1Parser uses
> com.sun.security.jgss.AuthorizationDataEntry and others use private Sun
> classes which does not allow me to use -release for now, only -source.
> The source is Java 8. When I run javadoc:javadoc with Zulu 8 all links
> are generated successfully. Running Zulu 11 with extracted Javadoc call
> (&"C:\Program Files\Zulu\zulu-11\bin\javadoc.exe" -verbose "@options"
> "@packages") gives me no warning, even in verbose mode. It simply does
> not link.
> When trying Temurin 22.0.1 (&"C:\Temp\jdk-22.0.1+8\bin\javadoc.exe"
> -verbose "@options" "@packages") it gives me:
>> Warnung: URLhttps://docs.oracle.com/javase/8/docs/jre/api/security/jgss/spec/element-list  wurde umgeleitet anhttps://docs.oracle.com/en/java/javase/22/  - Aktualisieren Sie die Befehlszeilenoptionen, um diese Warnung zu unterdrücken.
> That is the redirect. Either I am misunderstanding or I have hit an edge
> case for public classes outside of the standard JDK (Java namespaces).
> Here is the input to Javadoc (@options, @packages) if you cannot try
> yourself:https://urldefense.com/v3/__https://gist.github.com/michael-o/212c6797b000914b9142f1f077b1d9df__;!!ACWV5N9M2RV99hQ!L6MibNz6g0M99jnVOo2O_Zs2vP8-4CM-NS4WNUmHmL5dB30i0qaSfDJBHW4S_bxjOhImERJfBWGpStJ6WrwE0WAva12c46QzhA$  
>
> I have tried:
>> Apache Maven 3.8.8 (4c87b05d9aedce574290d1acc98575ed5eb6cd39)
>> Maven home: C:\Entwicklung\Programme\apache-maven-3.8.8
>> Java version: 11.0.18, vendor: Azul Systems, Inc., runtime: C:\Program Files\Zulu\zulu-11
>> Default locale: de_DE, platform encoding: UTF-8
>> OS name: "windows 10", version: "10.0", arch: "amd64", family: "windows"
>> Apache Maven 3.8.8 (4c87b05d9aedce574290d1acc98575ed5eb6cd39)
>> Maven home: C:\Entwicklung\Programme\apache-maven-3.8.8
>> Java version: 1.8.0_362, vendor: Azul Systems, Inc., runtime: C:\Program Files\Zulu\zulu-8\jre
>> Default locale: de_DE, platform encoding: Cp1252
>> OS name: "windows 10", version: "10.0", arch: "amd64", family: "windows"
>> Apache Maven 3.8.8 (4c87b05d9aedce574290d1acc98575ed5eb6cd39)
>> Maven home: C:\Entwicklung\Programme\apache-maven-3.8.8
>> Java version: 22.0.1, vendor: Eclipse Adoptium, runtime: C:\Temp\jdk-22.0.1+8
>> Default locale: de_DE, platform encoding: UTF-8
>> OS name: "windows 10", version: "10.0", arch: "amd64", family: "windows"
> Note: I have routed the Javadoc traffic through Fiddler and it clearly
> following the misconfigured docs.oracle.com location:
>> #	Result	Protocol	Host	URL	Body	Caching	Content-Type	Process	Comments	Custom	
>> 10	302	HTTPS	docs.oracle.com	/javase/8/docs/jre/api/security/jgss/spec/element-list	1			javadoc:24660			
>> #	Result	Protocol	Host	URL	Body	Caching	Content-Type	Process	Comments	Custom	
>> 12	200	HTTPS	docs.oracle.com	/en/java/javase/22/	33 431	max-age=19052	text/html	javadoc:24660			
>
> Regards,
>
> Michael
>
>

Michael,

I investigated a bit further, and I may have a solution for you.

The redirect is annoying, and sad to say, there is nothing I can do to 
get it fixed in a timely manner.  But, I think you may be able to work 
around it.  The answer is based on the content of the files in the gist 
that you referenced in your message.

Look at these lines:

-link
'https://docs.oracle.com/javase/8/docs/jre/api/security/jgss/spec'
-linkoffline
'https://docs.oracle.com/javase/8/docs/api' 
'C:/Entwicklung/workspace-2023-06/tomcatspnegoad/tomcat90/target/javadoc-bundle-options' 

I'm not sure what is in your `javadoc-bundle-options` file, but it 
*ought* to be a local copy of the `package-list` found here:
https://docs.oracle.com/javase/8/docs/api/package-list

For the first option, the `-link` one, try changing it to:

-linkoffline
'https://docs.oracle.com/javase/8/docs/jre/api/security/jgss/spec' 
/path/to/file

where `/path/to/file` is a local copy of the file found here:
https://docs.oracle.com/javase/8/docs/jre/api/security/jgss/spec/package-list

which in reality is just:

com.sun.security.jgss

In other words, both options should be instances of the `-linkoffline` 
option, which should be of the form:

-linkofflinehttps:/url/to/api   /path/to/file

where `/path/to/file` is a local copy of the file downloaded from 
`https:/url/to/api/package-list`

Note I am using `.../package-list` in this message because you are using 
`-source 8`.  If you use a newer version of these APIs, you may need to 
change `package-list` to `element-list`. (I believe the change happened 
in JDK 11.)

For more details on the `-linkoffline` option, see
https://docs.oracle.com/en/java/javase/22/docs/specs/man/javadoc.html#option-linkoffline

-- Jon
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.org/pipermail/security-dev/attachments/20240606/d397e3b5/attachment.htm>