001/*
002 * Licensed to the Apache Software Foundation (ASF) under one
003 * or more contributor license agreements.  See the NOTICE file
004 * distributed with this work for additional information
005 * regarding copyright ownership.  The ASF licenses this file
006 * to you under the Apache License, Version 2.0 (the
007 * "License"); you may not use this file except in compliance
008 * with the License.  You may obtain a copy of the License at
009 *
010 *   http://www.apache.org/licenses/LICENSE-2.0
011 *
012 * Unless required by applicable law or agreed to in writing,
013 * software distributed under the License is distributed on an
014 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015 * KIND, either express or implied.  See the License for the
016 * specific language governing permissions and limitations
017 * under the License.
018 */
019package org.apache.maven.plugin.plugin;
020
021import javax.inject.Inject;
022
023import java.io.File;
024import java.net.URI;
025import java.util.Arrays;
026import java.util.Collections;
027import java.util.LinkedHashSet;
028import java.util.List;
029import java.util.Set;
030
031import org.apache.maven.artifact.Artifact;
032import org.apache.maven.artifact.resolver.filter.ArtifactFilter;
033import org.apache.maven.artifact.resolver.filter.IncludesArtifactFilter;
034import org.apache.maven.execution.MavenSession;
035import org.apache.maven.plugin.MojoExecutionException;
036import org.apache.maven.plugin.descriptor.InvalidPluginDescriptorException;
037import org.apache.maven.plugin.descriptor.PluginDescriptor;
038import org.apache.maven.plugins.annotations.LifecyclePhase;
039import org.apache.maven.plugins.annotations.Mojo;
040import org.apache.maven.plugins.annotations.Parameter;
041import org.apache.maven.plugins.annotations.ResolutionScope;
042import org.apache.maven.project.MavenProject;
043import org.apache.maven.tools.plugin.DefaultPluginToolsRequest;
044import org.apache.maven.tools.plugin.PluginDescriptorHelper;
045import org.apache.maven.tools.plugin.PluginToolsRequest;
046import org.apache.maven.tools.plugin.extractor.ExtractionException;
047import org.apache.maven.tools.plugin.generator.GeneratorException;
048import org.apache.maven.tools.plugin.generator.GeneratorUtils;
049import org.apache.maven.tools.plugin.generator.PluginDescriptorFilesGenerator;
050import org.apache.maven.tools.plugin.scanner.MojoScanner;
051import org.codehaus.plexus.component.repository.ComponentDependency;
052import org.codehaus.plexus.util.ReaderFactory;
053import org.sonatype.plexus.build.incremental.BuildContext;
054
055/**
056 * <p>
057 * Generate a plugin descriptor.
058 * </p>
059 * <p>
060 * <b>Note:</b> Since 3.0, for Java plugin annotations support,
061 * default <a href="http://maven.apache.org/ref/current/maven-core/lifecycles.html">phase</a>
062 * defined by this goal is after the "compilation" of any scripts. This doesn't override
063 * <a href="/ref/current/maven-core/default-bindings.html#Bindings_for_maven-plugin_packaging">the default binding coded
064 * at generate-resources phase</a> in Maven core.
065 * </p>
066 * @author <a href="mailto:jason@maven.org">Jason van Zyl</a>
067 * @since 2.0
068 */
069@Mojo(
070        name = "descriptor",
071        defaultPhase = LifecyclePhase.PROCESS_CLASSES,
072        requiresDependencyResolution = ResolutionScope.COMPILE_PLUS_RUNTIME,
073        threadSafe = true)
074public class DescriptorGeneratorMojo extends AbstractGeneratorMojo {
075    private static final String VALUE_AUTO = "auto";
076
077    /**
078     * The directory where the generated <code>plugin.xml</code> file will be put.
079     */
080    @Parameter(defaultValue = "${project.build.outputDirectory}/META-INF/maven", readonly = true)
081    private File outputDirectory;
082
083    /**
084     * The file encoding of the source files.
085     *
086     * @since 2.5
087     */
088    @Parameter(property = "encoding", defaultValue = "${project.build.sourceEncoding}")
089    private String encoding;
090
091    /**
092     * A flag to disable generation of the <code>plugin.xml</code> in favor of a hand authored plugin descriptor.
093     *
094     * @since 2.6
095     */
096    @Parameter(defaultValue = "false")
097    private boolean skipDescriptor;
098
099    /**
100     * <p>
101     * The role names of mojo extractors to use.
102     * </p>
103     * <p>
104     * If not set, all mojo extractors will be used. If set to an empty extractor name, no mojo extractors
105     * will be used.
106     * </p>
107     * Example:
108     * <pre>
109     *  &lt;!-- Use all mojo extractors --&gt;
110     *  &lt;extractors/&gt;
111     *
112     *  &lt;!-- Use no mojo extractors --&gt;
113     *  &lt;extractors&gt;
114     *      &lt;extractor/&gt;
115     *  &lt;/extractors&gt;
116     *
117     *  &lt;!-- Use only bsh mojo extractor --&gt;
118     *  &lt;extractors&gt;
119     *      &lt;extractor&gt;bsh&lt;/extractor&gt;
120     *  &lt;/extractors&gt;
121     * </pre>
122     * The extractors with the following names ship with {@code maven-plugin-tools}:
123     * <ol>
124     *  <li>{@code java-annotations}</li>
125     *  <li>{@code java-javadoc}, deprecated</li>
126     *  <li>{@code ant}, deprecated</li>
127     *  <li>{@code bsh}, deprecated</li>
128     * </ol>
129     */
130    @Parameter
131    private Set<String> extractors;
132
133    /**
134     * A set of root directories to exclude from being scanned, if the extractor scans source directories
135     * to obtain metadata.
136     *
137     * <p>Globs are also supported here.
138     *
139     * <p>Users can specify this to prevent certain generated source roots from being parsed by this plugin
140     * in the event that those source roots contain potentially malformed or incompatible code.
141     *
142     * <p>This is primarily designed to facilitate allowing this plugin to operate with generated sources
143     * that use annotations or documentation in an uncontrollable format that may conflict with the parsing
144     * rules we utilise.
145     *
146     * <p>Note that this only accepts <strong>source roots</strong>. It will not accept
147     * specific paths within a source root (e.g. specific packages). In this context, a source root
148     * would be considered to be a directory holding a full Java package structure which can be
149     * passed directly to {@code javac} for compilation, or {@code javadoc} for documentation.
150     *
151     * <p>As an example, the following configuration will prevent this goal scanning any
152     * generated sources from annotation processors:
153     *
154     * <pre>{@code
155     *   <excludedScanDirectories>
156     *     <excludedScanDirectory>${project.build.directory}/generated-sources/annotations</excludedScanDirectory>
157     *     <excludedScanDirectory>${project.build.directory}/generated-test-sources/annotations</excludedScanDirectory>
158     *   </excludedScanDirectories>
159     * }</pre>
160     *
161     * @since 3.16.0
162     */
163    @Parameter
164    private Set<String> excludedScanDirectories = Collections.emptySet();
165
166    /**
167     * By default, an exception is throw if no mojo descriptor is found. As the maven-plugin is defined in core, the
168     * descriptor generator mojo is bound to generate-resources phase.
169     * But for annotations, the compiled classes are needed, so skip error
170     *
171     * @since 3.0
172     */
173    @Parameter(property = "maven.plugin.skipErrorNoDescriptorsFound", defaultValue = "false")
174    private boolean skipErrorNoDescriptorsFound;
175
176    /**
177     * Flag controlling is "expected dependencies in provided scope" check to be performed or not. Default value:
178     * {@code true}.
179     *
180     * @since 3.6.3
181     */
182    @Parameter(defaultValue = "true", property = "maven.plugin.checkExpectedProvidedScope")
183    private boolean checkExpectedProvidedScope = true;
184
185    /**
186     * List of {@code groupId} strings of artifact coordinates that are expected to be in "provided" scope. Default
187     * value: {@code ["org.apache.maven"]}.
188     *
189     * @since 3.6.3
190     */
191    @Parameter
192    private List<String> expectedProvidedScopeGroupIds = Collections.singletonList("org.apache.maven");
193
194    /**
195     * List of {@code groupId:artifactId} strings of artifact coordinates that are to be excluded from "expected
196     * provided scope" check. Default value:
197     * {@code ["org.apache.maven:maven-archiver", "org.apache.maven:maven-jxr", "org.apache.maven:plexus-utils"]}.
198     *
199     * @since 3.6.3
200     */
201    @Parameter
202    private List<String> expectedProvidedScopeExclusions = Arrays.asList(
203            "org.apache.maven:maven-archiver", "org.apache.maven:maven-jxr", "org.apache.maven:plexus-utils");
204
205    /**
206     * Specify the dependencies as {@code groupId:artifactId} containing (abstract) Mojos, to filter
207     * dependencies scanned at runtime and focus on dependencies that are really useful to Mojo analysis.
208     * By default, the value is {@code null} and all dependencies are scanned (as before this parameter was added).
209     * If specified in the configuration with no children, no dependencies are scanned.
210     *
211     * @since 3.5
212     */
213    @Parameter
214    private List<String> mojoDependencies = null;
215
216    /**
217     * Creates links to existing external javadoc-generated documentation.
218     * <br>
219     * <b>Notes</b>:
220     * all given links should have a fetchable {@code /package-list} or {@code /element-list} file.
221     * For instance:
222     * <pre>
223     * &lt;externalJavadocBaseUrls&gt;
224     *   &lt;externalJavadocBaseUrl&gt;https://docs.oracle.com/javase/8/docs/api/&lt;/externalJavadocBaseUrl&gt;
225     * &lt;/externalJavadocBaseUrls&gt;
226     * </pre>
227     * is valid because <code>https://docs.oracle.com/javase/8/docs/api/package-list</code> exists.
228     * See <a href="https://docs.oracle.com/en/java/javase/17/docs/specs/man/javadoc.html#standard-doclet-options">
229     * link option of the javadoc tool</a>.
230     * Using this parameter requires connectivity to the given URLs during the goal execution.
231     * @since 3.7.0
232     */
233    @Parameter(property = "externalJavadocBaseUrls", alias = "links")
234    protected List<URI> externalJavadocBaseUrls;
235
236    /**
237     * The base URL for the Javadoc site containing the current project's API documentation.
238     * This may be relative to the root of the generated Maven site.
239     * It does not need to exist yet at the time when this goal is executed.
240     * Must end with a slash.
241     * <b>In case this is set the javadoc reporting goal should be executed prior to
242     * <a href="../maven-plugin-report-plugin/index.html">Plugin Report</a>.</b>
243     * @since 3.7.0
244     */
245    @Parameter(property = "internalJavadocBaseUrl")
246    protected URI internalJavadocBaseUrl;
247
248    /**
249     * The version of the javadoc tool (equal to the container JDK version) used to generate the internal javadoc
250     * Only relevant if {@link #internalJavadocBaseUrl} is set.
251     * The default value needs to be overwritten in case toolchains are being used for generating Javadoc.
252     *
253     * @since 3.7.0
254     */
255    @Parameter(property = "internalJavadocVersion", defaultValue = "${java.version}")
256    protected String internalJavadocVersion;
257
258    /**
259     * The required Java version to set in the plugin descriptor. This is evaluated by Maven 4 and ignored by earlier
260     * Maven versions. Can be either one of the following formats:
261     *
262     * <ul>
263     * <li>A version range which specifies the supported Java versions. It can either use the usual mathematical
264     * syntax like {@code "[1.7,9),[11,)"} or use a single version like {@code "1.8"}. The latter is a short
265     * form for {@code "[1.8,)"}, i.e. denotes the minimum version required.</li>
266     * <li>{@code "auto"} to determine the minimum Java version from the binary class version being generated during
267     * compilation (determined by the extractor).</li>
268     * </ul>
269     *
270     * @since 3.8.0
271     */
272    @Parameter(defaultValue = VALUE_AUTO)
273    String requiredJavaVersion;
274
275    /**
276     * The required Maven version to set in the plugin descriptor. This is evaluated by Maven 4 and ignored by earlier
277     * Maven versions. Can be either one of the following formats:
278     *
279     * <ul>
280     * <li>A version range which specifies the supported Maven versions. It can either use the usual mathematical
281     * 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
282     * form for {@code "[2.2.1,)"}, i.e. denotes the minimum version required.</li>
283     * <li>{@code "auto"} to determine the minimum Maven version from the POM's Maven prerequisite, or if not set the
284     * referenced Maven Plugin API version.</li>
285     * </ul>
286     * This value takes precedence over the
287     * <a href="https://maven.apache.org/pom.html#Prerequisites">POM's Maven prerequisite</a> in Maven 4.
288     *
289     * @since 3.8.0
290     */
291    @Parameter(defaultValue = VALUE_AUTO)
292    String requiredMavenVersion;
293
294    private final MavenSession mavenSession;
295
296    /**
297     * The component used for scanning the source tree for mojos.
298     */
299    private final MojoScanner mojoScanner;
300
301    protected final BuildContext buildContext;
302
303    @Inject
304    public DescriptorGeneratorMojo(
305            MavenProject project, MavenSession mavenSession, MojoScanner mojoScanner, BuildContext buildContext) {
306        super(project);
307        this.mavenSession = mavenSession;
308        this.mojoScanner = mojoScanner;
309        this.buildContext = buildContext;
310    }
311
312    public void generate() throws MojoExecutionException {
313
314        if (!"maven-plugin".equalsIgnoreCase(project.getArtifactId())
315                && project.getArtifactId().toLowerCase().startsWith("maven-")
316                && project.getArtifactId().toLowerCase().endsWith("-plugin")
317                && !"org.apache.maven.plugins".equals(project.getGroupId())) {
318            getLog().warn(LS + LS + "Artifact Ids of the format maven-___-plugin are reserved for" + LS
319                    + "plugins in the Group Id org.apache.maven.plugins" + LS
320                    + "Please change your artifactId to the format ___-maven-plugin" + LS
321                    + "In the future this error will break the build." + LS + LS);
322        }
323
324        if (skipDescriptor) {
325            getLog().warn("Execution skipped");
326            return;
327        }
328
329        if (checkExpectedProvidedScope) {
330            Set<Artifact> wrongScopedArtifacts = dependenciesNotInProvidedScope();
331            if (!wrongScopedArtifacts.isEmpty()) {
332                StringBuilder message = new StringBuilder(
333                        LS + LS + "Some dependencies of Maven Plugins are expected to be in provided scope." + LS
334                                + "Please make sure that dependencies listed below declared in POM" + LS
335                                + "have set '<scope>provided</scope>' as well." + LS + LS
336                                + "The following dependencies are in wrong scope:" + LS);
337                for (Artifact artifact : wrongScopedArtifacts) {
338                    message.append(" * ").append(artifact).append(LS);
339                }
340                message.append(LS).append(LS);
341
342                getLog().warn(message.toString());
343            }
344        }
345
346        mojoScanner.setActiveExtractors(extractors);
347
348        // TODO: could use this more, eg in the writing of the plugin descriptor!
349        PluginDescriptor pluginDescriptor = new PluginDescriptor();
350
351        pluginDescriptor.setGroupId(project.getGroupId());
352
353        pluginDescriptor.setArtifactId(project.getArtifactId());
354
355        pluginDescriptor.setVersion(project.getVersion());
356
357        pluginDescriptor.setGoalPrefix(goalPrefix);
358
359        pluginDescriptor.setName(project.getName());
360
361        pluginDescriptor.setDescription(project.getDescription());
362
363        if (encoding == null || encoding.length() < 1) {
364            getLog().warn("Using platform encoding (" + ReaderFactory.FILE_ENCODING
365                    + " actually) to read mojo source files, i.e. build is platform dependent!");
366        } else {
367            getLog().info("Using '" + encoding + "' encoding to read mojo source files.");
368        }
369
370        if (internalJavadocBaseUrl != null && !internalJavadocBaseUrl.getPath().endsWith("/")) {
371            throw new MojoExecutionException("Given parameter 'internalJavadocBaseUrl' must end with a slash but is '"
372                    + internalJavadocBaseUrl + "'");
373        }
374        try {
375            List<ComponentDependency> deps = GeneratorUtils.toComponentDependencies(project.getArtifacts());
376            pluginDescriptor.setDependencies(deps);
377
378            PluginToolsRequest request = new DefaultPluginToolsRequest(project, pluginDescriptor);
379            request.setEncoding(encoding);
380            request.setSkipErrorNoDescriptorsFound(skipErrorNoDescriptorsFound);
381            request.setDependencies(filterMojoDependencies());
382            request.setRepoSession(mavenSession.getRepositorySession());
383            request.setInternalJavadocBaseUrl(internalJavadocBaseUrl);
384            request.setInternalJavadocVersion(internalJavadocVersion);
385            request.setExternalJavadocBaseUrls(externalJavadocBaseUrls);
386            request.setSettings(mavenSession.getSettings());
387            request.setExcludedScanDirectories(excludedScanDirectories);
388
389            mojoScanner.populatePluginDescriptor(request);
390            request.setPluginDescriptor(extendPluginDescriptor(request));
391
392            outputDirectory.mkdirs();
393
394            ValidateComponentRequirement validateComponentRequirement = new ValidateComponentRequirement();
395            validateComponentRequirement.validate(request.getPluginDescriptor(), getLog());
396
397            PluginDescriptorFilesGenerator pluginDescriptorGenerator = new PluginDescriptorFilesGenerator();
398            pluginDescriptorGenerator.execute(outputDirectory, request);
399
400            buildContext.refresh(outputDirectory);
401        } catch (GeneratorException e) {
402            throw new MojoExecutionException("Error writing plugin descriptor", e);
403        } catch (InvalidPluginDescriptorException | ExtractionException e) {
404            throw new MojoExecutionException(
405                    "Error extracting plugin descriptor: '" + e.getLocalizedMessage() + "'", e);
406        } catch (LinkageError e) {
407            throw new MojoExecutionException(
408                    "The API of the mojo scanner is not compatible with this plugin version."
409                            + " Please check the plugin dependencies configured"
410                            + " in the POM and ensure the versions match.",
411                    e);
412        }
413    }
414
415    private PluginDescriptor extendPluginDescriptor(PluginToolsRequest request) {
416        PluginDescriptor pluginDescriptor = request.getPluginDescriptor();
417        pluginDescriptor.setRequiredMavenVersion(getRequiredMavenVersion(request));
418        return PluginDescriptorHelper.setRequiredJavaVersion(pluginDescriptor, getRequiredJavaVersion(request));
419    }
420
421    private String getRequiredMavenVersion(PluginToolsRequest request) {
422        if (!VALUE_AUTO.equals(requiredMavenVersion)) {
423            return requiredMavenVersion;
424        }
425        getLog().debug("Trying to derive Maven version automatically from project prerequisites...");
426        String requiredMavenVersion =
427                project.getPrerequisites() != null ? project.getPrerequisites().getMaven() : null;
428        if (requiredMavenVersion == null) {
429            getLog().debug("Trying to derive Maven version automatically from referenced Maven Plugin API artifact "
430                    + "version...");
431            requiredMavenVersion = request.getUsedMavenApiVersion();
432        }
433        if (requiredMavenVersion == null) {
434            getLog().warn("Cannot determine the required Maven version automatically, it is recommended to "
435                    + "configure some explicit value manually.");
436        }
437        return requiredMavenVersion;
438    }
439
440    private String getRequiredJavaVersion(PluginToolsRequest request) {
441        if (!VALUE_AUTO.equals(requiredJavaVersion)) {
442            return requiredJavaVersion;
443        }
444        String minRequiredJavaVersion = request.getRequiredJavaVersion();
445        if (minRequiredJavaVersion == null) {
446            getLog().warn("Cannot determine the minimally required Java version automatically, it is recommended to "
447                    + "configure some explicit value manually.");
448            return null;
449        }
450
451        return minRequiredJavaVersion;
452    }
453
454    /**
455     * Collects all dependencies expected to be in "provided" scope but are NOT in "provided" scope.
456     */
457    private Set<Artifact> dependenciesNotInProvidedScope() {
458        LinkedHashSet<Artifact> wrongScopedDependencies = new LinkedHashSet<>();
459
460        for (Artifact dependency : project.getArtifacts()) {
461            String ga = dependency.getGroupId() + ":" + dependency.getArtifactId();
462            if (expectedProvidedScopeGroupIds.contains(dependency.getGroupId())
463                    && !expectedProvidedScopeExclusions.contains(ga)
464                    && !Artifact.SCOPE_PROVIDED.equals(dependency.getScope())) {
465                wrongScopedDependencies.add(dependency);
466            }
467        }
468
469        return wrongScopedDependencies;
470    }
471
472    /**
473     * Get dependencies filtered with mojoDependencies configuration.
474     *
475     * @return eventually filtered dependencies, or even <code>null</code> if configured with empty mojoDependencies
476     * list
477     * @see #mojoDependencies
478     */
479    private Set<Artifact> filterMojoDependencies() {
480        Set<Artifact> filteredArtifacts;
481        if (mojoDependencies == null) {
482            filteredArtifacts = new LinkedHashSet<>(project.getArtifacts());
483        } else if (mojoDependencies.isEmpty()) {
484            filteredArtifacts = null;
485        } else {
486            filteredArtifacts = new LinkedHashSet<>();
487
488            ArtifactFilter filter = new IncludesArtifactFilter(mojoDependencies);
489
490            for (Artifact artifact : project.getArtifacts()) {
491                if (filter.include(artifact)) {
492                    filteredArtifacts.add(artifact);
493                }
494            }
495        }
496
497        return filteredArtifacts;
498    }
499}