At the heart of Maven is an Inversion of Control (IoC) container called Plexus. What does it do? It is a system for managing and relating components. Although Martin Fowler wrote a canonical essay about IoC, the concept and term have been so heavily overloaded in the past few years that it is tough to find a good definition of the concept that isn’t a self-reference (or just a lazy reference to the aforementioned essay). Instead of resorting to a Wikipedia quote, we’ll summarize Inversion of Control and Dependency Injection (DI) with an analogy.

Suppose you have a series of components that need to be wired together. When you think about components, think stereo components, not software components. Imagine several stereo components hooked up to a PlayStation 3 and a TiVo that have to interface with an Apple TV box as well as a 50” flat panel LCD TV. You bring everything home from the electronics store, and you purchase a series of cables that you will use to connect it all. You unpack all of these components, put them in their right places, and then get to the job of hooking up 50,000 coaxial cables and stereo jacks to 50,000 digital inputs and network cables. Step back from your home entertainment center and turn on the TV; you’ve just performed Dependency Injection, and you’ve just been using an IoC container.

So, what does that have to do with anything? Your PlayStation 3 and a Java bean both provide an interface. The PlayStation 3 has two inputs—power and network—and one output to the TV. Your Java bean has three properties: power, network, and tvOutput. When you open the box of your PlayStation 3, it doesn’t provide you with detailed pictures and instructions for how to connect it to every different kind of TV that might be in every different kind of house, and when you look at your Java bean, it just provides a set of properties, not an explicit recipe for creating and managing an entire system of components. In an IoC container such as Plexus, you are responsible for declaring the relationships between a set of components that simply provide an interface of inputs and outputs. You don’t instantiate objects; Plexus does. Your application’s code isn’t responsible for managing the state of components; Plexus is. Although it sounds cheesy, when you start up Maven, it starts Plexus and manages a system of related components just like your stereo system does.

What are the advantages of using an IoC container? Well, what is the advantage of buying discrete stereo components? If one component breaks, you can drop in a replacement for your PlayStation 3 without having to spend $20,000 on the entire system. If you are unhappy with your TV, you can swap it out without affecting your CD player. Most important to you, your stereo components cost less and are more capable and reliable because manufacturers can build to a set of known inputs and outputs and can focus on building individual components. IoC containers and DI encourage disaggregation and the emergence of standards. The software industry likes to imagine itself as the font of all new ideas, but DI and IoC are really just new terms for the concepts of disaggregation and interchangeable machinery. If you really want to know about DI and IoC, learn about the Model T, the cotton gin, and the emergence of a railroad standard in the late 19th century.

The most important feature of an IoC container implemented in Java is the mechanism of Dependency Injection. The basic idea of IoC is that the control of creating and managing objects is removed from the code itself and placed into the power of an IoC framework. Using DI in an application that has been programmed to interfaces, you can create components that are not bound to specific implementations of these interfaces. Instead, you program to interfaces and then configure Plexus to connect the appropriate implementation to the appropriate component. While your code deals with interfaces, you can capture the dependencies between classes and components in an XML file that defines components, implementation classes, and the relationships between your components. In other words, you can write isolated components, and then you can wire them together using an XML file that defines how the components are wired together. In the case of Plexus, system components are defined with an XML document that is found in META-INF/plexus/components.xml.

In a Java IoC container, several methods exist for injecting dependencies values into a component object: constructor, setter, or field injections. Although Plexus is capable of all three Dependency Injection techniques, Maven uses only two types—field and setter injection:

