Cookbook: How To Upgrade from Plexus Javadoc Tags to Plexus Java Annotations?

Summary

This recipe describes how to upgrade from Plexus Javadoc Tags to Plexus Java Annotations, in 2 steps:

  1. replace the deprecated plexus-maven-plugin, which only supports Plexus Javadoc Tags, with its successor: plexus-component-metadata, which support both Plexus Javadoc Tags and Plexus Java Annotations,
  2. update sources with Java Annotations for Plexus.

Prerequisite Plugins

Here is the list of the plugins used:

Plugin Version
plexus-maven-plugin 1.3.8
plexus-component-metadata 1.5.5

Equivalence Table

plexus-maven-plugin plexus-component-metadata
project / plugin info project / plugin info
latest 1.3.8 1.5.5
phase process-sources process-classes
goals descriptor generate-metadata
merge-descriptors see staticMetadataDirectory parameter  
default: ${basedir}/src/main/resources/META-INF/plexus
test-descriptor generate-test-metadata
test-merge-descriptors see testStaticMetadataDirectory parameter  
default: ${basedir}/src/test/resources/META-INF/plexus
source annotations javadoc tags:  
@plexus.component, @plexus.requirement, @plexus.configuration  		 javadoc tags + plexus-component-annotations Java 5 annotations: 
@Component, @Requirement, @Configuration,

Recipe

Plugin Configuration

In your pom.xml, replace plexus-maven-plugin configuration:

<project>
  <build>
    <plugins>
      <plugin>
        <groupId>org.codehaus.plexus</groupId>
        <artifactId>plexus-maven-plugin</artifactId>
        <version>1.3.8</version>
        <executions>
          <execution>
            <goals>
              <goal>descriptor</goal>
            </goals>
          </execution>
        </executions>
      </plugin>
  </build>
</project>

with corresponding plexus-component-metadata configuration:

<project>
  <build>
    <plugins>
      <plugin>
        <groupId>org.codehaus.plexus</groupId>
        <artifactId>plexus-component-metadata</artifactId>
        <version>1.5.5</version>
        <executions>
          <execution>
            <goals>
              <goal>generate-metadata</goal>
            </goals>
          </execution>
        </executions>
      </plugin>
  </build>
</project>

If merge-descriptors is used, move the handwritten xml file to ${basedir}/src/main/resources/META-INF/plexus.

Replacing Plexus Javadoc Tags with Plexus Java 5 Annotations

In your pom.xml, add plexus-component-annotations dependency:

<project>
  <dependencies>
    <dependency>
      <groupId>org.codehaus.plexus</groupId>
      <artifactId>plexus-component-annotations</artifactId>
      <version>1.5.5</version>
    </dependency>
  </dependencies>
</project>

In your java sources, replace javadoc tags:

/**
 * @plexus.component role="foo.MyComponent" role-hint="hint-value"
 */
public class MyComponentImplementation
    implements MyComponent
{
    /**
     * @plexus.requirement
     */
    private InjectedComponent;
}

with corresponding Java 5 annotations

import org.codehaus.plexus.component.annotations.Component;
import org.codehaus.plexus.component.annotations.Requirement;

@Component( role = MyComponent.class, hint = "hint-value" )
public class MyComponentImplementation
    implements MyComponent
{
    @Requirement
    private InjectedComponent;
}