 ------
 Introduction
 ------
 Hervé Boutemy
 ------
 2012-05-12
 ------

~~ 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.

~~ NOTE: For help with the syntax of this file, see:
~~ http://maven.apache.org/doxia/references/apt-format.html

Maven Plugin Tool for Annotations

 The Maven Plugin Tool for Annotations is the <<<java-annotations>>> implementation of
 {{{../maven-plugin-tools-api/index.html}maven-plugin-tools-api}}
 to extract descriptors from plugins written in Java with
 {{{../maven-plugin-annotations/index.html}Maven Plugin Tools Java Annotations}}.

* Supported Annotations

+---------+
import org.apache.maven.execution.MavenSession;
import org.apache.maven.plugin.AbstractMojo;
import org.apache.maven.plugin.MojoExecution;
import org.apache.maven.plugin.descriptor.PluginDescriptor;
import org.apache.maven.plugins.annotations.Execute;
import org.apache.maven.plugins.annotations.InstantiationStrategy;
import org.apache.maven.plugins.annotations.LifecyclePhase;
import org.apache.maven.plugins.annotations.Mojo;
import org.apache.maven.plugins.annotations.Parameter;
import org.apache.maven.plugins.annotations.ResolutionScope;
import org.apache.maven.project.MavenProject;
import org.apache.maven.settings.Settings;

/**
 * Mojo Description. @Mojo( name = "<goal-name>" ) is the minimal required annotation.
 *
 * @since <since-text>
 * @deprecated <deprecated-text>
 */
@Mojo( name = "<goal-name>",
       aggregator = <false|true>, 
       configurator = "<role hint>",
       executionStrategy = "<once-per-session|always>", // (unsupported since Maven 3.0)
       inheritByDefault = <true|false>, // (unsupported since Maven 3.0)
       instantiationStrategy = InstantiationStrategy.<strategy>,
       defaultPhase = LifecyclePhase.<phase>,
       requiresDependencyResolution = ResolutionScope.<scope>,
       requiresDependencyCollection = ResolutionScope.<scope>, // (since Maven 3.0)
       requiresDirectInvocation = <false|true>, // (unsupported since Maven 3.0)
       requiresOnline = <false|true>,
       requiresProject = <true|false>,
       requiresReports = <false|true>, // (unsupported since Maven 3.0)
       threadSafe = <false|true> ) // (since Maven 3.0)
@Execute( goal = "<goal-name>",
          phase = LifecyclePhase.<phase>,
          lifecycle = "<lifecycle-id>" )
public class MyMojo
    extends AbstractMojo
{
    /**
     * Parameter description.
     *
     * @since <since-text>
     * @deprecated <deprecated-text>
     */
    @Parameter( name = "parameter",
                alias = "myAlias",
                property = "a.property",
                defaultValue = "an expression, possibly with ${variables} and pseudo-parameter expressions ${project.xxx.yyy}",
                readonly = <false|true>,
                required = <false|true> )
    private String parameter;

    @Parameter( defaultValue = "${reactorProjects}", readonly = true )
    // prefer using session.getProjects()
    private List<MavenProject> reactorProjects;

    @Parameter( defaultValue = "${plugin}", readonly = true ) // Maven 3 only
    // prefer using mojoExecution.getMojoDescriptor()
    private PluginDescriptor plugin;

    @Parameter( defaultValue = "${settings}", readonly = true )
    // prefer using session.getSettings()
    private Settings settings;

    @Parameter( defaultValue = "${project.basedir}", readonly = true )
    // prefer using project.getBasedir()
    private File basedir;

    @Parameter( defaultValue = "${project.build.directory}", readonly = true )
    // prefer using project.getBuild().getDirectory()
    private File target;

    // pseudo-parameters (marked read-only) permitting injection of Maven build context objects
    // sample objects taken from Maven API through PluginParameterExpressionEvaluator
    //     https://maven.apache.org/ref/current/maven-core/apidocs/org/apache/maven/plugin/PluginParameterExpressionEvaluator.html
    // plugins targeting Maven 3.2.5+ (after MNG-5695) should not use these pseudo-parameters any more,
    // but @Inject and Maven APIs to get better compiler-time checks

    private final MyComponent component;

    private final MavenSession session;

    private final MavenProject project;

    private final MojoExecution mojoExecution;

    @Inject
    public MyMojo(MyComponent component, MavenSession session, MavenProject project, MojoExecution mojoExecution) {
        this.component = component;
        this.session = session;
        this.project = project;
        this.mojoExecution = mojoExecution;
    }

    /**
     * @Parameter for methods can be used only with public setter methods
    */
    @Parameter( ... )
    public setOutput( File output )
    {
        ...
    }

    public void execute()
    {
        ...
    }
}
+---------+


* See also

 * {{{../maven-plugin-annotations/index.html}Maven Plugin Tools Java Annotations}}

 * {{{/developers/mojo-api-specification.html#The_Descriptor_and_Annotations}Mojo API Specification}}

 * {{{/ref/current/maven-plugin-api/plugin.html}META-INF/maven/plugin.xml plugin descriptor}}

 * {{{/ref/current/maven-core/apidocs/org/apache/maven/plugin/PluginParameterExpressionEvaluator.html}PluginParameterExpressionEvaluator}},
   used to evaluate plugin parameters values during Mojo configuration,

 * pseudo parameters:

   * <<<PluginParameterExpressionEvaluator>>> {{{https://maven.apache.org/ref/current/maven-core/apidocs/org/apache/maven/plugin/PluginParameterExpressionEvaluator.html}javadoc}} /
   {{{https://maven.apache.org/ref/current/maven-core/xref/org/apache/maven/plugin/PluginParameterExpressionEvaluator.html}source}}

   * {{{https://issues.apache.org/jira/browse/MNG-5695}MNG-5695}}: scoped objects added to Guice/Sisu in {{{https://maven.apache.org/ref/current/maven-core/}maven-core}} 3.2.5
