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:06 UTC
[maven-plugin-tools] branch bugfix/no-warning-for-javadoc-url-when-sites-not-configured created (now 75246fc4)
This is an automated email from the ASF dual-hosted git repository.
kwin pushed a change to branch bugfix/no-warning-for-javadoc-url-when-sites-not-configured
in repository https://gitbox.apache.org/repos/asf/maven-plugin-tools.git
at 75246fc4 [MPLUGIN-429] Don't emit warning for missing javadoc URI if no javadoc sources are configured
This branch includes the following new commits:
new 75246fc4 [MPLUGIN-429] Don't emit warning for missing javadoc URI if no javadoc sources are configured
The 1 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails. The revisions
listed as "add" were already present in the repository and have only
been added to this reference.
[maven-plugin-tools] 01/01: [MPLUGIN-429] Don't emit warning for missing javadoc URI if no javadoc sources are configured
Posted by kw...@apache.org.
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 )