Starting with Maven 2.0, plugins can be written in Java or any of a + number of scripting languages (currently just marmalade - we are + working to implement others). 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 trigger's 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 it's 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:
+
Each Mojo specified inside a plugin descriptor must provide the + following:
++
Each Mojo specifies the parameters that it expects to be able to work + with. 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:
++
The final component of a plugin descriptor is the dependencies. This + enables the plugin to function independently of it's 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 writing (and + maintaining) this metadata file by hand, Maven 2.0 ships with some + tools to aid developers 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. 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.
++
<packaging>maven-plugin</packaging><scriptSourceDirectory>src/main/scripts</scriptSourceDirectory>.
+ 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.)