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

Fri Jun 7 12:16:28 UTC 2024

On 2024-06-07 01:11, Jonathan Gibbons wrote:
> 
> 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,

this indeed worked. Thank you very much. I am certain that if 
docs.oracle.com would not misbehave it would work as expected and not 
wasted our time :-(. Hope you can fix that soon.

A similar issue I need to address in upcoming Maven Javadoc Plugin:
https://issues.apache.org/jira/browse/MJAVADOC-656

Best regards,

Michael