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:

  1. <project>
  2.   <build>
  3.     <plugins>
  4.       <plugin>
  5.         <groupId>org.codehaus.plexus</groupId>
  6.         <artifactId>plexus-maven-plugin</artifactId>
  7.         <version>1.3.8</version>
  8.         <executions>
  9.           <execution>
  10.             <goals>
  11.               <goal>descriptor</goal>
  12.             </goals>
  13.           </execution>
  14.         </executions>
  15.       </plugin>
  16.   </build>
  17. </project>

with corresponding plexus-component-metadata configuration:

  1. <project>
  2.   <build>
  3.     <plugins>
  4.       <plugin>
  5.         <groupId>org.codehaus.plexus</groupId>
  6.         <artifactId>plexus-component-metadata</artifactId>
  7.         <version>1.5.5</version>
  8.         <executions>
  9.           <execution>
  10.             <goals>
  11.               <goal>generate-metadata</goal>
  12.             </goals>
  13.           </execution>
  14.         </executions>
  15.       </plugin>
  16.   </build>
  17. </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:

  1. <project>
  2.   <dependencies>
  3.     <dependency>
  4.       <groupId>org.codehaus.plexus</groupId>
  5.       <artifactId>plexus-component-annotations</artifactId>
  6.       <version>1.5.5</version>
  7.     </dependency>
  8.   </dependencies>
  9. </project>

In your java sources, replace javadoc tags:

  1. /**
  2.  * @plexus.component role="foo.MyComponent" role-hint="hint-value"
  3.  */
  4. public class MyComponentImplementation
  5.     implements MyComponent
  6. {
  7.     /**
  8.      * @plexus.requirement
  9.      */
  10.     private InjectedComponent;
  11. }

with corresponding Java 5 annotations

  1. import org.codehaus.plexus.component.annotations.Component;
  2. import org.codehaus.plexus.component.annotations.Requirement;
  3.  
  4. @Component( role = MyComponent.class, hint = "hint-value" )
  5. public class MyComponentImplementation
  6.     implements MyComponent
  7. {
  8.     @Requirement
  9.     private InjectedComponent;
  10. }