Starting with Maven 2.0, plugins can be written in Java or any of a - number of scripting languages. Additionally, Maven tries to stay out of - the way of the programmer with its new Mojo API. This opens up the - opportunity for many Mojos to be reused outside of Maven, or bridged - into Maven from external systems like Ant.
-NOTE: For now, we will limit the discussion to Java-based Mojos, since - each scripting language will present these same basic requirements with - various forms of implementation.
-Although the requirements on Mojos are minimal by design, there are
- still a very few requirements that Mojo developers must keep in mind. Basically, these Mojo requirements are embodied by the
- org.apache.maven.plugin.Mojo
- interface, which the Mojo
- must implement (or else extend its abstract base class counterpart
- org.apache.maven.plugin.AbstractMojo
- ). This interface
- guarantees the correct execution contract for the Mojo: no parameters,
- void return type, and a throws clause that allows only
- org.apache.maven.plugin.MojoExecutionException
- and its
- derivatives. It also guarantees that the Mojo will have access to the
- standard Maven user-feedback mechanism,
- org.apache.maven.monitor.logging.Log
- , so the Mojo can
- communicate important events to the console or other log sink.
-
As mentioned before, each Plugin - or packaged set of Mojos - must
- provide a descriptor called
- plugin.xml
- under the path
- META-INF/maven
- inside the Plugin jar file. Fortunately,
- Maven also provides a set of Javadoc annotations and tools to generate
- this descriptor, so developers don't have to worry about directly
- authoring or maintaining a separate XML metadata file.
-
To serve as a quick reference for the developer, the rest of this page - will document these features (the API, along with the annotations) - which are considered the best practice for developing Mojos.
-This interface forms the contract required for Mojos to interact
- with the Maven infrastructure. It features an
- execute()
- method, which triggers the Mojo's build-process behavior, and can
- throw a
- MojoExecutionException
- if an error condition
- occurs. See below for a discussion on proper use of this
- Exception
- class. Also included is the
- setLog(..)
- method, which simply allows Maven to inject a
- logging mechanism which will allow the Mojo to communicate to the
- outside world through standard Maven channels.
-
-
- void setLog( org.apache.maven.monitor.logging.Log )
-
- Inject a standard Maven logging mechanism to allow this Mojo - to communicate events and feedback to the user.
-
- void execute() throws org.apache.maven.plugin.MojoExecutionException
-
- Perform whatever build-process behavior this Mojo implements.
- This is the main trigger for the Mojo inside the Maven system,
- and allows the Mojo to communicate fatal errors by throwing an
- instance of
- MojoExecutionException
- .
-
The
- MojoExecutionException
- (and all error
- conditions inside the Mojo) should be handled very carefully.
- The simple wrapping of lower-level exceptions without providing
- any indication of a user-friendly probable cause is strictly
- discouraged. In fact, a much better course of action is to
- provide error handling code (try/catch stanzas) for each
- coherent step within the Mojo's execution. Developers are then
- in a much better position to diagnose the cause of any error,
- and provide user-friendly feedback in the message of the
- MojoExecutionException
- .
-
Currently, this abstract base class simply takes care of managing
- the Maven log for concrete derivations. In keeping with this, it
- provides a
- protected
- method,
- getLog():Log
- ,
- to furnish Log access to these concrete implementations.
-
-
- public void setLog( org.apache.maven.monitor.logging.Log )
-
- - [IMPLEMENTED] -
-Inject a standard Maven logging mechanism to allow this Mojo - to communicate events and feedback to the user.
-protected Log getLog()
- - [IMPLEMENTED] -
-Furnish access to the standard Maven logging mechanism which - is managed in this base class.
-
- void execute() throws org.apache.maven.plugin.MojoExecutionException
-
- - [ABSTRACT] -
-Perform whatever build-process behavior this Mojo implements.
- See the documentation for
- Mojo
- above for more
- information.
-
This interface supplies the API for providing feedback to the user
- from the Mojo, using standard Maven channels. There should be no big
- surprises here, although you may notice that the methods accept
- java.lang.CharSequence
- rather than
- java.lang.String
- . This is provided mainly as a
- convenience, to enable developers to pass things like
- StringBuffer
- directly into the logger, rather than
- formatting first by calling
- toString()
- .
-
-
void debug( java.lang.CharSequence )
- Send a message to the user in the - debug - error level. -
-
- void debug( java.lang.CharSequence, java.lang.Throwable )
-
- Send a message (and accompanying exception) to the user in the - debug - error level. The error's stacktrace will be output - when this error level is enabled. -
-void debug( java.lang.Throwable )
- Send an exception to the user in the - debug - error level. - The stack trace for this exception will be output when this - error level is enabled. -
-void info( java.lang.CharSequence )
- Send a message to the user in the - info - error level. -
-
- void info( java.lang.CharSequence, java.lang.Throwable )
-
- Send a message (and accompanying exception) to the user in the - info - error level. The error's stacktrace will be output - when this error level is enabled. -
-void info( java.lang.CharSequence )
- Send an exception to the user in the - info - error level. - The stack trace for this exception will be output when this - error level is enabled. -
-void warn( java.lang.CharSequence )
- Send a message to the user in the - warn - error level. -
-
- void warn( java.lang.CharSequence, java.lang.Throwable )
-
- Send a message (and accompanying exception) to the user in the - warn - error level. The error's stacktrace will be output - when this error level is enabled. -
-void warn( java.lang.CharSequence )
- Send an exception to the user in the - warn - error level. - The stack trace for this exception will be output when this - error level is enabled. -
-void error( java.lang.CharSequence )
- Send a message to the user in the - error - error level. -
-
- void error( java.lang.CharSequence, java.lang.Throwable )
-
- Send a message (and accompanying exception) to the user in the - error - error level. The error's stacktrace will be output - when this error level is enabled. -
-void error( java.lang.CharSequence )
- Send an exception to the user in the - error - error level. - The stack trace for this exception will be output when this - error level is enabled. -
-In addition to the normal Java requirements in terms of interfaces - and/or abstract base classes which need to be implemented, a plugin - descriptor must accompany these classes inside the plugin jar. This - descriptor file is used to provide metadata about the parameters and - other component requirements for a set of Mojos so that Maven can - initialize the Mojo and validate its configuration before executing - it. As such, the plugin descriptor has a certain set of information - that is required for each Mojo specification to be valid, as well as - requirements for the overall plugin descriptor itself.
-NOTE: In the following discussion, bolded items are the descriptor's - element name along with a Javadoc annotation (if applicable) supporting - that piece of the plugin descriptor. A couple of examples are: - someElement - (@annotation parameterName="parameterValue") - or - someOtherElement (@annotation <rawAnnotationValue>) - . -
-The plugin descriptor must be provided in a jar resource with the
- path:
- META-INF/maven/plugin.xml
- , and it must contain the
- following:
-
-
| Descriptor Element | -Required? | -Notes | -
|---|---|---|
| mojos | -Yes | -Descriptors for each Mojo provided by the plugin, each inside a - mojo - sub-element. Mojo descriptors are covered in detail - below. Obviously, a plugin without any declared Mojos doesn't - make sense, so the - mojos - element is required, along with - at least one - mojo - sub-element. - | -
| dependencies | -Yes | -A set of dependencies which the plugin requires in order to
- function. Each dependency is provided inside a
- dependency
- sub-element. Dependency specifications are covered below. Since
- all plugins must have a dependency on
- maven-plugin-api
- , this element is effectively
- required.
- Using the plugin toolset, these dependencies can be
- extracted from the POM's dependencies.
- |
-
Each Mojo specified inside a plugin descriptor must provide the - following (annotations specified here are at the class level):
--
| Descriptor Element | -Annotation | -Required? | -Notes | -
|---|---|---|---|
| goal | -@goal <goalName> | -Yes | -The name for the Mojo that users will reference from the - command line to execute the Mojo directly, or inside a POM in - order to provide Mojo-specific configuration. | -
| implementation | -none (detected) | -Yes | -The Mojo's fully-qualified class name (or script path in - the case of non-Java Mojos). | -
| language | -none (detected) | -No. Default:
- java
- |
- The implementation language for this Mojo (Java, - beanshell, etc.). | -
| configurator | -@configurator <roleHint> | -No | -The configurator type to use when injecting parameter values - into this Mojo. The value is normally deduced from the - Mojo's implementation language, but can be specified to - allow a custom ComponentConfigurator implementation to be used. - NOTE: This will only be used in very special - cases, using a highly controlled vocabulary of possible values. - (Elements like this are why it's a good idea to use the - descriptor tools.) - | -
| phase | -@phase <phaseName> | -No | -Binds this Mojo to a particular phase of the standard build - lifecycle, if specified. - NOTE: This is only required if this - Mojo is to participate in the standard build process. - | -
| execute | -@execute [phase=<phaseName>|goal=<goalName>] [lifecycle=<lifecycleId>] | -No | -When this goal is invoked, it will first invoke a parallel lifecycle, ending at the given phase.
- If a goal is provided instead of a phase, that goal will be executed in isolation. The execution of either
- will not affect the current project, but instead make available the
- ${executedProject}
- expression if required. An alternate lifecycle can also be provided: for more information see the
- documentation on the
- build lifecycle
- .
- |
-
| requiresDependencyResolution | -@requiresDependencyResolution <requiredScope> | -No | -Flags this Mojo as requiring the dependencies in the specified - scope (or an implied scope) to be resolved before it can execute. - NOTE: Currently supports - compile - , - runtime - , and - test - scopes. - - | -
| description | -none (detected) | -No | -The description of this Mojo's functionality. - Using the - toolset, this will be the class-level Javadoc description - provided. NOTE: While this is not a required part of the Mojo - specification, it SHOULD be provided to enable future - tool support for browsing, etc. and for clarity. - | -
| parameters | -N/A | -No | -Specifications for the parameters which this Mojo uses will be - provided in - parameter - sub-elements in this section. - NOTE: Parameters are discussed in more detail below. - | -
Each Mojo specifies the parameters that it expects in order to work. - These parameters are the Mojo's link to the outside world, and - will be satisfied through a combination of POM/project values, plugin - configurations (from the POM and configuration defaults), and System - properties.
-NOTE[1]: For this discussion on Mojo parameters, a single - annotation may span multiple elements in the descriptor's specification - for that parameter. Duplicate annotation declarations in this section - will be used to detail each parameter of an annotation separately.
-NOTE[2]: In many cases, simply annotating a Mojo field with - @parameter - will be enough to allow injection of a value for that - parameter using POM configuration elements. The discussion below - shows advanced usage for this annotation, along with others. -
-Each parameter for a Mojo must be specified in the - plugin descriptor as follows:
--
| Descriptor Element | -Annotation | -Required? | -Notes | -
|---|---|---|---|
| name | -none (detected) | -Yes | -The name of the parameter, to be used in configuring this - parameter from the Mojo's declared defaults (discussed below) or - from the POM. - Using the toolset, this is detected as the - Java field name. - | -
| alias | -@parameter alias="myAlias" | -No | -Specifies an alias which can be used to configure this - parameter from the POM. This is primarily useful to improve - user-friendliness, where Mojo field names are not intuitive to - the user or are otherwise not conducive to configuration via - the POM. | -
| type | -none (detected) | -Yes | -The Java type for this parameter. This is used to validate the - result of any expressions used to calculate the value which - should be injected into the Mojo for this parameter. - Using the - toolset, this is detected as the class of the Java field - corresponding to this parameter. - | -
| required | -@required | -No | -Whether this parameter is required for the Mojo to function. - This is used to validate the configuration for a Mojo before it - is injected, and before the Mojo is executed from some - half-state. - NOTE: Specification of this annotation flags - the parameter as required; there is no true/false value. - | -
| editable | -@readonly | -No | -Specifies that this parameter cannot be configured directly by - the user (as in the case of POM-specified configuration). This is - useful when you want to force the user to use common POM elements - rather than plugin configurations, as in the case where you want - to use the artifact's final name as a parameter. In this case, - you want the user to modify - <build><finalName/></build> rather than - specifying a value for finalName directly in the plugin - configuration section. It is also useful to ensure that - for - example - a List-typed parameter which expects items of type - Artifact doesn't get a List full of Strings. - NOTE: - Specification of this annotation flags the parameter as - non-editable; there is no true/false value. - | -
| description | -none (detected) | -No | -The description of this parameter's use inside the Mojo. - Using the toolset, this is detected as the Javadoc description - for the field. NOTE: While this is not a required part of the - parameter specification, it SHOULD be provided to enable future - tool support for browsing, etc. and for clarity. - | -
| configuration | -@parameter expression="${someExpression}" default-value="value" | -No | -Specifies the expression used to calculate the value to be
- injected into this parameter of the Mojo at buildtime. This is
- commonly used to refer to specific elements in the POM, such as
- ${project.build.resources}, which refers to the List of resources
- meant to accompany the classes in the resulting jar file.
- The default value is used when the expression evaluates to
- null
- .
- NOTE: If not specified, an expression of ${<name>} is
- assumed, which can only be satisfied from POM configuration or
- System properties. The use of '${' and '}' is required to delimit
- actual expressions which may be evaluated.
- |
-
| deprecated | -@deprecated | -No | -Marks a parameter as deprecated. The rules on deprecation are - the same as normal Java with language elements. This will trigger - a warning when a user tries to configure a parameter marked as - deprecated. | -
The final component of a plugin descriptor is the dependencies. This - enables the plugin to function independently of its POM (or at least - to declare the libraries it needs to run). Dependencies are taken from - the - runtime - scope of the plugin's calculated dependencies (from - the POM). Dependencies are specified in exactly the same manner as in - the POM, except for the <scope> element (all dependencies in the - plugin descriptor are assumed to be runtime, because this is a - runtime profile for the plugin). -
-By now, we've mentioned the plugin tools several times without telling - you what they are or how to use them. Instead of manually writing (and - maintaining) the metadata detailed above, Maven 2.0 ships with some - tools to aid in this task. In fact, the only thing a plugin developer - needs to do is declare his project to be a plugin from within the POM. - Once this is done, Maven will call the appropriate descriptor - generators, etc. to produce an artifact that is ready for use within - Maven builds. Optional metadata can be injected via Javadoc annotation - (and possibly JDK5 annotations in the future) as described above, - enabling richer interactions between the Mojo and the user. The - section below describes the changes to the POM which are necessary to - create plugin artifacts.
-From the POM, Maven plugin projects look quite similar to any other - project. For pure Java plugins, the differences are even smaller than - for script-based plugins. The following details the POM elements - which are necessary to build a Maven plugin artifact.
--
| POM Element | -Required for Java Mojos? | -Sample Declaration | -Notes | -
|---|---|---|---|
| packaging | -Yes | -
- <packaging>maven-plugin</packaging>
- |
- The POM must declare a packaging element which describes this - project as a Maven plugin project. | -
| scriptSourceDirectory | -No | -
- <scriptSourceDirectory>src/main/scripts</scriptSourceDirectory>
- |
- In the case of script-based Mojos (which are not covered in
- detail within this document), the POM must include an additional
- element to distinguish script sources from (optional) Java
- supporting classes. This element is scriptSourceDirectory,
- inside the build section. This directory is included in the list
- of resources which accompany any compiled code in the resulting
- artifact. It is specified separately from the resources in the
- build section to denote its special status as an alternate source
- directory for scripts. |
-
After making the changes above, the developer can simply call
-
-
- m2 install
-
-
- to install the plugin to
- the local repository. (Any of the other standard lifecycle targets like
- package, deploy, etc. are also available in like fashion.)
-
This section simply gives a listing of pointers for more - information.
--
- -Starting with Maven 2.0, plugins can be written in Java or any of a + number of scripting languages. Additionally, Maven tries to stay out of + the way of the programmer with its new Mojo API. This opens up the + opportunity for many Mojos to be reused outside of Maven, or bridged + into Maven from external systems like Ant.
+NOTE: For now, we will limit the discussion to Java-based Mojos, since + each scripting language will present these same basic requirements with + various forms of implementation.
+Although the requirements on Mojos are minimal by design, there are
+ still a very few requirements that Mojo developers must keep in mind. Basically, these Mojo requirements are embodied by the
+ org.apache.maven.plugin.Mojo
+ interface, which the Mojo
+ must implement (or else extend its abstract base class counterpart
+ org.apache.maven.plugin.AbstractMojo
+ ). This interface
+ guarantees the correct execution contract for the Mojo: no parameters,
+ void return type, and a throws clause that allows only
+ org.apache.maven.plugin.MojoExecutionException
+ and its
+ derivatives. It also guarantees that the Mojo will have access to the
+ standard Maven user-feedback mechanism,
+ org.apache.maven.monitor.logging.Log
+ , so the Mojo can
+ communicate important events to the console or other log sink.
+
As mentioned before, each Plugin - or packaged set of Mojos - must
+ provide a descriptor called
+ plugin.xml
+ under the path
+ META-INF/maven
+ inside the Plugin jar file. Fortunately,
+ Maven also provides a set of Javadoc annotations and tools to generate
+ this descriptor, so developers don't have to worry about directly
+ authoring or maintaining a separate XML metadata file.
+
To serve as a quick reference for the developer, the rest of this page + will document these features (the API, along with the annotations) + which are considered the best practice for developing Mojos.
+This interface forms the contract required for Mojos to interact
+ with the Maven infrastructure. It features an
+ execute()
+ method, which triggers the Mojo's build-process behavior, and can
+ throw a
+ MojoExecutionException
+ if an error condition
+ occurs. See below for a discussion on proper use of this
+ Exception
+ class. Also included is the
+ setLog(..)
+ method, which simply allows Maven to inject a
+ logging mechanism which will allow the Mojo to communicate to the
+ outside world through standard Maven channels.
+
+
+ void setLog( org.apache.maven.monitor.logging.Log )
+
+ Inject a standard Maven logging mechanism to allow this Mojo + to communicate events and feedback to the user.
+
+ void execute() throws org.apache.maven.plugin.MojoExecutionException
+
+ Perform whatever build-process behavior this Mojo implements.
+ This is the main trigger for the Mojo inside the Maven system,
+ and allows the Mojo to communicate fatal errors by throwing an
+ instance of
+ MojoExecutionException
+ .
+
The
+ MojoExecutionException
+ (and all error
+ conditions inside the Mojo) should be handled very carefully.
+ The simple wrapping of lower-level exceptions without providing
+ any indication of a user-friendly probable cause is strictly
+ discouraged. In fact, a much better course of action is to
+ provide error handling code (try/catch stanzas) for each
+ coherent step within the Mojo's execution. Developers are then
+ in a much better position to diagnose the cause of any error,
+ and provide user-friendly feedback in the message of the
+ MojoExecutionException
+ .
+
Currently, this abstract base class simply takes care of managing
+ the Maven log for concrete derivations. In keeping with this, it
+ provides a
+ protected
+ method,
+ getLog():Log
+ ,
+ to furnish Log access to these concrete implementations.
+
+
+ public void setLog( org.apache.maven.monitor.logging.Log )
+
+ + [IMPLEMENTED] +
+Inject a standard Maven logging mechanism to allow this Mojo + to communicate events and feedback to the user.
+protected Log getLog()
+ + [IMPLEMENTED] +
+Furnish access to the standard Maven logging mechanism which + is managed in this base class.
+
+ void execute() throws org.apache.maven.plugin.MojoExecutionException
+
+ + [ABSTRACT] +
+Perform whatever build-process behavior this Mojo implements.
+ See the documentation for
+ Mojo
+ above for more
+ information.
+
This interface supplies the API for providing feedback to the user
+ from the Mojo, using standard Maven channels. There should be no big
+ surprises here, although you may notice that the methods accept
+ java.lang.CharSequence
+ rather than
+ java.lang.String
+ . This is provided mainly as a
+ convenience, to enable developers to pass things like
+ StringBuffer
+ directly into the logger, rather than
+ formatting first by calling
+ toString()
+ .
+
+
void debug( java.lang.CharSequence )
+ Send a message to the user in the + debug + error level. +
+
+ void debug( java.lang.CharSequence, java.lang.Throwable )
+
+ Send a message (and accompanying exception) to the user in the + debug + error level. The error's stacktrace will be output + when this error level is enabled. +
+void debug( java.lang.Throwable )
+ Send an exception to the user in the + debug + error level. + The stack trace for this exception will be output when this + error level is enabled. +
+void info( java.lang.CharSequence )
+ Send a message to the user in the + info + error level. +
+
+ void info( java.lang.CharSequence, java.lang.Throwable )
+
+ Send a message (and accompanying exception) to the user in the + info + error level. The error's stacktrace will be output + when this error level is enabled. +
+void info( java.lang.CharSequence )
+ Send an exception to the user in the + info + error level. + The stack trace for this exception will be output when this + error level is enabled. +
+void warn( java.lang.CharSequence )
+ Send a message to the user in the + warn + error level. +
+
+ void warn( java.lang.CharSequence, java.lang.Throwable )
+
+ Send a message (and accompanying exception) to the user in the + warn + error level. The error's stacktrace will be output + when this error level is enabled. +
+void warn( java.lang.CharSequence )
+ Send an exception to the user in the + warn + error level. + The stack trace for this exception will be output when this + error level is enabled. +
+void error( java.lang.CharSequence )
+ Send a message to the user in the + error + error level. +
+
+ void error( java.lang.CharSequence, java.lang.Throwable )
+
+ Send a message (and accompanying exception) to the user in the + error + error level. The error's stacktrace will be output + when this error level is enabled. +
+void error( java.lang.CharSequence )
+ Send an exception to the user in the + error + error level. + The stack trace for this exception will be output when this + error level is enabled. +
+In addition to the normal Java requirements in terms of interfaces + and/or abstract base classes which need to be implemented, a plugin + descriptor must accompany these classes inside the plugin jar. This + descriptor file is used to provide metadata about the parameters and + other component requirements for a set of Mojos so that Maven can + initialize the Mojo and validate its configuration before executing + it. As such, the plugin descriptor has a certain set of information + that is required for each Mojo specification to be valid, as well as + requirements for the overall plugin descriptor itself.
+NOTE: In the following discussion, bolded items are the descriptor's + element name along with a Javadoc annotation (if applicable) supporting + that piece of the plugin descriptor. A couple of examples are: + someElement + (@annotation parameterName="parameterValue") + or + someOtherElement (@annotation <rawAnnotationValue>) + . +
+The plugin descriptor must be provided in a jar resource with the
+ path:
+ META-INF/maven/plugin.xml
+ , and it must contain the
+ following:
+
+
| Descriptor Element | +Required? | +Notes | +
|---|---|---|
| mojos | +Yes | +Descriptors for each Mojo provided by the plugin, each inside a + mojo + sub-element. Mojo descriptors are covered in detail + below. Obviously, a plugin without any declared Mojos doesn't + make sense, so the + mojos + element is required, along with + at least one + mojo + sub-element. + | +
| dependencies | +Yes | +A set of dependencies which the plugin requires in order to
+ function. Each dependency is provided inside a
+ dependency
+ sub-element. Dependency specifications are covered below. Since
+ all plugins must have a dependency on
+ maven-plugin-api
+ , this element is effectively
+ required.
+ Using the plugin toolset, these dependencies can be
+ extracted from the POM's dependencies.
+ |
+
Each Mojo specified inside a plugin descriptor must provide the + following (annotations specified here are at the class level):
++
| Descriptor Element | +Annotation | +Required? | +Notes | +
|---|---|---|---|
| goal | +@goal <goalName> | +Yes | +The name for the Mojo that users will reference from the + command line to execute the Mojo directly, or inside a POM in + order to provide Mojo-specific configuration. | +
| implementation | +none (detected) | +Yes | +The Mojo's fully-qualified class name (or script path in + the case of non-Java Mojos). | +
| language | +none (detected) | +No. Default:
+ java
+ |
+ The implementation language for this Mojo (Java, + beanshell, etc.). | +
| configurator | +@configurator <roleHint> | +No | +The configurator type to use when injecting parameter values + into this Mojo. The value is normally deduced from the + Mojo's implementation language, but can be specified to + allow a custom ComponentConfigurator implementation to be used. + NOTE: This will only be used in very special + cases, using a highly controlled vocabulary of possible values. + (Elements like this are why it's a good idea to use the + descriptor tools.) + | +
| phase | +@phase <phaseName> | +No | +Binds this Mojo to a particular phase of the standard build + lifecycle, if specified. + NOTE: This is only required if this + Mojo is to participate in the standard build process. + | +
| execute | +@execute [phase=<phaseName>|goal=<goalName>] [lifecycle=<lifecycleId>] | +No | +When this goal is invoked, it will first invoke a parallel lifecycle, ending at the given phase.
+ If a goal is provided instead of a phase, that goal will be executed in isolation. The execution of either
+ will not affect the current project, but instead make available the
+ ${executedProject}
+ expression if required. An alternate lifecycle can also be provided: for more information see the
+ documentation on the
+ build lifecycle
+ .
+ |
+
| requiresDependencyResolution | +@requiresDependencyResolution <requiredScope> | +No | +Flags this Mojo as requiring the dependencies in the specified + scope (or an implied scope) to be resolved before it can execute. + NOTE: Currently supports + compile + , + runtime + , and + test + scopes. + + | +
| description | +none (detected) | +No | +The description of this Mojo's functionality. + Using the + toolset, this will be the class-level Javadoc description + provided. NOTE: While this is not a required part of the Mojo + specification, it SHOULD be provided to enable future + tool support for browsing, etc. and for clarity. + | +
| parameters | +N/A | +No | +Specifications for the parameters which this Mojo uses will be + provided in + parameter + sub-elements in this section. + NOTE: Parameters are discussed in more detail below. + | +
Each Mojo specifies the parameters that it expects in order to work. + These parameters are the Mojo's link to the outside world, and + will be satisfied through a combination of POM/project values, plugin + configurations (from the POM and configuration defaults), and System + properties.
+NOTE[1]: For this discussion on Mojo parameters, a single + annotation may span multiple elements in the descriptor's specification + for that parameter. Duplicate annotation declarations in this section + will be used to detail each parameter of an annotation separately.
+NOTE[2]: In many cases, simply annotating a Mojo field with + @parameter + will be enough to allow injection of a value for that + parameter using POM configuration elements. The discussion below + shows advanced usage for this annotation, along with others. +
+Each parameter for a Mojo must be specified in the + plugin descriptor as follows:
++
| Descriptor Element | +Annotation | +Required? | +Notes | +
|---|---|---|---|
| name | +none (detected) | +Yes | +The name of the parameter, to be used in configuring this + parameter from the Mojo's declared defaults (discussed below) or + from the POM. + Using the toolset, this is detected as the + Java field name. + | +
| alias | +@parameter alias="myAlias" | +No | +Specifies an alias which can be used to configure this + parameter from the POM. This is primarily useful to improve + user-friendliness, where Mojo field names are not intuitive to + the user or are otherwise not conducive to configuration via + the POM. | +
| type | +none (detected) | +Yes | +The Java type for this parameter. This is used to validate the + result of any expressions used to calculate the value which + should be injected into the Mojo for this parameter. + Using the + toolset, this is detected as the class of the Java field + corresponding to this parameter. + | +
| required | +@required | +No | +Whether this parameter is required for the Mojo to function. + This is used to validate the configuration for a Mojo before it + is injected, and before the Mojo is executed from some + half-state. + NOTE: Specification of this annotation flags + the parameter as required; there is no true/false value. + | +
| editable | +@readonly | +No | +Specifies that this parameter cannot be configured directly by + the user (as in the case of POM-specified configuration). This is + useful when you want to force the user to use common POM elements + rather than plugin configurations, as in the case where you want + to use the artifact's final name as a parameter. In this case, + you want the user to modify + <build><finalName/></build> rather than + specifying a value for finalName directly in the plugin + configuration section. It is also useful to ensure that - for + example - a List-typed parameter which expects items of type + Artifact doesn't get a List full of Strings. + NOTE: + Specification of this annotation flags the parameter as + non-editable; there is no true/false value. + | +
| description | +none (detected) | +No | +The description of this parameter's use inside the Mojo. + Using the toolset, this is detected as the Javadoc description + for the field. NOTE: While this is not a required part of the + parameter specification, it SHOULD be provided to enable future + tool support for browsing, etc. and for clarity. + | +
| configuration | +@parameter expression="${someExpression}" default-value="value" | +No | +Specifies the expression used to calculate the value to be
+ injected into this parameter of the Mojo at buildtime. This is
+ commonly used to refer to specific elements in the POM, such as
+ ${project.build.resources}, which refers to the List of resources
+ meant to accompany the classes in the resulting jar file.
+ The default value is used when the expression evaluates to
+ null
+ .
+ NOTE: If not specified, an expression of ${<name>} is
+ assumed, which can only be satisfied from POM configuration or
+ System properties. The use of '${' and '}' is required to delimit
+ actual expressions which may be evaluated.
+ |
+
| deprecated | +@deprecated | +No | +Marks a parameter as deprecated. The rules on deprecation are + the same as normal Java with language elements. This will trigger + a warning when a user tries to configure a parameter marked as + deprecated. | +
The final component of a plugin descriptor is the dependencies. This + enables the plugin to function independently of its POM (or at least + to declare the libraries it needs to run). Dependencies are taken from + the + runtime + scope of the plugin's calculated dependencies (from + the POM). Dependencies are specified in exactly the same manner as in + the POM, except for the <scope> element (all dependencies in the + plugin descriptor are assumed to be runtime, because this is a + runtime profile for the plugin). +
+By now, we've mentioned the plugin tools several times without telling + you what they are or how to use them. Instead of manually writing (and + maintaining) the metadata detailed above, Maven 2.0 ships with some + tools to aid in this task. In fact, the only thing a plugin developer + needs to do is declare his project to be a plugin from within the POM. + Once this is done, Maven will call the appropriate descriptor + generators, etc. to produce an artifact that is ready for use within + Maven builds. Optional metadata can be injected via Javadoc annotation + (and possibly JDK5 annotations in the future) as described above, + enabling richer interactions between the Mojo and the user. The + section below describes the changes to the POM which are necessary to + create plugin artifacts.
+From the POM, Maven plugin projects look quite similar to any other + project. For pure Java plugins, the differences are even smaller than + for script-based plugins. The following details the POM elements + which are necessary to build a Maven plugin artifact.
++
| POM Element | +Required for Java Mojos? | +Sample Declaration | +Notes | +
|---|---|---|---|
| packaging | +Yes | +
+ <packaging>maven-plugin</packaging>
+ |
+ The POM must declare a packaging element which describes this + project as a Maven plugin project. | +
| scriptSourceDirectory | +No | +
+ <scriptSourceDirectory>src/main/scripts</scriptSourceDirectory>
+ |
+ In the case of script-based Mojos (which are not covered in
+ detail within this document), the POM must include an additional
+ element to distinguish script sources from (optional) Java
+ supporting classes. This element is scriptSourceDirectory,
+ inside the build section. This directory is included in the list
+ of resources which accompany any compiled code in the resulting
+ artifact. It is specified separately from the resources in the
+ build section to denote its special status as an alternate source
+ directory for scripts. |
+
After making the changes above, the developer can simply call
+
+
+ m2 install
+
+
+ to install the plugin to
+ the local repository. (Any of the other standard lifecycle targets like
+ package, deploy, etc. are also available in like fashion.)
+
If you're using Jetbrains IntelliJ Idea to develop your plugin, + you can use the following to configure the javadoc annotations as live + templates.
++
This section simply gives a listing of pointers for more + information.
++
+ +