Spring happens to be the most popular IoC container at the moment, and there’s a good argument to be made that it has affected the Java “ecosystem” for the better, forcing companies such as Sun Microsystems to yield more control to the open source community and helping open up standards by providing a pluggable, component-oriented “bus.” But Spring isn’t the only IoC container in open source. There are many IoC containers (such as PicoContainer; see http://www.picocontainer.org/).

Years and years ago, when Maven was created, Spring wasn’t a mature option. The initial team of committers on Maven were more familiar with Plexus because they had invented it, so they decided to use it as an IoC container. Although it might not be as popular as the Spring Framework, it is no less capable. And the fact that it was created by the same person who created Maven makes it a perfect fit. After reading this chapter, you will have an idea of how Plexus works. If you already use an IoC container, you’ll notice similarities and differences between Plexus and the container you currently use.

A Maven plugin is a Maven artifact that contains a Plugin descriptor and one or more Mojos. A Mojo can be thought of as a goal in Maven, and every goal corresponds to a Mojo. The compiler:compile goal corresponds to the CompilerMojo class in the Maven Compiler plugin, and the jar:jar goal corresponds to the JarMojo class in the Maven Jar plugin. When you write your own plugin, you are simply grouping together a set of related Mojos (or goals) in a single plugin artifact.

A Mojo is much more than just a goal in Maven; it is a component managed by Plexus that can include references to other Plexus components.

The top-level configuration values in the plugin element are:

Next is the declaration of each Mojo. The plugin element contains an element named mojos that contains a mojo element for each Mojo present in the plugin. Each mojo element contains the following configuration elements:

Although you should know how to read a plugin descriptor, you will almost never need to write one of these descriptor files by hand. Plugin descriptor files are generated automatically off a set of annotations in the source for a Mojo.

Lastly, the plugin descriptor declares a set of dependencies, just like a Maven project. When Maven uses a plugin, it will download any required dependencies before it attempts to execute a goal from this plugin. In this example, the plugin depends on Jakarta Commons IO version 1.3.2.

To create a plugin project, you should use the Maven Archetype plugin. The following command line will create a plugin with a groupId of org.sonatype.mavenbook.plugins and an artifactId of first-maven-plugin:

$ mvn archetype:create 
  -DgroupId=org.sonatype.mavenbook.plugins 
  -DartifactId=first-maven-plugin 
  -DarchetypeGroupId=org.apache.maven.archetypes 
  -DarchetypeArtifactId=maven-archetype-mojo

The Archetype plugin will create a directory named my-first-plugin, which contains the POM shown in Example 17-2.

<?xml version="1.0" encoding="UTF-8"?><project>
  <modelVersion>4.0.0</modelVersion>
  <groupId>org.sonatype.mavenbook.plugins</groupId>
  <artifactId>first-maven-plugin</artifactId>
  <version>1.0-SNAPSHOT</version>
  <packaging>maven-plugin</packaging>
  <name>first-maven-plugin Maven Mojo</name>
  <url>http://maven.apache.org</url>
  <dependencies>
    <dependency>
      <groupId>org.apache.maven</groupId>
      <artifactId>maven-plugin-api</artifactId>
      <version>2.0</version>
    </dependency>
    <dependency>
      <groupId>junit</groupId>
      <artifactId>junit</artifactId>
      <version>3.8.1</version>
      <scope>test</scope>
    </dependency>
  </dependencies>
</project>

The most important element in a plugin project’s POM is the packaging element that has a value of maven-plugin. This packaging element customizes the Maven lifecycle to include the necessary goals to create a plugin descriptor. The plugin lifecycle was introduced in the section Maven Plugin” in Chapter 10. It is similar to the JAR lifecycle, with three exceptions: plugin:descriptor is bound to the generate-resources phase, plugin:addPluginArtifactMetadata is added to the package phase, and plugin:updateRegistry is added to the install phase.

The other important piece of a plugin project’s POM is the dependency on the Maven plugin API. This project depends on version 2.0 of the maven-plugin-api, and it also adds in JUnit as a test-scoped dependency.

In this chapter, we will introduce a Maven Mojo written in Java. Each Mojo in the project will implement the org.apache.maven.plugin.Mojo interface. The Mojo implementation shown in the upcoming example implements the Mojo interface by extending the org.apache.maven.plugin.AbstractMojo class. Before we dive into the code for this Mojo, let’s take some time to explore the methods on the Mojo interface. Mojo provides the following methods:

The Mojo interface is concerned with two things: logging the results of goal execution and executing a goal. When you are writing a custom plugin, you’ll be extending AbstractMojo. AbstractMojo takes care of handling the setLog() and getLog() implementations and contains an abstract execute() method. When you extend AbstractMojo, all you need to do is implement the execute() method. Example 17-3 shows a trivial Mojo implement that simply prints out a message to the console.

package org.sonatype.mavenbook.plugins;

import org.apache.maven.plugin.AbstractMojo;
import org.apache.maven.plugin.MojoExecutionException;
import org.apache.maven.plugin.MojoFailureException;

/**
 * Echos an object string to the output screen.
 * @goal echo
 * @requiresProject false
 */
public class EchoMojo extends AbstractMojo
{
    /**
     * Any Object to print out.
     * @parameter expression="${echo.message}" default-value="Hello Maven World..."
     */
    private Object message;

    public void execute()
        throws MojoExecutionException, MojoFailureException
    {
        getLog().info( message.toString() );
    }
}

If you create this Mojo in ${basedir} under src/main/java in org/sonatype/mavenbook/mojo/EchoMojo.java in the project created in the previous section and run mvn install, you should be able to invoke this goal directly from the command line with:

$ mvn org.sonatype.mavenbook.plugins:first-maven-plugin:1.0-SNAPSHOT:echo

That large command is mvn followed by the groupId:artifactId:version:goal. When you run this command, you should see output that contains the output of the echo goal with the default message: “Hello Maven World....” If you want to customize the message, you can pass the value of the message parameter with the following command:

$ mvn org.sonatype.mavenbook.plugins:first-maven-plugin:1.0-SNAPSHOT:echo 
             -Decho.message="The Eagle has Landed"

This command will execute the EchoMojo and print out the message “The Eagle has Landed”.

Specifying the groupId, artifactId, version, and goal on the command line is cumbersome. To address this, Maven assigns a plugin a prefix. Instead of typing:

$ mvn org.apache.maven.plugins:maven-jar-plugin:2.2:jar

You can use the plugin prefix jar and turn the command into mvn jar:jar. How does Maven resolve something like jar:jar to org.apache.mven.plugins:maven-jar:2.3? Maven looks at a file in the Maven repository to obtain a list of plugins for a specific groupId. By default, Maven is configured to look for plugins in two groups: org.apache.maven.plugins and org.codehaus.mojo. When you specify a new plugin prefix such as mvn hibernate3:hbm2ddl, Maven will scan the repository metadata for the appropriate plugin prefix. First, Maven will scan the org.apache.maven.plugins group for the plugin prefix hibernate3. If it doesn’t find the plugin prefix hibernate3 in the org.apache.maven.plugins group, it will scan the metadata for the org.codehaus.mojo group.

When Maven scans the metadata for a particular groupId, it is retrieving an XML file from the Maven repository that captures metadata about the artifacts contained in a group. This XML file is specific for each repository referenced; if you are not using a custom Maven repository, you will be able to see the Maven metadata for the org.apache.maven.plugins group in your local Maven repository (~/.m2/repository) under org/apache/maven/plugins/maven-metadata-central.xml. Example 17-4 shows a snippet of the maven-metadata-central.xml file from the org.apache.maven.plugin group.

<?xml version="1.0" encoding="UTF-8"?>
<metadata>
  <plugins>
    <plugin>
      <name>Maven Clean Plugin</name>
      <prefix>clean</prefix>
      <artifactId>maven-clean-plugin</artifactId>
    </plugin>
    <plugin>
      <name>Maven Compiler Plugin</name>
      <prefix>compiler</prefix>
      <artifactId>maven-compiler-plugin</artifactId>
    </plugin>
    <plugin>
      <name>Maven Surefire Plugin</name>
      <prefix>surefire</prefix>
      <artifactId>maven-surefire-plugin</artifactId>
    </plugin>
    ...
  </plugins>
</metadata>

As you can see in this example, this maven-metadata-central.xml file in your local repository is what makes it possible for you to execute mvn surefire:test. Maven scans org.apache.maven.plugins and org.codehaus.mojo. Plugins from org.apache.maven.plugins are considered core Maven plugins, and plugins from org.codehaus.mojo are considered extra plugins. The Apache Maven project manages the org.apache.maven.plugins group, and a separate independent open source community manages the Codehaus Mojo project. If you would like to start publishing plugins to your own groupId, and you would like Maven to automatically scan your own groupId for plugin prefixes, you can customize the groups that Maven scans for plugins in your Maven settings.

If you want to be able to run the first-maven-plugin’s echo goal by running first:echo, add the org.sonatype.mavenbook.plugins groupId to your ~/.m2/settings.xml, as shown in Example 17-5. This will prepend the org.sonatype.mavenbook.plugins to the list of groups that Maven scans for Maven plugins.

<settings>
  ...
  <pluginGroups>
    <pluginGroup>org.sonatype.mavenbook.plugins</pluginGroup>
  </pluginGroups>
</settings>

You can now run mvn first:echo from any directory and see that Maven will properly resolve the goal prefix to the appropriate plugin identifiers. This works because the project adheres to a naming convention for Maven plugins. If your plugin project has an artifactId that follows the pattern maven-first-plugin or first-maven-plugin, Maven will automatically assign a plugin goal prefix of first to your plugin. In other words, when the Maven Plugin plugin is generating the plugin descriptor for your plugin and you have not explicitly set the goalPrefix in your project, the plugin:descriptor goal will extract the prefix from your plugin’s artifactId when it matches one of the following patterns:

If you would like to set an explicit plugin prefix, you’ll need to configure the Maven Plugin plugin. This is plugin is responsible for building the plugin descriptor and performing plugin-specific tasks during the package and load phases. The Maven Plugin plugin can be configured just like any other plugin in the build element. To set the plugin prefix for your plugin, add the build element shown in Example 17-6 to the first-maven-plugin project’s pom.xml.

<?xml version="1.0" encoding="UTF-8"?><project>
  <modelVersion>4.0.0</modelVersion>
  <groupId>org.sonatype.mavenbook.plugins</groupId>
  <artifactId>first-maven-plugin</artifactId>
  <version>1.0-SNAPSHOT</version>
  <packaging>maven-plugin</packaging>
  <name>first-maven-plugin Maven Mojo</name>
  <url>http://maven.apache.org</url>
  <build>
    <plugins>
      <plugin>
        <artifactId>maven-plugin-plugin</artifactId>
        <version>2.3</version>
        <configuration>
          <goalPrefix>blah</goalPrefix>
        </configuration>
      </plugin>
    </plugins>
  </build>
  <dependencies>
    <dependency>
      <groupId>org.apache.maven</groupId>
      <artifactId>maven-plugin-api</artifactId>
      <version>2.0</version>
    </dependency>
    <dependency>
      <groupId>junit</groupId>
      <artifactId>junit</artifactId>
      <version>3.8.1</version>
      <scope>test</scope>
    </dependency>
  </dependencies>
</project>

This example sets the plugin prefix to blah. If you’ve added the org.sonatype.mavenbook.plugins to the pluginGroups in your ~/.m2/settings.xml, you should be able to execute the EchoMojo by running mvn echo:blah from any directory.

Maven takes care of connecting your Mojo to a logging provider by calling setLog() prior to the execution of your Mojo. It supplies an implementation of org.apache.maven.monitor.logging.Log. This class exposes methods that you can use to communicate information back to the user. This Log class provides multiple levels of logging similar to that API provided by Log4J. Those levels are captured by a series of methods available for each level—debug, info, error, and warn. To save trees, we will list only the methods for a single logging level—debug:

Each of the four levels exposes the same three methods. The four logging levels serve different purposes. The debug level exists for debugging purposes and for people who want to see a very detailed picture of the execution of a Mojo. You should use the debug logging level to provide as much detail on the execution of a Mojo, but you should never assume that a user is going to see the debug level. The info level is for general informational messages that should be printed as a normal course of operation. If you’re building a plugin that compiles code using a compiler, you might want to print the output of the compiler to the screen.

The warn logging level is used for messages about unexpected events and errors that your Mojo can cope with. If you are trying to run a plugin that compiles Ruby source code and there is no Ruby source code available, you might want to just print a warning message and move on. Warnings are not fatal, but errors are usually build-stopping conditions. For the completely unexpected error condition, there is the error logging level. You would use error if you couldn’t continue executing a Mojo. If you are writing a Mojo to compile some Java code and the compiler isn’t available, you’d print a message to the error level and possibly pass along an exception that Maven can print out for the user. You should assume that a user is going to see most of the messages in info and all of the messages in error.

In the first-maven-plugin example, you didn’t write the plugin descriptor yourself; you relied on Maven to generate the plugin descriptor from your source code. The descriptor was generated using your plugin project’s POM information and a set of annotations on your EchoMojo class. EchoMojo specifies only the @goal annotation. Here is a list of other annotations you can place on your Mojo implementation:

If you look at the source for EchoMojo, you’ll notice that Maven is not using the standard annotations available in Java 5. Instead, it is using Commons Attributes. Commons Attributes provided a way for Java programmers to use annotations before annotations were a part of the Java language specification. Why doesn’t Maven use Java 5 annotations? Because Maven is designed to target pre-Java 5 JVMs. Because Maven has to support older versions of Java, it cannot use any of the newer features available in Java 5.

The execute() method in Mojo throws two exceptions: MojoExecutionException and MojoFailureException. The difference between these two exceptions is both subtle and important, and it relates to what happens when a goal execution “fails.” A MojoExecutionException is a fatal exception: it means something unrecoverable happened. You will throw a MojoExecutionException if something happens that warrants a complete stop in a build: you are trying to write to disk, but there is no space left, or you are trying to publish to a remote repository, but you can’t connect to it. Throw a MojoExecutionException if there is no chance of a build continuing: that is, something terrible has happened, and you want the build to stop and the user to see a “BUILD ERROR” message.

A MojoFailureException is something less catastrophic: a goal can fail, but it might not be the end of the world for your Maven build. A unit test can fail, or an MD5 checksum can fail; both of these are potential problems, but you don’t want to return an exception that is going to kill the entire build. In this situation, you would throw a MojoFailureException. Maven provides for different “resiliency” settings when it comes to project failure. These are described next.

When you run a Maven build, it can involve a series of projects, each of which can succeed or fail. You have the option of running Maven in three failure modes:

You might want to ignore failures if you are running a continuous integration build and you want to attempt a build, regardless of the success or failure of an individual project build. As a plugin developer, you’ll have to make a call as to whether a particular failure condition is a MojoExecutionException or a MojoFailureExeception.

In EchoMojo, we declare the message parameter with the following annotations:

/**
 * Any Object to print out.
 * @parameter
 *       expression="${echo.message}"
 *       default-value="Hello Maven World"
 */
private Object message;

The default expression for this parameter is ${echo.message}. This means that Maven will try to use the value of the echo.message property to set the value for message. If the value of the echo.message property is null, the default-value attribute of the @parameter annotation will be used instead. Instead of using the echo.message property, we can configure a value for the message parameter of the EchoMojo directly in a project’s POM.

We can populate the message parameter in the EchoMojo in a few ways. First, we can pass in a value from the command line like this (assuming that you’ve added org.sonatype.mavenbook.plugins to your pluginGroups):

$ mvn first:echo -Decho.message="Hello Everybody"

We can also specify the value of this message parameter by setting a property in our POM or in our settings.xml:

<project>
  ...
  <properties>
    <echo.message>Hello Everybody</echo.message>
  </properties>
</project>

This parameter can also be configured directly as a configuration value for the plugin. If we wanted to customize the message parameter directly, we could use the following build configuration, which bypasses the echo.message property and populates the Mojo parameter in plugin configuration:

<project>
  ...
  <build>
    <plugins>
      <plugin>
        <groupId>org.sonatype.mavenbook.plugins</groupId>
        <artifactId>first-maven-plugin</artifactId>
        <version>1.0-SNAPSHOT</version>
        <configuration>
          <message>Hello Everybody!</message>
        </configuration>
      </plugin>
    </plugins>
  </build>
</project>

If we wanted to run the EchoMojo twice at difference phases in a lifecycle, and if we wanted to customize the message parameter for each execution separately, we could configure the parameter value at the execution level in a POM like this:

<build>
  <build>
    <plugins>
      <plugin>
        <groupId>org.sonatype.mavenbook.plugins</groupId>
        <artifactId>first-maven-plugin</artifactId>
        <version>1.0-SNAPSHOT</version>
        <executions>
          <execution>
            <id>first-execution</id>
            <phase>generate-resources</phase>
            <goals>
              <goal>echo</goal>
            </goals>
            <configuration>
              <message>The Eagle has Landed!</message>
            </configuration>
          </execution>
          <execution>
            <id>second-execution</id>
            <phase>validate</phase>
            <goals>
              <goal>echo</goal>
            </goals>
            <configuration>
              <message>${project.version}</message>
            </configuration>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>
</build>

Although this last configuration example seems very verbose, it illustrates the flexibility of Maven. In the previous configuration example, you bound the EchoMojo to both the validate and generate-resources phases in the default Maven lifecycle. The first execution is bound to generate-resources; it supplies a string value to the message parameter of “The Eagle has Landed!”. The second execution is bound to the validate phase; it supplies a property reference to ${project.version}. When you run mvn install for this project, you’ll see that the first:echo goal executes twice and prints out two different messages.

Plugins can have parameters that accept more than one value. Take a look at the ZipMojo shown in Example 17-7. Both the includes and excludes parameters are multivalued String arrays that specify the inclusion and exclusion patterns for a component that creates a ZIP file.

package org.sonatype.mavenbook.plugins
/**
 * Zips up the output directory.
 * @goal zip
 * @phase package
 */
public class ZipMojo extends AbstractMojo
{
    /**
     * The Zip archiver.
     * @parameter expression="${component.org.codehaus.plexus.archiver.Archiver#zip}"
     */
    private ZipArchiver zipArchiver;

    /**
     * Directory containing the build files.
     * @parameter expression="${project.build.directory}"
     */
    private File buildDirectory;

    /**
     * Base directory of the project.
     * @parameter expression="${basedir}"
     */
    private File baseDirectory;

    /**
     * A set of file patterns to include in the zip.
     * @parameter alias="includes"
     */
    private String[] mIncludes;

    /**
     * A set of file patterns to exclude from the zip.
     * @parameter alias="excludes"
     */
    private String[] mExcludes;

    public void setExcludes( String[] excludes ) { mExcludes = excludes; }

    public void setIncludes( String[] includes ) { mIncludes = includes; }

    public void execute()
        throws MojoExecutionException
    {
        try {
            zipArchiver.addDirectory( buildDirectory, includes, excludes );
            zipArchiver.setDestFile( new File( baseDirectory, "output.zip" ) );
            zipArchiver.createArchive();
        } catch( Exception e ) {
            throw new MojoExecutionException( "Could not zip", e );
        }
    }
}

To configure a multivalued Mojo parameter, you use a series of elements for each value. If the name of the multivalued parameter is includes, you would use an element includes with child elements include. If the multivalued parameter is excludes, you would use an element excludes with child elements exclude. To configure the ZipMojo to ignore all files ending in .txt and all files ending in a tilde, you would use the following plugin configuration:

<project>
  ...
  <build>
    <plugins>
      <plugin>
        <groupId>org.sonatype.mavenbook.plugins</groupId>
        <pluginId>zip-maven-plugin</pluginId>
        <configuration>
          <excludes>
            <exclude>**/*.txt</exclude>
            <exclude>**/*~</exclude>
          </excludes>
        </configuration>
      </plugin>
    </plugins>
  </build>
</project>

A Mojo is a component managed by an IoC container called Plexus. A Mojo can depend on other components managed by Plexus by declaring a Mojo parameter and using the @parameter or the @component annotation. Example 17-8 shows a ZipMojo that depends on a Plexus component using the @parameter annotation. This dependency could be declared using the @component annotation.

/**
 * The Zip archiver.
 * @component role="org.codehaus.plexus.archiver.Archiver" roleHint="zip"
 */
private ZipArchiver zipArchiver;

When Maven instantiates this Mojo, it will then attempt to retrieve the Plexus component with the specified role and role hint. In this example, the Mojo will be related to a ZipArchiver component that will allow the ZipMojo to create a ZIP file.

Unless you insist on writing your plugin descriptors by hand, you’ll never have to write that XML. Instead, the Maven Plugin plugin has a plugin:descriptor goal bound to the generate-resources phase. This goal generates the plugin descriptor from annotations on your Mojo. To configure a Mojo parameter, you should use the following annotations on the private member variables for each of your Mojo’s parameters. You can also use these annotations on public setter methods, but the most common convention for Maven plugins is to annotate private member variables directly:

Let’s assume you write some goal that depends on the output from a previous build. Maybe the ZipMojo goal can run only if there is output to include in an archive. You can specify something like a prerequisite goal by using the @execute annotation on a Mojo class. This annotation will cause Maven to spawn a parallel build and execute a goal or a lifecycle in a parallel instance of Maven that isn’t going to affect the current build. Maybe you wrote some Mojo that you can run once a day that runs mvn install and then packages up all of the output in some sort of customized distribution format. Your Mojo descriptor could tell Maven that before you execute your CustomMojo, you’d like it to execute the default lifecycle up to the install phase and then expose the results of that project to your Mojo as the property ${executedProject}. You could then reference properties in that project before some sort of postprocessing.

Another possibility is that you have a goal that does something completely unrelated to the default lifecycle. Let’s consider something completely unexpected. Maybe you have a goal that turns a WAV file into an MP3 using something like LAME, but before you do that, you want to step through a lifecycle that turns a MIDI file to a WAV. (You can use Maven for anything; this example isn’t that “far out.”) You’ve created a midi-sound lifecycle, and you want to include the output of the midi-sound lifecycle’s install phase in your web application project, which has a war packaging type. Since your project is running in the war packaging lifecycle, you’ll need to have a goal that effectively forks off an isolated build and runs through the midi-source lifecycle. You would do this by annotating your mojo with @execute lifecycle="midi-source" phase="install":

A custom lifecycle must be packaged in the plugin under the META-INF/maven/lifecycle.xml file. You can include a lifecycle under src/main/resources in META-INF/maven/lifecycle.xml. The lifecycle.xml shown in Example 17-9 declares a lifecycle named zipcycle that contains only the zip goal in a package phase.

<lifecycles>
  <lifecycle>
    <id>zipcycle</id>
    <phases>
      <phase>
        <id>package</id>
        <executions>
          <execution>
            <goals>
              <goal>zip</goal>
            </goals>
          </execution>
        </executions>
      </phase>
    </phases>
  </lifecycle>
</lifecycles>

If you wanted to execute the zipcycle phase within another build, you could then create a ZipForkMojo that uses the @execute annotation to tell Maven to step through the zipcycle phase to package when the ZipForkMojo is executed. See Example 17-10.

/**
 * Forks a zip lifecycle.
 * @goal zip-fork
 * @execute lifecycle="zipcycle" phase="package"
 */
public class ZipForkMojo extends AbstractMojo
{
  public void execute()
    throws MojoExecutionException
  {
    getLog().info( "doing nothing here" );
  }
}

Running the ZipForkMojo will fork the lifecycle. If you’ve configured your plugin to execute with the goal prefix zip, running zip-fork should produce something similar to the following output:

$ mvn zip:zip-fork
[INFO] Scanning for projects...
[INFO] Searching repository for plugin with prefix: 'zip'.
[INFO] -------------------------------------------------------------------
[INFO] Building Maven Zip Forked Lifecycle Test
[INFO]    task-segment: [zip:zip-fork]
[INFO] -------------------------------------------------------------------
[INFO] Preparing zip:zip-fork
[INFO] [site:attach-descriptor]
[INFO] [zip:zip]
[INFO] Building zip: ~/maven-zip-plugin/src/projects/zip-lifecycle-test/
            target/output.zip
[INFO] [zip:zip-fork]
[INFO] doing nothing here
[INFO] -------------------------------------------------------------------
[INFO] BUILD SUCCESSFUL
[INFO] -------------------------------------------------------------------
[INFO] Total time: 1 second
[INFO] Finished at: Sun Apr 29 16:10:06 CDT 2007
[INFO] Final Memory: 3M/7M
[INFO] -------------------------------------------------------------------

Calling zip-fork spawns another lifecycle. Maven executes the zipcycle lifecycle, and then it prints out the message from ZipFormMojo’s execute method.

Once you’ve created your own lifecycle and spawned it from a Mojo, the next question you might have is: How do you override the default lifecycle? How do you create custom lifecycles and then attach them to projects? In Chapter 10, we saw that the packaging of a project defines the lifecycle of a project. There’s something different about almost every packaging type: war attaches different goals to package, custom lifecycles such as swf from the Israfil Flex 3 plugin attach different goals to the compile phase. When you create a custom lifecycle, you can attach that lifecycle to a packaging type by supplying some Plexus configuration in your plugin’s archive.

To define a new lifecycle for a new packaging type, you’ll need to configure a LifecycleMapping component in Plexus. In your plugin project, create a META-INF/plexus/components.xml under src/main/resources. In components.xml, add the content from Example 17-11. Set the name of the packaging type under role-hint, and the set of phases containing the coordinates of the goals to bind (omit the version). Multiple goals can be associated with a phase using a comma delimited list.

<component-set>
  <components>
    <component>
      <role>org.apache.maven.lifecycle.mapping.LifecycleMapping</role>
      <role-hint>zip</role-hint>
      <implementation>org.apache.maven.lifecycle.mapping.DefaultLifecycleMapping
           </implementation>
      <configuration>
        <phases>
          <process-resources>org.apache.maven.plugins:maven-resources-plugin:resources
            </process-resources>
          <compile>org.apache.maven.plugins:maven-compiler-plugin:compile</compile>
          <package>org.sonatype.mavenbook.plugins:maven-zip-plugin:zip</package>
        </phases>
      </configuration>
    </component>
  </components>
</component-set>

If you create a plugin that defines a new packaging type and a customized lifecycle, Maven won’t know anything about it until you add the plugin to your project’s POM and set the extensions element to true. Once you do this, Maven will scan your plugin for more than just Mojos to execute; it will look for the components.xml under META-INF/plexus, and it will make the packaging type available to your project. See Example 17-12.

<project>
  ...
  <build>
    ...
    <plugins>
      <plugin>
        <groupId>com.training.plugins</groupId>
        <artifactId>maven-zip-plugin</artifactId>
        <extensions>true</extensions>
      </plugin>
    </plugins>
  </build>
</project>

Once you add the plugin with the extensions element set to true, you can use the custom packaging type and your project will be able to execute the custom lifecycle associated with that packaging type.