View Javadoc
1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one
3    * or more contributor license agreements.  See the NOTICE file
4    * distributed with this work for additional information
5    * regarding copyright ownership.  The ASF licenses this file
6    * to you under the Apache License, Version 2.0 (the
7    * "License"); you may not use this file except in compliance
8    * with the License.  You may obtain a copy of the License at
9    *
10   *   http://www.apache.org/licenses/LICENSE-2.0
11   *
12   * Unless required by applicable law or agreed to in writing,
13   * software distributed under the License is distributed on an
14   * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15   * KIND, either express or implied.  See the License for the
16   * specific language governing permissions and limitations
17   * under the License.
18   */
19  package org.apache.maven.plugin.plugin;
20  
21  import java.io.File;
22  import java.net.URI;
23  import java.util.Arrays;
24  import java.util.Collections;
25  import java.util.LinkedHashSet;
26  import java.util.List;
27  import java.util.Set;
28  
29  import org.apache.maven.artifact.Artifact;
30  import org.apache.maven.artifact.resolver.filter.ArtifactFilter;
31  import org.apache.maven.artifact.resolver.filter.IncludesArtifactFilter;
32  import org.apache.maven.execution.MavenSession;
33  import org.apache.maven.plugin.MojoExecutionException;
34  import org.apache.maven.plugin.descriptor.InvalidPluginDescriptorException;
35  import org.apache.maven.plugin.descriptor.PluginDescriptor;
36  import org.apache.maven.plugins.annotations.Component;
37  import org.apache.maven.plugins.annotations.LifecyclePhase;
38  import org.apache.maven.plugins.annotations.Mojo;
39  import org.apache.maven.plugins.annotations.Parameter;
40  import org.apache.maven.plugins.annotations.ResolutionScope;
41  import org.apache.maven.tools.plugin.DefaultPluginToolsRequest;
42  import org.apache.maven.tools.plugin.ExtendedPluginDescriptor;
43  import org.apache.maven.tools.plugin.PluginToolsRequest;
44  import org.apache.maven.tools.plugin.extractor.ExtractionException;
45  import org.apache.maven.tools.plugin.generator.GeneratorException;
46  import org.apache.maven.tools.plugin.generator.GeneratorUtils;
47  import org.apache.maven.tools.plugin.generator.PluginDescriptorFilesGenerator;
48  import org.apache.maven.tools.plugin.scanner.MojoScanner;
49  import org.codehaus.plexus.component.repository.ComponentDependency;
50  import org.codehaus.plexus.util.ReaderFactory;
51  import org.sonatype.plexus.build.incremental.BuildContext;
52  
53  /**
54   * <p>
55   * Generate a plugin descriptor.
56   * </p>
57   * <p>
58   * <b>Note:</b> Since 3.0, for Java plugin annotations support,
59   * default <a href="http://maven.apache.org/ref/current/maven-core/lifecycles.html">phase</a>
60   * defined by this goal is after the "compilation" of any scripts. This doesn't override
61   * <a href="/ref/current/maven-core/default-bindings.html#Bindings_for_maven-plugin_packaging">the default binding coded
62   * at generate-resources phase</a> in Maven core.
63   * </p>
64   * @author <a href="mailto:jason@maven.org">Jason van Zyl</a>
65   * @since 2.0
66   */
67  @Mojo(
68          name = "descriptor",
69          defaultPhase = LifecyclePhase.PROCESS_CLASSES,
70          requiresDependencyResolution = ResolutionScope.COMPILE_PLUS_RUNTIME,
71          threadSafe = true)
72  public class DescriptorGeneratorMojo extends AbstractGeneratorMojo {
73      private static final String VALUE_AUTO = "auto";
74  
75      /**
76       * The directory where the generated <code>plugin.xml</code> file will be put.
77       */
78      @Parameter(defaultValue = "${project.build.outputDirectory}/META-INF/maven", readonly = true)
79      private File outputDirectory;
80  
81      /**
82       * The file encoding of the source files.
83       *
84       * @since 2.5
85       */
86      @Parameter(property = "encoding", defaultValue = "${project.build.sourceEncoding}")
87      private String encoding;
88  
89      /**
90       * A flag to disable generation of the <code>plugin.xml</code> in favor of a hand authored plugin descriptor.
91       *
92       * @since 2.6
93       */
94      @Parameter(defaultValue = "false")
95      private boolean skipDescriptor;
96  
97      /**
98       * <p>
99       * The role names of mojo extractors to use.
100      * </p>
101      * <p>
102      * If not set, all mojo extractors will be used. If set to an empty extractor name, no mojo extractors
103      * will be used.
104      * </p>
105      * Example:
106      * <pre>
107      *  &lt;!-- Use all mojo extractors --&gt;
108      *  &lt;extractors/&gt;
109      *
110      *  &lt;!-- Use no mojo extractors --&gt;
111      *  &lt;extractors&gt;
112      *      &lt;extractor/&gt;
113      *  &lt;/extractors&gt;
114      *
115      *  &lt;!-- Use only bsh mojo extractor --&gt;
116      *  &lt;extractors&gt;
117      *      &lt;extractor&gt;bsh&lt;/extractor&gt;
118      *  &lt;/extractors&gt;
119      * </pre>
120      * The extractors with the following names ship with {@code maven-plugin-tools}:
121      * <ol>
122      *  <li>{@code java-annotations}</li>
123      *  <li>{@code java-javadoc}, deprecated</li>
124      *  <li>{@code ant}, deprecated</li>
125      *  <li>{@code bsh}, deprecated</li>
126      * </ol>
127      */
128     @Parameter
129     private Set<String> extractors;
130 
131     /**
132      * By default, an exception is throw if no mojo descriptor is found. As the maven-plugin is defined in core, the
133      * descriptor generator mojo is bound to generate-resources phase.
134      * But for annotations, the compiled classes are needed, so skip error
135      *
136      * @since 3.0
137      */
138     @Parameter(property = "maven.plugin.skipErrorNoDescriptorsFound", defaultValue = "false")
139     private boolean skipErrorNoDescriptorsFound;
140 
141     /**
142      * Flag controlling is "expected dependencies in provided scope" check to be performed or not. Default value:
143      * {@code true}.
144      *
145      * @since 3.6.3
146      */
147     @Parameter(defaultValue = "true", property = "maven.plugin.checkExpectedProvidedScope")
148     private boolean checkExpectedProvidedScope = true;
149 
150     /**
151      * List of {@code groupId} strings of artifact coordinates that are expected to be in "provided" scope. Default
152      * value: {@code ["org.apache.maven"]}.
153      *
154      * @since 3.6.3
155      */
156     @Parameter
157     private List<String> expectedProvidedScopeGroupIds = Collections.singletonList("org.apache.maven");
158 
159     /**
160      * List of {@code groupId:artifactId} strings of artifact coordinates that are to be excluded from "expected
161      * provided scope" check. Default value:
162      * {@code ["org.apache.maven:maven-archiver", "org.apache.maven:maven-jxr", "org.apache.maven:plexus-utils"]}.
163      *
164      * @since 3.6.3
165      */
166     @Parameter
167     private List<String> expectedProvidedScopeExclusions = Arrays.asList(
168             "org.apache.maven:maven-archiver", "org.apache.maven:maven-jxr", "org.apache.maven:plexus-utils");
169 
170     /**
171      * Specify the dependencies as {@code groupId:artifactId} containing (abstract) Mojos, to filter
172      * dependencies scanned at runtime and focus on dependencies that are really useful to Mojo analysis.
173      * By default, the value is {@code null} and all dependencies are scanned (as before this parameter was added).
174      * If specified in the configuration with no children, no dependencies are scanned.
175      *
176      * @since 3.5
177      */
178     @Parameter
179     private List<String> mojoDependencies = null;
180 
181     /**
182      * Creates links to existing external javadoc-generated documentation.
183      * <br>
184      * <b>Notes</b>:
185      * all given links should have a fetchable {@code /package-list} or {@code /element-list} file.
186      * For instance:
187      * <pre>
188      * &lt;externalJavadocBaseUrls&gt;
189      *   &lt;externalJavadocBaseUrl&gt;https://docs.oracle.com/javase/8/docs/api/&lt;/externalJavadocBaseUrl&gt;
190      * &lt;/externalJavadocBaseUrls&gt;
191      * </pre>
192      * is valid because <code>https://docs.oracle.com/javase/8/docs/api/package-list</code> exists.
193      * See <a href="https://docs.oracle.com/en/java/javase/17/docs/specs/man/javadoc.html#standard-doclet-options">
194      * link option of the javadoc tool</a>.
195      * Using this parameter requires connectivity to the given URLs during the goal execution.
196      * @since 3.7.0
197      */
198     @Parameter(property = "externalJavadocBaseUrls", alias = "links")
199     protected List<URI> externalJavadocBaseUrls;
200 
201     /**
202      * The base URL for the Javadoc site containing the current project's API documentation.
203      * This may be relative to the root of the generated Maven site.
204      * It does not need to exist yet at the time when this goal is executed.
205      * Must end with a slash.
206      * <b>In case this is set the javadoc reporting goal should be executed prior to
207      * <a href="../maven-plugin-report-plugin/index.html">Plugin Report</a>.</b>
208      * @since 3.7.0
209      */
210     @Parameter(property = "internalJavadocBaseUrl")
211     protected URI internalJavadocBaseUrl;
212 
213     /**
214      * The version of the javadoc tool (equal to the container JDK version) used to generate the internal javadoc
215      * Only relevant if {@link #internalJavadocBaseUrl} is set.
216      * The default value needs to be overwritten in case toolchains are being used for generating Javadoc.
217      *
218      * @since 3.7.0
219      */
220     @Parameter(property = "internalJavadocVersion", defaultValue = "${java.version}")
221     protected String internalJavadocVersion;
222 
223     @Component
224     private MavenSession mavenSession;
225 
226     /**
227      * The required Java version to set in the plugin descriptor. This is evaluated by Maven 4 and ignored by earlier
228      * Maven versions. Can be either one of the following formats:
229      *
230      * <ul>
231      * <li>A version range which specifies the supported Java versions. It can either use the usual mathematical
232      * syntax like {@code "[1.7,9),[11,)"} or use a single version like {@code "1.8"}. The latter is a short
233      * form for {@code "[1.8,)"}, i.e. denotes the minimum version required.</li>
234      * <li>{@code "auto"} to determine the minimum Java version from the binary class version being generated during
235      * compilation (determined by the extractor).</li>
236      * </ul>
237      *
238      * @since 3.8.0
239      */
240     @Parameter(defaultValue = VALUE_AUTO)
241     String requiredJavaVersion;
242 
243     /**
244      * The required Maven version to set in the plugin descriptor. This is evaluated by Maven 4 and ignored by earlier
245      * Maven versions. Can be either one of the following formats:
246      *
247      * <ul>
248      * <li>A version range which specifies the supported Maven versions. It can either use the usual mathematical
249      * syntax like {@code "[2.0.10,2.1.0),[3.0,)"} or use a single version like {@code "2.2.1"}. The latter is a short
250      * form for {@code "[2.2.1,)"}, i.e. denotes the minimum version required.</li>
251      * <li>{@code "auto"} to determine the minimum Maven version from the POM's Maven prerequisite, or if not set the
252      * referenced Maven Plugin API version.</li>
253      * </ul>
254      * This value takes precedence over the
255      * <a href="https://maven.apache.org/pom.html#Prerequisites">POM's Maven prerequisite</a> in Maven 4.
256      *
257      * @since 3.8.0
258      */
259     @Parameter(defaultValue = VALUE_AUTO)
260     String requiredMavenVersion;
261 
262     /**
263      * The component used for scanning the source tree for mojos.
264      */
265     @Component
266     private MojoScanner mojoScanner;
267 
268     @Component
269     protected BuildContext buildContext;
270 
271     public void generate() throws MojoExecutionException {
272 
273         if (!"maven-plugin".equalsIgnoreCase(project.getArtifactId())
274                 && project.getArtifactId().toLowerCase().startsWith("maven-")
275                 && project.getArtifactId().toLowerCase().endsWith("-plugin")
276                 && !"org.apache.maven.plugins".equals(project.getGroupId())) {
277             getLog().warn(LS + LS + "Artifact Ids of the format maven-___-plugin are reserved for" + LS
278                     + "plugins in the Group Id org.apache.maven.plugins" + LS
279                     + "Please change your artifactId to the format ___-maven-plugin" + LS
280                     + "In the future this error will break the build." + LS + LS);
281         }
282 
283         if (skipDescriptor) {
284             getLog().warn("Execution skipped");
285             return;
286         }
287 
288         if (checkExpectedProvidedScope) {
289             Set<Artifact> wrongScopedArtifacts = dependenciesNotInProvidedScope();
290             if (!wrongScopedArtifacts.isEmpty()) {
291                 StringBuilder message = new StringBuilder(
292                         LS + LS + "Some dependencies of Maven Plugins are expected to be in provided scope." + LS
293                                 + "Please make sure that dependencies listed below declared in POM" + LS
294                                 + "have set '<scope>provided</scope>' as well." + LS + LS
295                                 + "The following dependencies are in wrong scope:" + LS);
296                 for (Artifact artifact : wrongScopedArtifacts) {
297                     message.append(" * ").append(artifact).append(LS);
298                 }
299                 message.append(LS).append(LS);
300 
301                 getLog().warn(message.toString());
302             }
303         }
304 
305         mojoScanner.setActiveExtractors(extractors);
306 
307         // TODO: could use this more, eg in the writing of the plugin descriptor!
308         PluginDescriptor pluginDescriptor = new PluginDescriptor();
309 
310         pluginDescriptor.setGroupId(project.getGroupId());
311 
312         pluginDescriptor.setArtifactId(project.getArtifactId());
313 
314         pluginDescriptor.setVersion(project.getVersion());
315 
316         pluginDescriptor.setGoalPrefix(goalPrefix);
317 
318         pluginDescriptor.setName(project.getName());
319 
320         pluginDescriptor.setDescription(project.getDescription());
321 
322         if (encoding == null || encoding.length() < 1) {
323             getLog().warn("Using platform encoding (" + ReaderFactory.FILE_ENCODING
324                     + " actually) to read mojo source files, i.e. build is platform dependent!");
325         } else {
326             getLog().info("Using '" + encoding + "' encoding to read mojo source files.");
327         }
328 
329         if (internalJavadocBaseUrl != null && !internalJavadocBaseUrl.getPath().endsWith("/")) {
330             throw new MojoExecutionException("Given parameter 'internalJavadocBaseUrl' must end with a slash but is '"
331                     + internalJavadocBaseUrl + "'");
332         }
333         try {
334             List<ComponentDependency> deps = GeneratorUtils.toComponentDependencies(project.getArtifacts());
335             pluginDescriptor.setDependencies(deps);
336 
337             PluginToolsRequest request = new DefaultPluginToolsRequest(project, pluginDescriptor);
338             request.setEncoding(encoding);
339             request.setSkipErrorNoDescriptorsFound(skipErrorNoDescriptorsFound);
340             request.setDependencies(filterMojoDependencies());
341             request.setRepoSession(mavenSession.getRepositorySession());
342             request.setInternalJavadocBaseUrl(internalJavadocBaseUrl);
343             request.setInternalJavadocVersion(internalJavadocVersion);
344             request.setExternalJavadocBaseUrls(externalJavadocBaseUrls);
345             request.setSettings(mavenSession.getSettings());
346 
347             mojoScanner.populatePluginDescriptor(request);
348             request.setPluginDescriptor(extendPluginDescriptor(request));
349 
350             outputDirectory.mkdirs();
351 
352             PluginDescriptorFilesGenerator pluginDescriptorGenerator = new PluginDescriptorFilesGenerator();
353             pluginDescriptorGenerator.execute(outputDirectory, request);
354 
355             buildContext.refresh(outputDirectory);
356         } catch (GeneratorException e) {
357             throw new MojoExecutionException("Error writing plugin descriptor", e);
358         } catch (InvalidPluginDescriptorException | ExtractionException e) {
359             throw new MojoExecutionException(
360                     "Error extracting plugin descriptor: '" + e.getLocalizedMessage() + "'", e);
361         } catch (LinkageError e) {
362             throw new MojoExecutionException(
363                     "The API of the mojo scanner is not compatible with this plugin version."
364                             + " Please check the plugin dependencies configured"
365                             + " in the POM and ensure the versions match.",
366                     e);
367         }
368     }
369 
370     private PluginDescriptor extendPluginDescriptor(PluginToolsRequest request) {
371         ExtendedPluginDescriptor extendedPluginDescriptor = new ExtendedPluginDescriptor(request.getPluginDescriptor());
372         extendedPluginDescriptor.setRequiredJavaVersion(getRequiredJavaVersion(request));
373         extendedPluginDescriptor.setRequiredMavenVersion(getRequiredMavenVersion(request));
374         return extendedPluginDescriptor;
375     }
376 
377     private String getRequiredMavenVersion(PluginToolsRequest request) {
378         if (!VALUE_AUTO.equals(requiredMavenVersion)) {
379             return requiredMavenVersion;
380         }
381         getLog().debug("Trying to derive Maven version automatically from project prerequisites...");
382         String requiredMavenVersion =
383                 project.getPrerequisites() != null ? project.getPrerequisites().getMaven() : null;
384         if (requiredMavenVersion == null) {
385             getLog().debug("Trying to derive Maven version automatically from referenced Maven Plugin API artifact "
386                     + "version...");
387             requiredMavenVersion = request.getUsedMavenApiVersion();
388         }
389         if (requiredMavenVersion == null) {
390             getLog().warn("Cannot determine the required Maven version automatically, it is recommended to "
391                     + "configure some explicit value manually.");
392         }
393         return requiredMavenVersion;
394     }
395 
396     private String getRequiredJavaVersion(PluginToolsRequest request) {
397         if (!VALUE_AUTO.equals(requiredJavaVersion)) {
398             return requiredJavaVersion;
399         }
400         String minRequiredJavaVersion = request.getRequiredJavaVersion();
401         if (minRequiredJavaVersion == null) {
402             getLog().warn("Cannot determine the minimally required Java version automatically, it is recommended to "
403                     + "configure some explicit value manually.");
404             return null;
405         }
406 
407         return minRequiredJavaVersion;
408     }
409 
410     /**
411      * Collects all dependencies expected to be in "provided" scope but are NOT in "provided" scope.
412      */
413     private Set<Artifact> dependenciesNotInProvidedScope() {
414         LinkedHashSet<Artifact> wrongScopedDependencies = new LinkedHashSet<>();
415 
416         for (Artifact dependency : project.getArtifacts()) {
417             String ga = dependency.getGroupId() + ":" + dependency.getArtifactId();
418             if (expectedProvidedScopeGroupIds.contains(dependency.getGroupId())
419                     && !expectedProvidedScopeExclusions.contains(ga)
420                     && !Artifact.SCOPE_PROVIDED.equals(dependency.getScope())) {
421                 wrongScopedDependencies.add(dependency);
422             }
423         }
424 
425         return wrongScopedDependencies;
426     }
427 
428     /**
429      * Get dependencies filtered with mojoDependencies configuration.
430      *
431      * @return eventually filtered dependencies, or even <code>null</code> if configured with empty mojoDependencies
432      * list
433      * @see #mojoDependencies
434      */
435     private Set<Artifact> filterMojoDependencies() {
436         Set<Artifact> filteredArtifacts;
437         if (mojoDependencies == null) {
438             filteredArtifacts = new LinkedHashSet<>(project.getArtifacts());
439         } else if (mojoDependencies.isEmpty()) {
440             filteredArtifacts = null;
441         } else {
442             filteredArtifacts = new LinkedHashSet<>();
443 
444             ArtifactFilter filter = new IncludesArtifactFilter(mojoDependencies);
445 
446             for (Artifact artifact : project.getArtifacts()) {
447                 if (filter.include(artifact)) {
448                     filteredArtifacts.add(artifact);
449                 }
450             }
451         }
452 
453         return filteredArtifacts;
454     }
455 }