You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@maven.apache.org by kw...@apache.org on 2022/10/24 14:33:07 UTC
[maven-plugin-tools] 01/01: [MPLUGIN-429] Don't emit warning for missing javadoc URI if no javadoc sources are configured
This is an automated email from the ASF dual-hosted git repository.
kwin pushed a commit to branch bugfix/no-warning-for-javadoc-url-when-sites-not-configured
in repository https://gitbox.apache.org/repos/asf/maven-plugin-tools.git
commit 75246fc49d64107132b2139f94b0b70a1045b05a
Author: Konrad Windszus <kw...@apache.org>
AuthorDate: Mon Oct 24 16:32:59 2022 +0200
[MPLUGIN-429] Don't emit warning for missing javadoc URI if no javadoc
sources are configured
---
.../JavaAnnotationsMojoDescriptorExtractor.java | 17 +++++--
.../annotations/converter/ConverterContext.java | 13 ++++++
.../converter/JavaClassConverterContext.java | 13 +++++-
.../annotations/converter/tag/LinkUtils.java | 54 +++++++++++++---------
.../converter/SimpleConverterContext.java | 6 +++
.../annotations/converter/tag/LinkUtilsTest.java | 3 +-
.../tools/plugin/javadoc/JavadocLinkGenerator.java | 6 +++
.../plugin/javadoc/JavadocLinkGeneratorTest.java | 8 ++--
.../generator/PluginDescriptorFilesGenerator.java | 40 ++++++++++------
9 files changed, 112 insertions(+), 48 deletions(-)
diff --git a/maven-plugin-tools-annotations/src/main/java/org/apache/maven/tools/plugin/extractor/annotations/JavaAnnotationsMojoDescriptorExtractor.java b/maven-plugin-tools-annotations/src/main/java/org/apache/maven/tools/plugin/extractor/annotations/JavaAnnotationsMojoDescriptorExtractor.java
index c2d839ca..d3704293 100644
--- a/maven-plugin-tools-annotations/src/main/java/org/apache/maven/tools/plugin/extractor/annotations/JavaAnnotationsMojoDescriptorExtractor.java
+++ b/maven-plugin-tools-annotations/src/main/java/org/apache/maven/tools/plugin/extractor/annotations/JavaAnnotationsMojoDescriptorExtractor.java
@@ -143,11 +143,20 @@ public class JavaAnnotationsMojoDescriptorExtractor
JavaProjectBuilder builder = scanJavadoc( request, mojoAnnotatedClasses.values() );
Map<String, JavaClass> javaClassesMap = discoverClasses( builder );
+ final JavadocLinkGenerator linkGenerator;
+ if ( request.getInternalJavadocBaseUrl() != null || ( request.getExternalJavadocBaseUrls() != null
+ && !request.getExternalJavadocBaseUrls().isEmpty() ) )
+ {
+ linkGenerator = new JavadocLinkGenerator( request.getInternalJavadocBaseUrl(),
+ request.getInternalJavadocVersion(),
+ request.getExternalJavadocBaseUrls(),
+ request.getSettings() );
+ }
+ else
+ {
+ linkGenerator = null;
+ }
- JavadocLinkGenerator linkGenerator = new JavadocLinkGenerator( request.getInternalJavadocBaseUrl(),
- request.getInternalJavadocVersion(),
- request.getExternalJavadocBaseUrls(),
- request.getSettings() );
populateDataFromJavadoc( builder, mojoAnnotatedClasses, javaClassesMap, linkGenerator );
return toMojoDescriptors( mojoAnnotatedClasses, request.getPluginDescriptor() );
diff --git a/maven-plugin-tools-annotations/src/main/java/org/apache/maven/tools/plugin/extractor/annotations/converter/ConverterContext.java b/maven-plugin-tools-annotations/src/main/java/org/apache/maven/tools/plugin/extractor/annotations/converter/ConverterContext.java
index 55155af4..f564c1f8 100644
--- a/maven-plugin-tools-annotations/src/main/java/org/apache/maven/tools/plugin/extractor/annotations/converter/ConverterContext.java
+++ b/maven-plugin-tools-annotations/src/main/java/org/apache/maven/tools/plugin/extractor/annotations/converter/ConverterContext.java
@@ -70,11 +70,20 @@ public interface ConverterContext
*/
FullyQualifiedJavadocReference resolveReference( JavadocReference reference );
+ /**
+ *
+ * @return {@code true} if links to javadoc pages could potentially be generated with
+ * {@link #getUrl(FullyQualifiedJavadocReference))
+ */
+ boolean canCreateUrl();
+
/**
* Returns a (deep-)link to the javadoc page for the given reference
* @param reference the reference for which to get the url
* @return the link
* @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
+ * (i.e. {@link #canCreateUrl()} returns {@code false})
*/
URI getUrl( FullyQualifiedJavadocReference reference );
@@ -86,6 +95,10 @@ public interface ConverterContext
*/
String getStaticFieldValue( FullyQualifiedJavadocReference reference );
+ /**
+ * Returns the base url to use for internal javadoc links
+ * @return the base url for internal javadoc links (may be {@code null}).
+ */
URI getInternalJavadocSiteBaseUrl();
/**
diff --git a/maven-plugin-tools-annotations/src/main/java/org/apache/maven/tools/plugin/extractor/annotations/converter/JavaClassConverterContext.java b/maven-plugin-tools-annotations/src/main/java/org/apache/maven/tools/plugin/extractor/annotations/converter/JavaClassConverterContext.java
index d53bf5f9..efdb8d4c 100644
--- a/maven-plugin-tools-annotations/src/main/java/org/apache/maven/tools/plugin/extractor/annotations/converter/JavaClassConverterContext.java
+++ b/maven-plugin-tools-annotations/src/main/java/org/apache/maven/tools/plugin/extractor/annotations/converter/JavaClassConverterContext.java
@@ -61,7 +61,7 @@ public class JavaClassConverterContext
final Map<String, MojoAnnotatedClass> mojoAnnotatedClasses;
- final JavadocLinkGenerator linkGenerator;
+ final JavadocLinkGenerator linkGenerator; // may be null in case nothing was configured
final int lineNumber;
@@ -168,6 +168,13 @@ public class JavaClassConverterContext
&& javaClass.getSimpleName().equals( reference.getClassName().orElse( "" ) );
}
+
+ @Override
+ public boolean canCreateUrl()
+ {
+ return linkGenerator != null;
+ }
+
@Override
public URI getUrl( FullyQualifiedJavadocReference reference )
{
@@ -196,6 +203,10 @@ public class JavaClassConverterContext
{
throw new IllegalStateException( "Error constructing a valid URL", e ); // should not happen
}
+ if ( linkGenerator == null )
+ {
+ throw new IllegalStateException( "No Javadoc Sites given to create URLs to" );
+ }
return linkGenerator.createLink( reference );
}
diff --git a/maven-plugin-tools-annotations/src/main/java/org/apache/maven/tools/plugin/extractor/annotations/converter/tag/LinkUtils.java b/maven-plugin-tools-annotations/src/main/java/org/apache/maven/tools/plugin/extractor/annotations/converter/tag/LinkUtils.java
index d9ed3bfa..707ecf2f 100644
--- a/maven-plugin-tools-annotations/src/main/java/org/apache/maven/tools/plugin/extractor/annotations/converter/tag/LinkUtils.java
+++ b/maven-plugin-tools-annotations/src/main/java/org/apache/maven/tools/plugin/extractor/annotations/converter/tag/LinkUtils.java
@@ -49,45 +49,55 @@ public class LinkUtils
public static String createLink( String referenceValue, ConverterContext context,
UnaryOperator<String> labelDecorator )
{
- StringBuilder link = new StringBuilder();
try
{
JavadocReference reference = JavadocReference.parse( referenceValue );
FullyQualifiedJavadocReference fqReference = context.resolveReference( reference );
- try
- {
- link.append( "<a href=\"" );
- link.append( context.getUrl( fqReference ).toString() );
- link.append( "\">" );
- String label = getReferenceLabel( fqReference, context );
- label = labelDecorator.apply( label );
- link.append( label );
- link.append( "</a>" );
- }
- catch ( IllegalArgumentException e )
+ if ( !context.canCreateUrl() )
{
- LOG.warn( "Could not get javadoc URL for reference {} at {} (fully qualified {}): {}", referenceValue,
- fqReference, context.getLocation(), e.getMessage() );
- String label = getReferenceLabel( fqReference, context );
- link.setLength( 0 );
- link.append( labelDecorator.apply( label ) );
- link.append( "<!-- this link does not have javadoc linked -->" );
+ return getReferenceLabel( fqReference, context, labelDecorator, "no javadoc sites associated" );
}
+ return createLink( referenceValue, fqReference, context, labelDecorator );
}
catch ( IllegalArgumentException e )
{
LOG.warn( "Unresolvable link in javadoc tag with value {} found in {}: {}", referenceValue,
context.getLocation(), e.getMessage() );
- String label = referenceValue;
+ return labelDecorator.apply( referenceValue ) + "<!-- this link could not be resolved -->";
+ }
+ }
+
+ private static String createLink( String referenceValue, FullyQualifiedJavadocReference fqReference,
+ ConverterContext context, UnaryOperator<String> labelDecorator )
+ {
+ StringBuilder link = new StringBuilder();
+ try
+ {
+ link.append( "<a href=\"" );
+ link.append( context.getUrl( fqReference ).toString() );
+ link.append( "\">" );
+ String label = getReferenceLabel( fqReference, context );
label = labelDecorator.apply( label );
- link.setLength( 0 );
link.append( label );
- link.append( "<!-- this link could not be resolved -->" );
+ link.append( "</a>" );
+ }
+ catch ( IllegalArgumentException e )
+ {
+ LOG.warn( "Could not get javadoc URL for reference {} at {} (fully qualified {}): {}", referenceValue,
+ fqReference, context.getLocation(), e.getMessage() );
+ return getReferenceLabel( fqReference, context, labelDecorator,
+ "reference not found in associated javadoc sites" );
}
-
return link.toString();
}
+ private static String getReferenceLabel( FullyQualifiedJavadocReference fqReference, ConverterContext context,
+ UnaryOperator<String> labelDecorator, String htmlComment )
+ {
+ String label = getReferenceLabel( fqReference, context );
+ return labelDecorator.apply( label ) + "<!-- " + htmlComment + " -->";
+ }
+
/**
* @return the undecorated label of the link
* @see <a href="https://docs.oracle.com/javase/8/docs/technotes/tools/windows/javadoc.html#JSWOR656"> javadoc: How
diff --git a/maven-plugin-tools-annotations/src/test/java/org/apache/maven/tools/plugin/extractor/annotations/converter/SimpleConverterContext.java b/maven-plugin-tools-annotations/src/test/java/org/apache/maven/tools/plugin/extractor/annotations/converter/SimpleConverterContext.java
index 68d7c1eb..6c0dafe2 100644
--- a/maven-plugin-tools-annotations/src/test/java/org/apache/maven/tools/plugin/extractor/annotations/converter/SimpleConverterContext.java
+++ b/maven-plugin-tools-annotations/src/test/java/org/apache/maven/tools/plugin/extractor/annotations/converter/SimpleConverterContext.java
@@ -213,4 +213,10 @@ public class SimpleConverterContext
{
return (T) attributes.getOrDefault( name, defaultValue );
}
+
+ @Override
+ public boolean canCreateUrl()
+ {
+ return true;
+ }
}
\ No newline at end of file
diff --git a/maven-plugin-tools-annotations/src/test/java/org/apache/maven/tools/plugin/extractor/annotations/converter/tag/LinkUtilsTest.java b/maven-plugin-tools-annotations/src/test/java/org/apache/maven/tools/plugin/extractor/annotations/converter/tag/LinkUtilsTest.java
index 157b0af1..981bdfb8 100644
--- a/maven-plugin-tools-annotations/src/test/java/org/apache/maven/tools/plugin/extractor/annotations/converter/tag/LinkUtilsTest.java
+++ b/maven-plugin-tools-annotations/src/test/java/org/apache/maven/tools/plugin/extractor/annotations/converter/tag/LinkUtilsTest.java
@@ -23,7 +23,6 @@ import java.net.URI;
import org.apache.maven.tools.plugin.extractor.annotations.converter.ConverterContext;
import org.apache.maven.tools.plugin.extractor.annotations.converter.SimpleConverterContext;
-import org.apache.maven.tools.plugin.extractor.annotations.converter.tag.LinkUtils;
import org.apache.maven.tools.plugin.javadoc.JavadocReference;
import org.junit.jupiter.api.Test;
@@ -44,7 +43,7 @@ class LinkUtilsTest
void testCreateLinkWithNoJavadoc()
{
ConverterContext context = new SimpleConverterContext( "myPackage", ( ref ) -> { throw new IllegalArgumentException("Could not get javadoc"); } );
- assertEquals( "NoJavadoc<!-- this link does not have javadoc linked -->",
+ assertEquals( "NoJavadoc<!-- reference not found in associated javadoc sites -->",
LinkUtils.createLink( "NoJavadoc", context ) );
}
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 54f677bd..fa4cedef 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
@@ -148,6 +148,11 @@ public class JavadocLinkGenerator
{
externalJavadocSites = Collections.emptyList();
}
+ if ( internalJavadocSite == null && externalJavadocSites.isEmpty() )
+ {
+ throw new IllegalArgumentException( "Either internal or at least one accessible external javadoc "
+ + "URLs must be given!" );
+ }
}
/**
@@ -158,6 +163,7 @@ public class JavadocLinkGenerator
* @param javadocReference
* @return the (deep-) link towards 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
*/
public URI createLink( FullyQualifiedJavadocReference javadocReference )
{
diff --git a/maven-plugin-tools-api/src/test/java/org/apache/maven/tools/plugin/javadoc/JavadocLinkGeneratorTest.java b/maven-plugin-tools-api/src/test/java/org/apache/maven/tools/plugin/javadoc/JavadocLinkGeneratorTest.java
index 20696ad7..620128bf 100644
--- a/maven-plugin-tools-api/src/test/java/org/apache/maven/tools/plugin/javadoc/JavadocLinkGeneratorTest.java
+++ b/maven-plugin-tools-api/src/test/java/org/apache/maven/tools/plugin/javadoc/JavadocLinkGeneratorTest.java
@@ -116,11 +116,9 @@ class JavadocLinkGeneratorTest
@Test
void testInaccessibleBaseUri() throws URISyntaxException
{
- // construction succeeds, but every subsequent link creation fails
- JavadocLinkGenerator linkGenerator =
- new JavadocLinkGenerator( Collections.singletonList( new URI( "https://example.com/apidocs/" ) ), null );
- assertThrows( IllegalArgumentException.class,
- () -> linkGenerator.createLink( new FullyQualifiedJavadocReference( "some.unknown.package", false ) ) );
+ // construction fails as no valid site URL is given
+ assertThrows( IllegalArgumentException.class, () ->
+ new JavadocLinkGenerator( Collections.singletonList( new URI( "https://example.com/apidocs/" ) ), null ) );
}
}
diff --git a/maven-plugin-tools-generators/src/main/java/org/apache/maven/tools/plugin/generator/PluginDescriptorFilesGenerator.java b/maven-plugin-tools-generators/src/main/java/org/apache/maven/tools/plugin/generator/PluginDescriptorFilesGenerator.java
index 07a1f6dc..870045a4 100644
--- a/maven-plugin-tools-generators/src/main/java/org/apache/maven/tools/plugin/generator/PluginDescriptorFilesGenerator.java
+++ b/maven-plugin-tools-generators/src/main/java/org/apache/maven/tools/plugin/generator/PluginDescriptorFilesGenerator.java
@@ -167,11 +167,20 @@ public class PluginDescriptorFilesGenerator
w.startElement( "mojos" );
- JavadocLinkGenerator javadocLinkGenerator =
- new JavadocLinkGenerator( request.getInternalJavadocBaseUrl(),
- request.getInternalJavadocVersion(),
- request.getExternalJavadocBaseUrls(),
- request.getSettings() );
+ final JavadocLinkGenerator javadocLinkGenerator;
+ if ( request.getInternalJavadocBaseUrl() != null
+ || ( request.getExternalJavadocBaseUrls() != null
+ && !request.getExternalJavadocBaseUrls().isEmpty() ) )
+ {
+ javadocLinkGenerator = new JavadocLinkGenerator( request.getInternalJavadocBaseUrl(),
+ request.getInternalJavadocVersion(),
+ request.getExternalJavadocBaseUrls(),
+ request.getSettings() );
+ }
+ else
+ {
+ javadocLinkGenerator = null;
+ }
if ( pluginDescriptor.getMojos() != null )
{
List<MojoDescriptor> descriptors = pluginDescriptor.getMojos();
@@ -506,16 +515,19 @@ public class PluginDescriptorFilesGenerator
if ( type == DescriptorType.XHTML )
{
- try
- {
- URI uri = javadocLinkGenerator.createLink( parameter.getType() );
- GeneratorUtils.element( w, "typeJavadocUrl", uri.toString() );
- }
- catch ( IllegalArgumentException e )
+ if ( javadocLinkGenerator != null )
{
- LOG.warn( "Could not get javadoc URL for type {} of parameter {} from goal {}: {}",
- parameter.getType(), parameter.getName(), mojoDescriptor.getGoal(),
- e.getMessage() );
+ try
+ {
+ URI uri = javadocLinkGenerator.createLink( parameter.getType() );
+ GeneratorUtils.element( w, "typeJavadocUrl", uri.toString() );
+ }
+ catch ( IllegalArgumentException e )
+ {
+ LOG.warn( "Could not get javadoc URL for type {} of parameter {} from goal {}: {}",
+ parameter.getType(), parameter.getName(), mojoDescriptor.getGoal(),
+ e.getMessage() );
+ }
}
}
if ( parameter.getSince() != null )