[MPLUGIN-257] deprecated classical Maven objects as components: replaced with code snippets in documentation

git-svn-id: https://svn.apache.org/repos/asf/maven/plugin-tools/trunk@1590401 13f79535-47bb-0310-9956-ffa450edef68

maven-plugin-annotations/src/main/java/org/apache/maven/plugins/annotations/Component.java

@@ -29,15 +29,7 @@ import java.lang.annotation.Target;
 /**
  * Used to configure injection of Plexus components by
  * <a href="/ref/current/maven-core/apidocs/org/apache/maven/plugin/MavenPluginManager.html">
- * <code>MavenPluginManager.getConfiguredMojo(...)</code></a> and special Maven
+ * <code>MavenPluginManager.getConfiguredMojo(...)</code></a>.
- * objects as well:
- * <dl>
- *   <dt>mojoExecution</dt>        <dd>org.apache.maven.plugin.MojoExecution</dd>
- *   <dt>project</dt>              <dd>org.apache.maven.project.MavenProject</dd>
- *   <dt>session</dt>              <dd>org.apache.maven.execution.MavenSession</dd>
- *   <dt>settings</dt>             <dd>org.apache.maven.settings.Settings</dd>
- *   <dt>plugin (Maven-3 only)</dt><dd>org.apache.maven.plugin.descriptor.PluginDescriptor</dd>
- * </dl>
  *
  * @author Olivier Lamy
  * @since 3.0

maven-plugin-tools-annotations/src/main/java/org/apache/maven/tools/plugin/annotations/JavaAnnotationsMojoDescriptorExtractor.java

@@ -588,7 +588,10 @@ public class JavaAnnotationsMojoDescriptorExtractor
                 }
                 else
                 {
-                    // not a component but a Maven object to be transformed into an expression/property
+                    // not a component but a Maven object to be transformed into an expression/property: deprecated
+                    getLogger().warn( "Deprecated @component for " + parameter.getName() + " field in "
+                                          + mojoAnnotatedClass.getClassName() + "."
+                                          + ": replace with @parameter name=\"" + expression + "\" @readonly" );
                     parameter.setDefaultValue( expression );
                     parameter.setType( componentAnnotationContent.getRoleClassName() );
                     parameter.setRequired( true );

maven-plugin-tools-annotations/src/site/apt/index.apt

@@ -89,22 +89,23 @@ public class MyMojo
                 hint = "..." )
     private MyComponent component;
 
-    @Component
+    // sample objects taken from Maven API through PluginParameterExpressionEvaluator
+
+    @Parameter( defaultValue = "${session}", readonly = true )
     private MavenSession session;
 
-    @Component
+    @Parameter( defaultValue = "${project}", readonly = true )
     private MavenProject project;
 
-    @Component
+    @Parameter( defaultValue = "${mojoExecution}", readonly = true )
     private MojoExecution mojo;
 
-    @Component // for Maven 3 only
+    @Parameter( defaultValue = "${plugin}", readonly = true ) // Maven 3 only
     private PluginDescriptor plugin;
 
-    @Component
+    @Parameter( defaultValue = "${settings}", readonly = true )
     private Settings settings;
 
-    // sample objects taken from Maven API through PluginParameterExpressionEvaluator
     @Parameter( defaultValue = "${project.basedir}", readonly = true )
     private File basedir;
 

maven-plugin-tools-api/src/main/java/org/apache/maven/tools/plugin/util/PluginUtils.java

@@ -45,10 +45,12 @@ public final class PluginUtils
     }
 
     /**
-     * Expression associated with class types to recognize Maven objects (injected  in fact as parameters by
+     * Expression associated with class types to recognize Maven objects (injected in fact as parameters by <a
-     * <a href="/ref/current/maven-core/apidocs/org/apache/maven/plugin/PluginParameterExpressionEvaluator.html">
+     * href="/ref/current/maven-core/apidocs/org/apache/maven/plugin/PluginParameterExpressionEvaluator.html">
-     * maven-core's PluginParameterExpressionEvaluator</a>)
+     * maven-core's PluginParameterExpressionEvaluator</a>) like components ("real" components are injected by Plexus).
-     * like components ("real" components are injected by Plexus).
+     * 
+     * @deprecated wrong approach (fake components), documented parameter default values instead to learn people how to
+     *             discover them
      */
     public static final Map<String, String> MAVEN_COMPONENTS;
     static

maven-plugin-tools-java/src/main/java/org/apache/maven/tools/plugin/extractor/java/JavaMojoDescriptorExtractor.java

@@ -540,6 +540,9 @@ public class JavaMojoDescriptorExtractor
                 else
                 {
                     // not a component but a Maven object to be transformed into an expression/property
+                    getLogger().warn( "Deprecated @Component for " + pd.getName() + " field in "
+                                          + javaClass.getFullyQualifiedName() + ": replace with @Parameter( name = \""
+                                          + expression + "\", readonly = true )" );
                     pd.setDefaultValue( expression );
                     pd.setType( role );
                     pd.setRequired( true );

maven-plugin-tools-java/src/site/apt/index.apt

@@ -80,32 +80,38 @@ public class MyMojo
      */
     private Component component;
 
+    // sample objects taken from Maven API through PluginParameterExpressionEvaluator
+
     /**
-     * @component
+     * @parameter default-value="${session}"
+     * @readonly
      */
     private MavenSession session;
 
     /**
-     * @component
+     * @parameter default-value="${project}"
+     * @readonly
      */
     private MavenProject project;
 
     /**
-     * @component
+     * @parameter default-value="${mojoExecution}"
+     * @readonly
      */
     private MojoExecution mojo;
 
     /**
-     * @component
+     * @parameter default-value="${plugin}" // Maven 3 only
+     * @readonly
      */
     private PluginDescriptor plugin;
 
     /**
-     * @component
+     * @parameter default-value="${settings}"
+     * @readonly
      */
     private Settings settings;
 
-    // sample objects taken from Maven API through PluginParameterExpressionEvaluator
     /**
     * @parameter default-value="${project.basedir}"
     * @readonly