| ------ |
| Using Plugin Tools Java5 Annotations |
| ------ |
| Olivier Lamy |
| ------ |
| 2012-05-14 |
| ------ |
| |
| ~~ 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: |
| ~~ https://maven.apache.org/doxia/references/apt-format.html |
| |
| Using Plugin Tools Java5 Annotations |
| |
| Since version 3.0 of the maven-plugin-plugin, you can use Java5 annotations to generate the |
| plugin descriptor file. |
| |
| <<NOTE>> With annotations, your Mojo super class does not any more require to be in the same project. Provided that the super class also uses annotations, it |
| can now come from reactor projects or external dependencies. As javadoc doclet are still useful for <<<@since>>>, <<<@deprecated>>> and comments, |
| the sources are still scanned. So if you use an external dependency, you must still provide an artifact with sources (<<<sources>>> classifier) to |
| provide documentation (the tooling will skip error if this artifact sources is missing). |
| |
| * Annotations |
| |
| Information for plugin descriptor generation is specified using 4 annotations: |
| |
| * 2 class-level annotations: |
| |
| * <<<@Mojo>>>: This annotation will mark your class as a Mojo, |
| |
| * <<<@Execute>>>: Used if your Mojo needs to fork a lifecycle, |
| |
| [] |
| |
| * 2 field-level annotations: |
| |
| * <<<@Parameter>>>: Used to configure your Mojo parameters, |
| |
| * <<<@Component>>>: Used to configure injection of Plexus components or Maven context components. |
| |
| [] |
| |
| [] |
| |
| For more information on these annotations, see the |
| {{{../../maven-plugin-tools-annotations/index.html#Supported_Annotations}corresponding documentation}}. |
| |
| Notice that Plugin Tools Java 5 Annotations are named after Plugin Tools Javadoc Tags |
| with following little differences: |
| |
| *-------------------------------+---------------+ |
| || {{{../../maven-plugin-tools-java/index.html}Plugin Tools Javadoc Tags}} || {{{../../maven-plugin-tools-annotations/index.html}Plugin Tools Java 5 Annotation}} || |
| *-------------------------------+---------------+ |
| | <<<@goal "goal-name">>> | <<<@Mojo( name = "goal-name" )>>> |
| *-------------------------------+---------------+ |
| | <<<@phase "\<phase-name\>">>> | <<<@Mojo( defaultPhase = LifecyclePhase.\<phase\> )>>> |
| *-------------------------------+---------------+ |
| |
| * POM configuration |
| |
| To be able to use these Java 5 annotations, you need to add some configuration to your plugin POM: |
| |
| * add <<<maven-plugin-annotations>>> dependency, preferably with <<<provided>>> scope, |
| |
| * override Maven core's <<<default-descriptor>>> execution phase to <<<process-classes>>>, |
| |
| [] |
| |
| +-----+ |
| <project> |
| ... |
| <packaging>maven-plugin</packaging> |
| ... |
| <dependencies> |
| <!-- dependencies to annotations --> |
| <dependency> |
| <groupId>org.apache.maven.plugin-tools</groupId> |
| <artifactId>maven-plugin-annotations</artifactId> |
| <version>${project.version}</version> |
| <scope>provided</scope><!-- annotations are needed only to build the plugin --> |
| </dependency> |
| </dependencies> |
| ... |
| <build> |
| <plugins> |
| <plugin> |
| <groupId>org.apache.maven.plugins</groupId> |
| <artifactId>maven-plugin-plugin</artifactId> |
| <version>${project.version}</version> |
| <executions> |
| <execution> |
| <id>default-descriptor</id> |
| <phase>process-classes</phase> |
| </execution> |
| <!-- if you want to generate help goal --> |
| <execution> |
| <id>help-goal</id> |
| <goals> |
| <goal>helpmojo</goal> |
| </goals> |
| </execution> |
| </executions> |
| </plugin> |
| </plugins> |
| ... |
| </build> |
| ... |
| </project> |
| +-----+ |
| |
| <Notice>: this configuration will not work with Maven 2, which does not support execution phase overriding. |
| If you absolutely need to build with Maven 2, you should use <<<skipErrorNoDescriptorsFound>>> parameter |
| to avoid failure on default execution phase and add another execution: |
| |
| +-----+ |
| <project> |
| ... |
| <profiles> |
| <profile> |
| <id>maven-2</id> |
| <activation> |
| <file> |
| <!-- This employs that the basedir expression is only recognized by Maven 3.x (see MNG-2363) --> |
| <missing>${basedir}</missing> |
| </file> |
| </activation> |
| <build> |
| <plugins> |
| <plugin> |
| <groupId>org.apache.maven.plugins</groupId> |
| <artifactId>maven-plugin-plugin</artifactId> |
| <configuration> |
| <!-- see https://issues.apache.org/jira/browse/MNG-5346 --> |
| <skipErrorNoDescriptorsFound>true</skipErrorNoDescriptorsFound> |
| </configuration> |
| <executions> |
| <execution> |
| <id>mojo-descriptor</id> |
| <goals> |
| <goal>descriptor</goal> |
| </goals> |
| </execution> |
| </executions> |
| </plugin> |
| </plugins> |
| </build> |
| </profile> |
| </profiles> |
| </project> |
| +-----+ |