Broken external links in Javadoc artifacts in Maven Central

[lbruun]

The links from the per-module Javadoc provided in Maven Central into the centrally hosted API docs are broken.

Description of bug

External Links from the Javadoc published in Maven Central point to https://aws.amazon.com/sdkforjava/apidocs but no Javadoc lives there.

Expected Behavior

Correct link.

Current Behavior

Reason for problem:
The Maven Javadoc Plugin by default uses ${project.url} value but this value is https://aws.amazon.com/sdkforjava. The Plugin will by convention expect to find Javadoc at the subpath /apidocs of this URL.

Possible Solution

Changing the project's URL, i.e. <url>....</url> value, in all POM files may not be the way to go solely to make the Maven Javadoc Plugin happy. Perhaps an URL redirect would be the easiest solution? Meaning having the aws.amazon.com website redirect requests for https://aws.amazon.com/sdkforjava/apidocs to https://sdk.amazonaws.com/java/api/latest/.

Another option might be to set links configuration value explicitly for the Maven Javadoc Plugin.

Context

Verified as a problem on v2.15.26, but I suspect the problem exist for any version.

[debora-ito]

@lbruun thank you for reaching out. Can you show exactly where are the broken links?

[lbruun]

@debora-ito
The incorrect links are literally all over the Javadoc. I would say there are thousands of them.
Whenever there's a link to another SDK module.

In the following I show this the problem the old school way (i.e. without an IDE) and with a concrete example.

1. Download Javadoc bundle for a SDK service from Maven Central. You can use any service to showcase the problem,
   but in this example I use the ec2 service and I use the latest version as of today, v2.15.66. So the URL
   to download becomes:
   https://repo1.maven.org/maven2/software/amazon/awssdk/ec2/2.15.66/ec2-2.15.66-javadoc.jar

2. Unzip the JAR onto your harddisk and from that content open the file "index.html".

3. Now you need to find any link which points from this module (ec2) to another SDK module. All such
   links will be broken. There will by nature be many Javadoc links from the given service
   module (in this case ec2) into the SDK's core module. For example, for ec2 service, you can browse
   the interface Ec2AsyncClientBuilder which inherits from interface SdkAsyncClientBilder in core module
   but you'll notice the link is broken.
   Here is what it looks like:

[debora-ito]

Got it, thank you. I don't know where the javadoc should point to when the structure is in another module. I'll research.

[lbruun]

@debora-ito. It should point to something centrally hosted, e.g. https://sdk.amazonaws.com/java/api/latest/. My personal opinion is - as indicated under "Possible Solutions" - that it is easiest solved with a HTTP redirect implemented on the webserver. But I would guess there are many ways of solving it. How does the SDK-v1 work in this respect?