Getting Started

Implementing a Maven plugin based on this library is really easy. In the following there are some basic steps to go:

1. Add this library as a project dependency

---

Add the following to the dependencies of your plugin POM:

<dependency>
  <groupId>com.itemis.maven.plugins</groupId>
  <artifactId>cdi-plugin-utils</artifactId>
  <version>3.1.2</version>
</dependency>

2. Add beans.xml

---

In order to activate CDI for your plugin you will have to add a beans.xml to the META-INF folder of your plugin JAR. Simply add the beans.xml to src/main/resources/META-INF and CDI will then automatically process your classpath.

3. Implement a Mojo class

---

You need to implement a class representing your Mojo. This class must extend the abstract base Mojo provided by this library. It is important that your Mojo class does not override the method void execute() declared by Maven's Mojo interface! Wonder how you shall implement your processing logic then? No worries, this will be handled soon!

@Mojo(name = "test")
public class TestMojo extends AbstractCDIMojo {
  ...
}

More about Mojo implementation here: CDI Enabled Mojos

4. Let Maven inject parameters and components into your Mojo and provide them to your processing steps

---

Parameter injection is pretty equal to standard Maven Mojos. The difference here is that we use CDI producers and qualifiers to provide these parameters to our workflow steps that implemnt the processing logic.

@Mojo(name = "test")
public class TestMojo extends AbstractCDIMojo {
  // producer field
  @Parameter(defaultValue = "${project}", readonly = true, required = true)
  @MojoProduces                    // producer annotation to be used in Mojo classes
  private MavenProject project;

  // producer field
  @Component
  @MojoProduces                    // producer annotation to be used in Mojo classes
  private RepositorySystem repoSystem;

  // producer field
  @Parameter(defaultValue = "true", property = "test.outputToConsole")
  @MojoProduces                    // producer annotation to be used in Mojo classes
  @Named("outputToConsole")        // simple qualifier to dispatch boolean injection
  private boolean outputToConsole;

  // producer method
  @MojoProduces                    // producer annotation to be used in Mojo classes
  private PluginDescriptor getPluginDescriptor() {
    return (PluginDescriptor) getPluginContext().get("pluginDescriptor");
  }
}

You can use producer fields as well as producer methods to provide parameters and other data to your business logic implementations.

Note that there are some restrictions

Within your Mojo classes (classes extending AbstractCDIMojo) you cannot use the following annotations:

1. @Inject => Replaced by @com.itemis.maven.plugins.cdi.annotations.MojoInject
2. @Produces => Replaced by @com.itemis.maven.plugins.cdi.annotations.MojoProduces

This replacement is necessary due to Maven's own CDI injection approach which is much less powerful and requires more manual setup by the implementor.

More information about the Mojo implementation is available here: More about Mojo implementation here: CDI Enabled Mojos

5. Implement your business logic

---

By using the DI approach it is far more easy to split up your implementation into logically divided parts that make sense (separation of concerns). One key to this design is that it is now more easy to bring the Mojo parameters and other data to the points where they are needed, just inject them rather than passing them through all your classes.

The business logic of a plugin will be implemented in processing steps. Such steps must be annotated with @ProcessingStep and are required to implement the interface CDIMojoProcessingStep.

@ProcessingStep(id = "prepareTests", description = "Prepares the tests for execution.", requiresOnline = false)
public class StoreScmRevision implements CDIMojoProcessingStep {
  @Inject
  private Logger log;
  
  @Override
  public void execute(ExecutionContext context) throws MojoExecutionException, MojoFailureException {
    ...
  }
}

A detailed specification about processing steps and what can be done there is available here: Processing Steps

6. Orchestrate your business workflow

---

The final step to get the plugin functional is to define a default workflow which orchestrates the processing steps as required. This workflow is a simple text document named as the Mojo. It is required to be packaged under META-INF/workflows. For our example Mojo the workflow file would be META-INF/workflows/test and could look like the following:

# default workflow for our test example
pre-test
test
post-test

The workflow format is pretty simple and is in principle not much more than listing the ids of the processing steps in their correct order, each on a separate line. More about workflows here: The Workflow Format