| ----- |
| Cookbook - How To Upgrade from Plexus Javadoc Tags to Plexus Java Annotations |
| ----- |
| Hervé Boutemy |
| ----- |
| 2012-06-02 |
| ----- |
| |
| ~~ Licensed to the Apache Software Foundation (ASF) under one |
| ~~ or more contributor license agreements. See the NOTICE file |
| ~~ distributed with this work for additional information |
| ~~ regarding copyright ownership. The ASF licenses this file |
| ~~ to you under the Apache License, Version 2.0 (the |
| ~~ "License"); you may not use this file except in compliance |
| ~~ with the License. You may obtain a copy of the License at |
| ~~ |
| ~~ http://www.apache.org/licenses/LICENSE-2.0 |
| ~~ |
| ~~ Unless required by applicable law or agreed to in writing, |
| ~~ software distributed under the License is distributed on an |
| ~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| ~~ KIND, either express or implied. See the License for the |
| ~~ specific language governing permissions and limitations |
| ~~ under the License. |
| |
| ~~ NOTE: For help with the syntax of this file, see: |
| ~~ http://maven.apache.org/doxia/references/apt-format.html |
| |
| 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 {{{https://codehaus-plexus.github.io/plexus-maven-plugin/}<<<plexus-maven-plugin>>>}}, |
| which only supports Plexus Javadoc Tags, with its successor: |
| {{{https://codehaus-plexus.github.io/plexus-containers/plexus-component-metadata/}<<<plexus-component-metadata>>>}}, |
| which support both Plexus Javadoc Tags and Plexus Java Annotations, |
| |
| [[2]] update sources with {{{https://codehaus-plexus.github.io/plexus-containers/plexus-component-annotations/}Java Annotations for Plexus}}. |
| |
| [] |
| |
| * Prerequisite Plugins |
| |
| Here is the list of the plugins used: |
| |
| *--------------------------------------------------------------------------------------------------------------+--------------+ |
| || <<Plugin>> || <<Version>> |
| *--------------------------------------------------------------------------------------------------------------+--------------+ |
| | {{{https://codehaus-plexus.github.io/plexus-maven-plugin/}<<<plexus-maven-plugin>>>}} | 1.3.8 |
| *--------------------------------------------------------------------------------------------------------------+--------------+ |
| | {{{https://codehaus-plexus.github.io/plexus-containers/plexus-component-metadata/}<<<plexus-component-metadata>>>}} | 1.5.5 |
| *--------------------------------------------------------------------------------------------------------------+--------------+ |
| |
| * Equivalence Table |
| |
| *---------*---------------------------------------------------------------------------------------------------------*--------------* |
| | || <<plexus-maven-plugin>> || <<plexus-component-metadata>> |
| *---------+---------------------------------------------------------------------------------------------------------+--------------+ |
| | | {{{https://codehaus-plexus.github.io/plexus-maven-plugin/}project}} / | {{{https://codehaus-plexus.github.io/plexus-containers/plexus-component-metadata/}project}} / |
| | | {{{https://codehaus-plexus.github.io/plexus-maven-plugin/plugin-info.html}plugin info}} | {{{https://codehaus-plexus.github.io/plexus-containers/plexus-component-metadata/plugin-info.html}plugin info}} |
| *---------+---------------------------------------------------------------------------------------------------------+--------------+ |
| || latest | 1.3.8 | 1.5.5 |
| *---------+---------------------------------------------------------------------------------------------------------+--------------+ |
| || phase | process-sources | process-classes |
| *---------+---------------------------------------------------------------------------------------------------------+--------------+ |
| || goals | {{{https://codehaus-plexus.github.io/plexus-maven-plugin/descriptor-mojo.html}<<<descriptor>>>}} | {{{https://codehaus-plexus.github.io/plexus-containers/plexus-component-metadata/generate-metadata-mojo.html}<<<generate-metadata>>>}} |
| *---------+---------------------------------------------------------------------------------------------------------+--------------+ |
| | | {{{https://codehaus-plexus.github.io/plexus-maven-plugin/merge-descriptors-mojo.html}<<<merge-descriptors>>>}} | see <<<staticMetadataDirectory>>> parameter \ |
| | | | default: <<<$\{basedir}/src/main/resources/META-INF/plexus>>> |
| *---------+---------------------------------------------------------------------------------------------------------+--------------+ |
| | | {{{https://codehaus-plexus.github.io/plexus-maven-plugin/test-descriptor-mojo.html}<<<test-descriptor>>>}} | {{{https://codehaus-plexus.github.io/plexus-containers/plexus-component-metadata/generate-test-metadata-mojo.html}<<<generate-test-metadata>>>}} |
| *---------+---------------------------------------------------------------------------------------------------------+--------------+ |
| | | {{{https://codehaus-plexus.github.io/plexus-maven-plugin/test-merge-descriptors-mojo.html}<<<test-merge-descriptors>>>}} | see <<<testStaticMetadataDirectory>>> parameter \ |
| | | | default: <<<$\{basedir}/src/test/resources/META-INF/plexus>>> |
| *---------+---------------------------------------------------------------------------------------------------------+--------------+ |
| || source annotations | javadoc tags: \ |
| || | | javadoc tags + {{{https://codehaus-plexus.github.io/plexus-containers/plexus-component-annotations/}<<<plexus-component-annotations>>>}} Java 5 annotations:\ |
| || | <<<@plexus.component>>>, <<<@plexus.requirement>>>, <<<@plexus.configuration>>> \ |
| || | | {{{https://codehaus-plexus.github.io/plexus-containers/plexus-component-annotations/apidocs/org/codehaus/plexus/component/annotations/Component.html}<<<@Component>>>}}, |
| || | | {{{https://codehaus-plexus.github.io/plexus-containers/plexus-component-annotations/apidocs/org/codehaus/plexus/component/annotations/Requirement.html}<<<@Requirement>>>}}, |
| || | | {{{https://codehaus-plexus.github.io/plexus-containers/plexus-component-annotations/apidocs/org/codehaus/plexus/component/annotations/Configuration.html}<<<@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; |
| } |
| +---------+ |