From 25d920f53e12ef20a1d01bf9aae3a4c1ce738964 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Herv=C3=A9=20Boutemy?= Date: Sun, 5 Nov 2023 09:47:39 +0200 Subject: [PATCH] [MNG-5695] document Maven 3.2.5+ scoped components usage This closes #236 --- .../src/site/apt/index.apt | 32 ++++++++++++++++--- 1 file changed, 27 insertions(+), 5 deletions(-) diff --git a/maven-plugin-tools-annotations/src/site/apt/index.apt b/maven-plugin-tools-annotations/src/site/apt/index.apt index f78b791a..dad471df 100644 --- a/maven-plugin-tools-annotations/src/site/apt/index.apt +++ b/maven-plugin-tools-annotations/src/site/apt/index.apt @@ -85,7 +85,7 @@ public class MyMojo @Parameter( name = "parameter", alias = "myAlias", property = "a.property", - defaultValue = "an expression, possibly with ${variables}", + defaultValue = "an expression, possibly with ${variables} and pseudo-parameter expressions ${project.xxx.yyy}", readonly = , required = ) private String parameter; @@ -94,27 +94,42 @@ public class MyMojo hint = "..." ) private MyComponent component; + // pseudo-parameters (marked read-only) permitting injection of Maven build context objects // sample objects taken from Maven API through PluginParameterExpressionEvaluator + // https://maven.apache.org/ref/current/maven-core/apidocs/org/apache/maven/plugin/PluginParameterExpressionEvaluator.html + // plugins targetting Maven 3.2.5+ (after MNG-5695) should not use these pseudo-parameters any more, + // but @Component and Maven APIs to get better compiler-time checks - @Parameter( defaultValue = "${session}", readonly = true ) + // @Parameter( defaultValue = "${session}", readonly = true ) + @Component // since Maven 3.2.5, thanks to MNG-5695 private MavenSession session; - @Parameter( defaultValue = "${project}", readonly = true ) + // @Parameter( defaultValue = "${project}", readonly = true ) + @Component // since Maven 3.2.5, thanks to MNG-5695 private MavenProject project; - @Parameter( defaultValue = "${mojoExecution}", readonly = true ) - private MojoExecution mojo; + // @Parameter( defaultValue = "${mojoExecution}", readonly = true ) + @Component // since Maven 3.2.5, thanks to MNG-5695 + private MojoExecution mojoExecution; + + @Parameter( defaultValue = "${reactorProjects}", readonly = true ) + // prefer using session.getProjects() + private List reactorProjects; @Parameter( defaultValue = "${plugin}", readonly = true ) // Maven 3 only + // prefer using mojoExecution.getMojoDescriptor() private PluginDescriptor plugin; @Parameter( defaultValue = "${settings}", readonly = true ) + // prefer using session.getSettings() private Settings settings; @Parameter( defaultValue = "${project.basedir}", readonly = true ) + // prefer using project.getBasedir() private File basedir; @Parameter( defaultValue = "${project.build.directory}", readonly = true ) + // prefer using project.getBuild().getDirectory() private File target; /** @@ -144,3 +159,10 @@ public class MyMojo * {{{/ref/current/maven-core/apidocs/org/apache/maven/plugin/PluginParameterExpressionEvaluator.html}PluginParameterExpressionEvaluator}}, used to evaluate plugin parameters values during Mojo configuration, + + * pseudo parameters: + + * <<>> {{{https://maven.apache.org/ref/current/maven-core/apidocs/org/apache/maven/plugin/PluginParameterExpressionEvaluator.html}javadoc}} / + {{{https://maven.apache.org/ref/current/maven-core/xref/org/apache/maven/plugin/PluginParameterExpressionEvaluator.html}source}} + + * {{{https://issues.apache.org/jira/browse/MNG-5695}MNG-5695}}: scoped objects added to Guice/Sisu in {{{https://maven.apache.org/ref/current/maven-core/}maven-core}} 3.2.5