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:


  
    
      
        org.codehaus.plexus
        plexus-maven-plugin
        1.3.8
        
          
            
              descriptor

with corresponding plexus-component-metadata configuration:


  
    
      
        org.codehaus.plexus
        plexus-component-metadata
        1.7.1
        
          
            
              generate-metadata

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:


  
    
      org.codehaus.plexus
      plexus-component-annotations
      1.7.1

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;
}