| ------ |
| 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 Java Annotations |
| |
| You can use Java annotations to generate the plugin descriptor file. |
| |
| <<NOTE>> With annotations, your Mojo super class does not have to be in the same project: provided that the superclass also uses annotations, it |
| can now come from reactor projects or external dependencies. By default all dependencies are scanned, but this can be reduced with the <<<mojoDependencies>>> |
| parameter. BUT as javadoc doclets are still useful for goals and parameters description, <<<@since>>> and <<<@deprecated>>>, 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, |
| |
| [] |
| |
| * 1 field or method level annotations: |
| |
| * <<<@Parameter>>>: Used to configure your Mojo parameters, |
| |
| [] |
| |
| * 1 field level annotations: |
| |
| * <<<@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 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 Annotation}} || |
| *-------------------------------+---------------+ |
| | <<<@goal "goal-name">>> | <<<@Mojo( name = "goal-name" )>>> |
| *-------------------------------+---------------+ |
| | <<<@phase "\<phase-name\>">>> | <<<@Mojo( defaultPhase = LifecyclePhase.\<phase\> )>>> |
| *-------------------------------+---------------+ |
| |
| * POM configuration |
| |
| To use these Java annotations, add a dependency on |
| <<<maven-plugin-annotations>>> to your pom, preferably with <<<provided>>> scope. |
| |
| +-----+ |
| <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 not used at runtime because @Retention(value=CLASS), they 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> |
| <!-- if you want to generate help goal --> |
| <execution> |
| <id>help-goal</id> |
| <goals> |
| <goal>helpmojo</goal> |
| </goals> |
| </execution> |
| </executions> |
| </plugin> |
| </plugins> |
| ... |
| </build> |
| ... |
| </project> |
| +-----+ |