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 when defining a Plexus component.

This is done in 2 steps:

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,
update sources with Java Annotations for Plexus.

Notice: if you're targeting components for Maven 3.1.0+, using @Named/@Inject JSR-330 annotations instead of @Component/@Requirement Plexus Java Annotations may be a good next step

Prerequisite Plugins

Here is the list of the plugins used:

Plugin	Version
`plexus-maven-plugin`	1.3.8
`plexus-component-metadata`	1.7.1

Equivalence Table

	plexus-maven-plugin	plexus-component-metadata
	project / plugin info	project / plugin info
latest	1.3.8	1.7.1
phase	process-sources	process-classes
goals	`descriptor`	`generate-metadata`
	`merge-descriptors`	see `staticMetadataDirectory` parameter default: `${project.basedir}/src/main/resources/META-INF/plexus`
	`test-descriptor`	`generate-test-metadata`
	`test-merge-descriptors`	see `testStaticMetadataDirectory` parameter default: `${project.basedir}/src/test/resources/META-INF/plexus`
	`components-report`	reporting feature not available
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.7.1</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 ${project.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.7.1</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;
}