This is an automated email from the ASF dual-hosted git repository. kwin pushed a commit to branch bugfix/javadoc-module-names-for-binary-names-3.x in repository https://gitbox.apache.org/repos/asf/maven-plugin-tools.git
commit 6330c56b74e52c51d8bc7e8d956af42cc6b78fc8 Author: Konrad Windszus <[email protected]> AuthorDate: Mon Dec 15 20:47:38 2025 +0100 JavadocLinkGenerator.createLink(String) must consider module names When link towards external javadoc with modules generated include the module name in the URL path This closes #1038 --- .../tools/plugin/javadoc/JavadocLinkGenerator.java | 6 ++--- .../maven/tools/plugin/javadoc/JavadocSite.java | 29 +++++++++++++++++++--- .../tools/plugin/javadoc/JavadocNonLtsSiteIT.java | 7 ++++++ .../maven/tools/plugin/javadoc/JavadocSiteIT.java | 16 +++++++++--- .../tools/plugin/javadoc/JavadocSiteTest.java | 14 ++++++++++- 5 files changed, 60 insertions(+), 12 deletions(-) diff --git a/maven-plugin-tools-api/src/main/java/org/apache/maven/tools/plugin/javadoc/JavadocLinkGenerator.java b/maven-plugin-tools-api/src/main/java/org/apache/maven/tools/plugin/javadoc/JavadocLinkGenerator.java index dd0c2243..badaf5dc 100644 --- a/maven-plugin-tools-api/src/main/java/org/apache/maven/tools/plugin/javadoc/JavadocLinkGenerator.java +++ b/maven-plugin-tools-api/src/main/java/org/apache/maven/tools/plugin/javadoc/JavadocLinkGenerator.java @@ -112,7 +112,7 @@ public class JavadocLinkGenerator { // resolve version JavaVersion javadocVersion = JavaVersion.parse(internalJavadocVersion); internalJavadocSite = - new JavadocSite(internalJavadocSiteUrl, JavadocToolVersionRange.findMatch(javadocVersion), false); + new JavadocSite(internalJavadocSiteUrl, JavadocToolVersionRange.findMatch(javadocVersion)); } else { internalJavadocSite = null; } @@ -140,7 +140,7 @@ public class JavadocLinkGenerator { * Only uses the offline site for references returning {@code false} for * {@link FullyQualifiedJavadocReference#isExternal()}. * @param javadocReference - * @return the (deep-) link towards a javadoc page + * @return the (deep-)link to a javadoc page * @throws IllegalArgumentException in case no javadoc link could be generated for the given reference * @throws IllegalStateException in case no javadoc source sites have been configured */ @@ -163,7 +163,7 @@ public class JavadocLinkGenerator { * Preferably resolves from the online sites if they provide the given package. * @param binaryName a binary name according to * <a href="https://docs.oracle.com/javase/specs/jls/se8/html/jls-13.html#jls-13.1";>JLS 13.1</a> - * @return the (deep-) link towards a javadoc page + * @return the (deep-)link to a javadoc page * @throws IllegalArgumentException in case no javadoc link could be generated for the given name */ public URI createLink(String binaryName) { diff --git a/maven-plugin-tools-api/src/main/java/org/apache/maven/tools/plugin/javadoc/JavadocSite.java b/maven-plugin-tools-api/src/main/java/org/apache/maven/tools/plugin/javadoc/JavadocSite.java index 36670126..d40fff74 100644 --- a/maven-plugin-tools-api/src/main/java/org/apache/maven/tools/plugin/javadoc/JavadocSite.java +++ b/maven-plugin-tools-api/src/main/java/org/apache/maven/tools/plugin/javadoc/JavadocSite.java @@ -158,16 +158,31 @@ class JavadocSite { this.requireModuleNameInPath = requireModuleNameInPath; } - /** Constructor for offline sites. This throws {@link UnsupportedOperationException} + /** Constructor for offline sites without modules. This throws {@link UnsupportedOperationException} * for {@link #hasEntryFor(Optional, Optional)}. */ - JavadocSite(final URI url, JavadocLinkGenerator.JavadocToolVersionRange version, boolean requireModuleNameInPath) { + JavadocSite(final URI url, JavadocLinkGenerator.JavadocToolVersionRange version) { Objects.requireNonNull(url); this.baseUri = url; Objects.requireNonNull(version); this.version = version; this.settings = null; this.containedPackageNamesAndModules = Collections.emptyMap(); - this.requireModuleNameInPath = requireModuleNameInPath; + this.requireModuleNameInPath = false; + } + + /** Constructor for offline sites with modules. This throws {@link UnsupportedOperationException} + * for {@link #hasEntryFor(Optional, Optional)}. */ + JavadocSite( + final URI url, + JavadocLinkGenerator.JavadocToolVersionRange version, + Map<String, String> containedPackageNamesAndModules) { + Objects.requireNonNull(url); + this.baseUri = url; + Objects.requireNonNull(version); + this.version = version; + this.settings = null; + this.containedPackageNamesAndModules = containedPackageNamesAndModules; + this.requireModuleNameInPath = true; } static Map<String, String> getPackageListWithModules(final URI url, final Settings settings) throws IOException { @@ -236,7 +251,13 @@ class JavadocSite { // url must point to simple class className = className.substring(0, className.length() - 2); } - return createLink(baseUri, Optional.empty(), Optional.of(packageName), Optional.of(className)); + Optional<String> moduleName; + if (!requireModuleNameInPath) { + moduleName = Optional.empty(); + } else { + moduleName = Optional.ofNullable(containedPackageNamesAndModules.get(packageName)); + } + return createLink(baseUri, moduleName, Optional.of(packageName), Optional.of(className)); } catch (URISyntaxException e) { throw new IllegalArgumentException("Could not create link for " + packageName + "." + className, e); } diff --git a/maven-plugin-tools-api/src/test/java/org/apache/maven/tools/plugin/javadoc/JavadocNonLtsSiteIT.java b/maven-plugin-tools-api/src/test/java/org/apache/maven/tools/plugin/javadoc/JavadocNonLtsSiteIT.java index 424bea5c..e1fc2579 100644 --- a/maven-plugin-tools-api/src/test/java/org/apache/maven/tools/plugin/javadoc/JavadocNonLtsSiteIT.java +++ b/maven-plugin-tools-api/src/test/java/org/apache/maven/tools/plugin/javadoc/JavadocNonLtsSiteIT.java @@ -72,4 +72,11 @@ class JavadocNonLtsSiteIT extends JavadocSiteIT { void nestedClass(URI javadocBaseUrl) throws Exception { super.nestedClass(javadocBaseUrl); } + + @Override + @ParameterizedTest + @MethodSource("javadocBaseUrls") + void clazz(URI javadocBaseUrl) throws Exception { + super.clazz(javadocBaseUrl); + } } diff --git a/maven-plugin-tools-api/src/test/java/org/apache/maven/tools/plugin/javadoc/JavadocSiteIT.java b/maven-plugin-tools-api/src/test/java/org/apache/maven/tools/plugin/javadoc/JavadocSiteIT.java index dd603115..4d9ba32b 100644 --- a/maven-plugin-tools-api/src/test/java/org/apache/maven/tools/plugin/javadoc/JavadocSiteIT.java +++ b/maven-plugin-tools-api/src/test/java/org/apache/maven/tools/plugin/javadoc/JavadocSiteIT.java @@ -21,6 +21,7 @@ package org.apache.maven.tools.plugin.javadoc; import java.net.URI; import java.util.stream.Stream; +import org.apache.maven.settings.Settings; import org.apache.maven.tools.plugin.javadoc.FullyQualifiedJavadocReference.MemberType; import org.junit.jupiter.params.ParameterizedTest; import org.junit.jupiter.params.provider.Arguments; @@ -39,7 +40,7 @@ class JavadocSiteIT { @ParameterizedTest @MethodSource("javadocBaseUrls") void constructors(URI javadocBaseUrl) throws Exception { - JavadocSite site = new JavadocSite(javadocBaseUrl, null); + JavadocSite site = new JavadocSite(javadocBaseUrl, (Settings) null); JavadocSiteTest.assertUrlValid(site.createLink(new FullyQualifiedJavadocReference( "java.lang", "String", "String(byte[],int)", MemberType.CONSTRUCTOR, true))); } @@ -47,7 +48,7 @@ class JavadocSiteIT { @ParameterizedTest @MethodSource("javadocBaseUrls") void methods(URI javadocBaseUrl) throws Exception { - JavadocSite site = new JavadocSite(javadocBaseUrl, null); + JavadocSite site = new JavadocSite(javadocBaseUrl, (Settings) null); JavadocSiteTest.assertUrlValid(site.createLink(new FullyQualifiedJavadocReference( "java.lang", "String", "copyValueOf(char[],int,int)", MemberType.METHOD, true))); } @@ -55,7 +56,7 @@ class JavadocSiteIT { @ParameterizedTest @MethodSource("javadocBaseUrls") void fields(URI javadocBaseUrl) throws Exception { - JavadocSite site = new JavadocSite(javadocBaseUrl, null); + JavadocSite site = new JavadocSite(javadocBaseUrl, (Settings) null); JavadocSiteTest.assertUrlValid(site.createLink(new FullyQualifiedJavadocReference( "java.lang", "String", "CASE_INSENSITIVE_ORDER", MemberType.FIELD, true))); } @@ -63,8 +64,15 @@ class JavadocSiteIT { @ParameterizedTest @MethodSource("javadocBaseUrls") void nestedClass(URI javadocBaseUrl) throws Exception { - JavadocSite site = new JavadocSite(javadocBaseUrl, null); + JavadocSite site = new JavadocSite(javadocBaseUrl, (Settings) null); JavadocSiteTest.assertUrlValid( site.createLink(new FullyQualifiedJavadocReference("java.util", "Map.Entry", true))); } + + @ParameterizedTest + @MethodSource("javadocBaseUrls") + void clazz(URI javadocBaseUrl) throws Exception { + JavadocSite site = new JavadocSite(javadocBaseUrl, (Settings) null); + JavadocSiteTest.assertUrlValid(site.createLink("java.lang", "String")); + } } diff --git a/maven-plugin-tools-api/src/test/java/org/apache/maven/tools/plugin/javadoc/JavadocSiteTest.java b/maven-plugin-tools-api/src/test/java/org/apache/maven/tools/plugin/javadoc/JavadocSiteTest.java index df37c599..05c5cd9e 100644 --- a/maven-plugin-tools-api/src/test/java/org/apache/maven/tools/plugin/javadoc/JavadocSiteTest.java +++ b/maven-plugin-tools-api/src/test/java/org/apache/maven/tools/plugin/javadoc/JavadocSiteTest.java @@ -23,6 +23,7 @@ import java.io.IOException; import java.net.URI; import java.net.URISyntaxException; import java.util.AbstractMap; +import java.util.Collections; import java.util.Map; import java.util.regex.Pattern; import java.util.stream.Stream; @@ -110,6 +111,17 @@ class JavadocSiteTest { "org.apache.maven.tools.plugin.extractor.annotations.converter.test", "CurrentClass", false))); } + @Test + void classLinkFromPackageAndClassNameWithExternalJavadocRequiringModules() throws URISyntaxException, IOException { + URI baseUri = new URI("https://docs.oracle.com/en/java/javase/11/docs/api/";); + JavadocSite site = new JavadocSite( + baseUri, + JavadocLinkGenerator.JavadocToolVersionRange.JDK10_OR_HIGHER, + Collections.singletonMap("java.lang", "java.base")); + // don't request URL to make test independent of network connectivity + assertEquals(baseUri.resolve("java.base/java/lang/String.html"), site.createLink("java.lang", "String")); + } + @Test void getPackageAndClassName() { assertEquals( @@ -137,7 +149,7 @@ class JavadocSiteTest { throws URISyntaxException { URI javadocBaseUri = JavadocSiteTest.class.getResource("/javadoc/" + name + "/").toURI(); - return new JavadocSite(javadocBaseUri, version, false); + return new JavadocSite(javadocBaseUri, version); } static void assertUrlValid(final URI url) {
