This is an automated email from the ASF dual-hosted git repository. rfscholte pushed a commit to branch MJAVADOC-611 in repository https://gitbox.apache.org/repos/asf/maven-javadoc-plugin.git
commit 8792446d712120005e2698d3f86c09b0ce498a15 Author: rfscholte <[email protected]> AuthorDate: Sun May 2 13:33:19 2021 +0200 [MJAVADOC-611] Support adjustment javadoc link of dependency --- .../invoker.properties | 17 +++++ .../projects/MJAVADOC-611_dependencyLinks/pom.xml | 60 ++++++++++++++++ .../src/main/java/foo/Bar.java | 34 +++++++++ .../MJAVADOC-611_dependencyLinks/verify.groovy | 25 +++++++ .../maven/plugins/javadoc/AbstractJavadocMojo.java | 80 ++++++++++++++++++---- .../maven/plugins/javadoc/DependencyLink.java | 76 ++++++++++++++++++++ 6 files changed, 278 insertions(+), 14 deletions(-) diff --git a/src/it/projects/MJAVADOC-611_dependencyLinks/invoker.properties b/src/it/projects/MJAVADOC-611_dependencyLinks/invoker.properties new file mode 100644 index 0000000..7a948bb --- /dev/null +++ b/src/it/projects/MJAVADOC-611_dependencyLinks/invoker.properties @@ -0,0 +1,17 @@ +# Licensed to the Apache Software Foundation (ASF) under one +# or more contributor license agreements. See the NOTICE file +# distributed with this work for additional information +# regarding copyright ownership. The ASF licenses this file +# to you under the Apache License, Version 2.0 (the +# "License"); you may not use this file except in compliance +# with the License. You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, +# software distributed under the License is distributed on an +# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +# KIND, either express or implied. See the License for the +# specific language governing permissions and limitations +# under the License. +invoker.goals = compile javadoc:javadoc diff --git a/src/it/projects/MJAVADOC-611_dependencyLinks/pom.xml b/src/it/projects/MJAVADOC-611_dependencyLinks/pom.xml new file mode 100644 index 0000000..5049d7d --- /dev/null +++ b/src/it/projects/MJAVADOC-611_dependencyLinks/pom.xml @@ -0,0 +1,60 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + ~ Licensed to the Apache Software Foundation (ASF) under one + ~ or more contributor license agreements. See the NOTICE file + ~ distributed with this work for additional information + ~ regarding copyright ownership. The ASF licenses this file + ~ to you under the Apache License, Version 2.0 (the + ~ "License"); you may not use this file except in compliance + ~ with the License. You may obtain a copy of the License at + ~ + ~ http://www.apache.org/licenses/LICENSE-2.0 + ~ + ~ Unless required by applicable law or agreed to in writing, + ~ software distributed under the License is distributed on an + ~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + ~ KIND, either express or implied. See the License for the + ~ specific language governing permissions and limitations + ~ under the License. + --> +<project xmlns="http://maven.apache.org/POM/4.0.0"; + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"; + xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd";> + <modelVersion>4.0.0</modelVersion> + + <groupId>foo</groupId> + <artifactId>bar</artifactId> + <version>0.1.0-SNAPSHOT</version> + + <properties> + <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding> + </properties> + + <build> + <plugins> + <plugin> + <groupId>org.apache.maven.plugins</groupId> + <artifactId>maven-javadoc-plugin</artifactId> + <version>@project.version@</version> + <configuration> + <detectLinks>true</detectLinks> + <dependencyLinks> + <link> + <groupId>org.ow2.asm</groupId> + <artifactId>asm</artifactId> + <url>https://asm.ow2.io/javadoc</url> + </link> + </dependencyLinks> + </configuration> + </plugin> + </plugins> + </build> + + <dependencies> + <dependency> + <groupId>org.ow2.asm</groupId> + <artifactId>asm</artifactId> + <version>7.1</version> + </dependency> + </dependencies> +</project> diff --git a/src/it/projects/MJAVADOC-611_dependencyLinks/src/main/java/foo/Bar.java b/src/it/projects/MJAVADOC-611_dependencyLinks/src/main/java/foo/Bar.java new file mode 100644 index 0000000..7ef6422 --- /dev/null +++ b/src/it/projects/MJAVADOC-611_dependencyLinks/src/main/java/foo/Bar.java @@ -0,0 +1,34 @@ +package foo; + +/* + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ + +import org.objectweb.asm.Opcodes; + +/** + * Bar. + */ +public class Bar implements Opcodes +{ + public void run() + { + System.out.println( "Bar" ); + } + +} diff --git a/src/it/projects/MJAVADOC-611_dependencyLinks/verify.groovy b/src/it/projects/MJAVADOC-611_dependencyLinks/verify.groovy new file mode 100644 index 0000000..f305650 --- /dev/null +++ b/src/it/projects/MJAVADOC-611_dependencyLinks/verify.groovy @@ -0,0 +1,25 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ + +def options = new File( basedir, 'target/site/apidocs/options' ); +assert options.exists() : options + " not found" + +def linkLines = options.readLines().dropWhile{it != '-link'}.drop(1).takeWhile{!it.startsWith('-')} +assert linkLines.size() == 1 +assert linkLines[0] == "'https://asm.ow2.io/javadoc'" diff --git a/src/main/java/org/apache/maven/plugins/javadoc/AbstractJavadocMojo.java b/src/main/java/org/apache/maven/plugins/javadoc/AbstractJavadocMojo.java index ab51e51..db58e77 100644 --- a/src/main/java/org/apache/maven/plugins/javadoc/AbstractJavadocMojo.java +++ b/src/main/java/org/apache/maven/plugins/javadoc/AbstractJavadocMojo.java @@ -527,6 +527,7 @@ public abstract class AbstractJavadocMojo * The added Javadoc <code>-link</code> parameter will be <code>http://commons.apache.org/lang/apidocs</code>. * * @see #links + * @see #dependencyLinks * @since 2.6 */ @Parameter( property = "detectLinks", defaultValue = "false" ) @@ -1142,9 +1143,31 @@ public abstract class AbstractJavadocMojo * * @see #detectLinks * @see #detectJavaApiLink + * @see #dependencyLinks */ @Parameter( property = "links" ) protected ArrayList<String> links; + + + /** + * Redefine the apidoc URL for specific dependencies when using {@link #detectLinks}. + * Useful if the dependency wasn't build with Maven or when the apidocs have been moved. + * <pre> + * <dependencyLinks> + * <dependencyLink> + * <groupId>groupId</groupId> + * <artifactId>artifactId</artifactId> + * <classifier>classifier</classifier> <!-- optional --> + * <url>version</url> + * </dependencyLink> + * </dependencyLinks> + * </pre> + * + * @see #detectLinks + * @since 3.3.0 + */ + @Parameter + private List<DependencyLink> dependencyLinks = new ArrayList<>(); /** * Creates an HTML version of each source file (with line numbers) and adds links to them from the standard @@ -6390,32 +6413,61 @@ public abstract class AbstractJavadocMojo continue; } - try + Optional<DependencyLink> depLink = + this.dependencyLinks.stream().filter( d -> matches( d, artifact ) ).findAny(); + + final String url; + final boolean detected; + if ( depLink.isPresent() ) { - MavenProject artifactProject = - mavenProjectBuilder.build( artifact, getProjectBuildingRequest( project ) ).getProject(); - - if ( StringUtils.isNotEmpty( artifactProject.getUrl() ) ) + url = depLink.get().getUrl(); + detected = false; + } + else + { + try { - String url = getJavadocLink( artifactProject ); - - if ( isValidJavadocLink( url, true ) ) - { - getLog().debug( "Added Javadoc link: " + url + " for " + artifactProject.getId() ); + MavenProject artifactProject = + mavenProjectBuilder.build( artifact, getProjectBuildingRequest( project ) ).getProject(); - dependenciesLinks.add( url ); - } + url = getJavadocLink( artifactProject ); + detected = true; + } + catch ( ProjectBuildingException e ) + { + logError( "ProjectBuildingException for " + artifact.toString() + ": " + e.getMessage(), e ); + continue; } } - catch ( ProjectBuildingException e ) + + if ( isValidJavadocLink( url, detected ) ) { - logError( "ProjectBuildingException for " + artifact.toString() + ": " + e.getMessage(), e ); + getLog().debug( "Added Javadoc link: " + url + " for " + artifact.getId() ); + + dependenciesLinks.add( url ); } } return dependenciesLinks; } + private boolean matches( DependencyLink d, Artifact artifact ) + { + if ( d.getGroupId() != null && !d.getGroupId().equals( artifact.getGroupId() ) ) + { + return false; + } + if ( d.getArtifactId() != null && !d.getArtifactId().equals( artifact.getArtifactId() ) ) + { + return false; + } + if ( d.getClassifier() != null && !d.getClassifier().equals( artifact.getClassifier() ) ) + { + return false; + } + return true; + } + /** * @return if {@link #detectJavaApiLink}, the Java API link based on the {@link #javaApiLinks} properties and the * value of the <code>source</code> parameter in the diff --git a/src/main/java/org/apache/maven/plugins/javadoc/DependencyLink.java b/src/main/java/org/apache/maven/plugins/javadoc/DependencyLink.java new file mode 100644 index 0000000..dacfa04 --- /dev/null +++ b/src/main/java/org/apache/maven/plugins/javadoc/DependencyLink.java @@ -0,0 +1,76 @@ +package org.apache.maven.plugins.javadoc; + +/* + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ + +/** + * In case of autodetectLinks, this class can overwrite the url for that dependency + * + * @since 3.3.0 + */ +public class DependencyLink +{ + private String groupId; + + private String artifactId; + + private String classifier; + + private String url; + + public String getUrl() + { + return url; + } + + public void setUrl( String url ) + { + this.url = url; + } + + public String getGroupId() + { + return groupId; + } + + public void setGroupId( String groupId ) + { + this.groupId = groupId; + } + + public String getArtifactId() + { + return artifactId; + } + + public void setArtifactId( String artifactId ) + { + this.artifactId = artifactId; + } + + public String getClassifier() + { + return classifier; + } + + public void setClassifier( String classifier ) + { + this.classifier = classifier; + } +}
