This is an automated email from the ASF dual-hosted git repository. kwin pushed a commit to branch bugfix/javadoc-url-for-package-and-classname-with-modules in repository https://gitbox.apache.org/repos/asf/maven-plugin-tools.git
commit ea37e1c4210c8d80af6d8147a2b46250fd949df4 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 | 28 ++++++++++++++++++---- .../maven/tools/plugin/javadoc/JavadocSiteIT.java | 17 +++++++++---- .../tools/plugin/javadoc/JavadocSiteTest.java | 12 +++++++++- 4 files changed, 51 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..4952e1ca 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,29 @@ 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 +249,14 @@ 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/JavadocSiteIT.java b/maven-plugin-tools-api/src/test/java/org/apache/maven/tools/plugin/javadoc/JavadocSiteIT.java index 115bb982..d06794cc 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 @@ -22,6 +22,7 @@ import java.io.IOException; 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; @@ -40,7 +41,7 @@ class JavadocSiteIT { @ParameterizedTest @MethodSource("javadocBaseUrls") void testConstructors(URI javadocBaseUrl) throws IOException { - 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))); } @@ -48,7 +49,7 @@ class JavadocSiteIT { @ParameterizedTest @MethodSource("javadocBaseUrls") void testMethods(URI javadocBaseUrl) throws IOException { - 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))); } @@ -56,7 +57,7 @@ class JavadocSiteIT { @ParameterizedTest @MethodSource("javadocBaseUrls") void testFields(URI javadocBaseUrl) throws IOException { - 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))); } @@ -64,8 +65,16 @@ class JavadocSiteIT { @ParameterizedTest @MethodSource("javadocBaseUrls") void testNestedClass(URI javadocBaseUrl) throws IOException { - 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 testClass(URI javadocBaseUrl) throws IOException { + 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 4355fb82..96030754 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; @@ -115,6 +116,15 @@ class JavadocSiteTest { "org.apache.maven.tools.plugin.extractor.annotations.converter.test", "CurrentClass", false))); } + @Test + void testClassLinkFromPackageAndClassNameWithExternalJavadocRequiringModules() + 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 testGetPackageAndClassName() { assertEquals( @@ -142,7 +152,7 @@ class JavadocSiteTest { throws IOException, 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) {
