This is an automated email from the ASF dual-hosted git repository.
kwin pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/maven-site.git
The following commit(s) were added to refs/heads/master by this push:
new c0edfafc [MNG-7524] Document type coercion from String to Mojo
parameter types (#322)
c0edfafc is described below
commit c0edfafc076d08d4c5aa16e0ad82d1c939437cfc
Author: Konrad Windszus <k...@apache.org>
AuthorDate: Fri Sep 30 17:38:09 2022 +0200
[MNG-7524] Document type coercion from String to Mojo parameter types (#322)
rely on TOC macro
---
.../apt/guides/mini/guide-configuring-plugins.apt | 128 ++++----
.../plugin/guide-java-plugin-development.apt | 328 +--------------------
2 files changed, 79 insertions(+), 377 deletions(-)
diff --git a/content/apt/guides/mini/guide-configuring-plugins.apt
b/content/apt/guides/mini/guide-configuring-plugins.apt
index 3861cb98..946c2f11 100644
--- a/content/apt/guides/mini/guide-configuring-plugins.apt
+++ b/content/apt/guides/mini/guide-configuring-plugins.apt
@@ -29,51 +29,7 @@
Guide to Configuring Plug-ins
- [[1]] {{{Generic_Configuration}Generic Configuration}}
-
- [[1]] {{{Help_Goal}Help Goal}}
-
- [[2]] {{{Configuring_Parameters}Configuring Parameters}}
-
- [[1]] {{{Mapping_Simple_Objects}Mapping Simple Objects}}
-
- [[2]] {{{Mapping_Complex_Objects}Mapping Complex Objects}}
-
- [[3]] {{{Mapping_Collections}Mapping Collections}}
-
- [[1]] {{{Mapping_Lists}Mapping Lists}}
-
- [[2]] {{{Mapping_Maps}Mapping Maps}}
-
- [[3]] {{{Mapping_Properties}Mapping Properties}}
-
- []
-
- []
-
- []
-
- [[2]] {{{Configuring_Build_Plugins}Configuring Build Plugins}}
-
- [[1]] {{{Using_the_executions_Tag}Using the <<<\<executions\>>>> Tag}}
-
- [[2]] {{{Using_the_dependencies_Tag}Using the <<<\<dependencies\>>>>
Tag}}
-
- [[3]] {{{Using_the_inherited_Tag_In_Build_Plugins}Using the
<<<\<inherited\>>>> Tag In Build Plugins}}
-
- []
-
- [[3]] {{{Configuring_Reporting_Plugins}Configuring Reporting Plugins}}
-
- [[1]] {{{Using_the_reporting_Tag_VS_build_Tag}Using the
<<<\<reporting\>>>> Tag VS <<<\<build\>>>> Tag}}
-
- [[2]] {{{Using_the_reportSets_Tag}Using the <<<\<reportSets\>>>> Tag}}
-
- [[3]] {{{Using_the_inherited_Tag_In_Reporting_Plugins}Using the
<<<\<inherited\>>>> Tag In Reporting Plugins}}
-
- []
-
- []
+%{toc|fromDepth=2}
* Introduction
@@ -190,9 +146,11 @@ mvn javadoc:help -Ddetail -Dgoal=javadoc
** {Configuring Parameters}
-*** {Mapping Simple Objects}
+ Parametrisation of Mojos is relying internally on Plexus Component
Configuration API provided by
{{{https://github.com/eclipse/sisu.plexus}sisu-plexus}}.
- Mapping simple types, like Boolean or Integer, is very simple. The
<<<\<configuration\>>>> element might look like
+*** {Mapping Value Objects}
+
+ Mapping value types, like Boolean or Integer, is very simple. The
<<<\<configuration\>>>> element might look like
the following:
+----+
@@ -208,6 +166,47 @@ mvn javadoc:help -Ddetail -Dgoal=javadoc
...
+----+
+ The detailed type coercion is explained in the table below.
+ For conversion to primitive types their according
{{{https://docs.oracle.com/javase/tutorial/java/data/autoboxing.html}wrapper
classes are used and automatically unboxed}}.
+
+*---------------------*--------------*
+|| Parameter Class || Conversion from String
+*---------------------*--------------*
+ <<<Boolean>>> |
{{{https://docs.oracle.com/javase/8/docs/api/java/lang/Boolean.html#valueOf-java.lang.String-}<<<Boolean.valueOf(String)>>>}}
+*---------------------*--------------*
+ <<<Byte>>> |
{{{https://docs.oracle.com/javase/8/docs/api/java/lang/Byte.html#decode-java.lang.String-}<<<Byte.decode(String)>>>}}
+*---------------------*--------------*
+ <<<Character>>> |
{{{https://docs.oracle.com/javase/8/docs/api/java/lang/Character.html#valueOf-char-}<<<Character.valueOf(char)>>>}}
of the first character in the given string
+*---------------------*--------------*
+ <<<Class>>> |
{{{https://docs.oracle.com/javase/8/docs/api/java/lang/Class.html#forName-java.lang.String-}<<<Class.forName(String)>>>}}
+*---------------------*--------------*
+ <<<java.util.Date>>> |
{{{https://docs.oracle.com/javase/8/docs/api/java/text/DateFormat.html#parse-java.lang.String-}<<<SimpleDateFormat.parse(String)>>>}}
for the following patterns: <<<yyyy-MM-dd hh:mm:ss.S a>>>, <<<yyyy-MM-dd
hh:mm:ssa>>>, <<<yyyy-MM-dd HH:mm:ss.S>>> or <<<yyyy-MM-dd HH:mm:ss>>>
+*---------------------*--------------*
+ <<<Double>>> |
{{{https://docs.oracle.com/javase/8/docs/api/java/lang/Double.html#valueOf-java.lang.String-}<<<Double.valueOf(String)>>>}}
+*---------------------*--------------*
+ <<<Enum>>> |
{{{https://docs.oracle.com/javase/8/docs/api/java/lang/Enum.html#valueOf-java.lang.String-}<<<Enum.valueOf(String)>>>}}
+*---------------------*--------------*
+ <<<java.io.File>>> |
{{{https://docs.oracle.com/javase/8/docs/api/java/io/File.html#File-java.lang.String-}<<<new
File(String)>>>}} with the file separators normalized to
<<<File.separatorChar>>>. In case the file is relative, is is made absolute by
prefixing it with the project's base directory.
+*---------------------*--------------*
+ <<<Float>>> |
{{{https://docs.oracle.com/javase/8/docs/api/java/lang/Float.html#valueOf-java.lang.String-}<<<Float.valueOf(String)>>>}}
+*---------------------*--------------*
+ <<<Integer>>> |
{{{https://docs.oracle.com/javase/8/docs/api/java/lang/Integer.html#decode-java.lang.String-}<<<Integer.decode(String)>>>}}
+*---------------------*--------------*
+ <<<Long>>> |
{{{https://docs.oracle.com/javase/8/docs/api/java/lang/Long.html#decode-java.lang.String-}<<<Long.decode(String)>>>}}
+*---------------------*--------------*
+ <<<Short>>> |
{{{https://docs.oracle.com/javase/8/docs/api/java/lang/Short.html#decode-java.lang.String-}<<<Short.decode(String)>>>}}
+*---------------------*--------------*
+ <<<String>>> | n/a
+*---------------------*--------------*
+ <<<StringBuffer>>> |
{{{https://docs.oracle.com/javase/8/docs/api/java/lang/StringBuffer.html#StringBuffer-java.lang.String-}<<<new
StringBuffer(String)>>>}}
+*---------------------*--------------*
+ <<<StringBuilder>>> |
{{{https://docs.oracle.com/javase/8/docs/api/java/lang/StringBuilder.html#StringBuilder-java.lang.String-}<<<new
StringBuilder(String)>>>}}
+*---------------------*--------------*
+ <<<java.net.URI>>> |
{{{https://docs.oracle.com/javase/8/docs/api/java/net/URI.html#URI-java.lang.String-)}<<<new
URI(String)>>>}}
+*---------------------*--------------*
+ <<<java.net.URL>>> |
{{{https://docs.oracle.com/javase/8/docs/api/java/net/URL.html#URL-java.lang.String-)}<<<new
URL(String)>>>}}
+*---------------------*--------------*
+
*** {Mapping Complex Objects}
Mapping complex types is also fairly straight forward. Let's look at a
simple example where we
@@ -252,15 +251,15 @@ mvn javadoc:help -Ddetail -Dgoal=javadoc
...
+----+
-*** {Mapping Collections}
+*** {Mapping Collection Types}
The configuration mapping mechanism can easily deal with most collections so
let's go through a few examples
to show you how it's done:
-**** {Mapping Lists}
+**** {Mapping Collections and Arrays}
- Mapping lists works in much the same way as mapping to arrays where you a
list of elements will be
- mapped to the List. So if you have a mojo like the following:
+ Mapping to collections works in much the same way as mapping to arrays. Each
item is given in the XML
+ as dedicated element. The element name does not matter in that case. So if
you have a mojo like the following:
+----+
public class MyAnimalMojo
@@ -277,7 +276,7 @@ public class MyAnimalMojo
}
+----+
- Where you have a field named <<<animals>>> then your configuration for the
plug-in would look like the following:
+ where you have a field named <<<animals>>> then your configuration for the
plug-in would look like the following:
+----+
<project>
@@ -315,6 +314,31 @@ public class MyAnimalMojo
[]
+ Alternatively, you can list individual items as comma-separated list in the
XML value of animals directly.
+ This approach is also used if configuring collection/array parameters via
command line
+ The following example is equivalent to the example above:
+
++----+
+<project>
+ ...
+ <build>
+ <plugins>
+ <plugin>
+ <artifactId>maven-myanimal-plugin</artifactId>
+ <version>1.0</version>
+ <configuration>
+ <animals>cat,dog,aardvark</animals>
+ </configuration>
+ </plugin>
+ </plugins>
+ </build>
+ ...
+</project>
++----+
+
+ Each item is mapped again according to the rules of this section depending on
the type of the collection/array.
+
+
**** {Mapping Maps}
In the same way, you could define maps like the following:
diff --git a/content/apt/guides/plugin/guide-java-plugin-development.apt
b/content/apt/guides/plugin/guide-java-plugin-development.apt
index be855d21..b4349a05 100644
--- a/content/apt/guides/plugin/guide-java-plugin-development.apt
+++ b/content/apt/guides/plugin/guide-java-plugin-development.apt
@@ -33,7 +33,9 @@ Introduction
This guide is intended to assist users in developing Java plugins for
Maven.
-* Important Notice: {Plugin Naming Convention and Apache Maven Trademark}
+%{toc|fromDepth=2}
+
+* Important Notice: {{{../mini/guide-naming-conventions.html}Plugin Naming
Convention and Apache Maven Trademark}}
You will typically name your plugin <<<<yourplugin>-maven-plugin>>>.
@@ -359,330 +361,6 @@ mvn archetype:generate \
<<Note>>: More details can be found in the
{{{../mini/guide-configuring-plugins.html}Guide to Configuring Plugins}}.
-** Parameter Types With One Value
-
- Listed below are the various types of simple variables which can be used as
- parameters in your mojos, along with any rules on how the values in the
- POM are interpreted.
-
-*** Boolean
-
- This includes variables typed <<<boolean>>> and <<<Boolean>>>. When reading
- the configuration, the text "<<<true>>>" causes the parameter to be set to
- true and all other text causes the parameter to be set to false. Example:
-
-+-----+
- /**
- * My boolean.
- */
- @Parameter
- private boolean myBoolean;
-+-----+
-
-+-----+
-<myBoolean>true</myBoolean>
-+-----+
-
-*** Integer Numbers
-
- This includes variables typed <<<byte>>>, <<<Byte>>>, <<<int>>>,
- <<<Integer>>>, <<<long>>>, <<<Long>>>, <<<short>>>, and <<<Short>>>. When
- reading the configuration, the text in the XML file is converted to an
- integer value using either <<<Integer.parseInt()>>> or the <<<valueOf()>>>
- method of the appropriate class. This means that the strings must be valid
- decimal integer values, consisting only of the digits 0 to 9 with an optional
- <<<->>> in front for a negative value. Example:
-
-+-----+
- /**
- * My Integer.
- */
- @Parameter
- private Integer myInteger;
-+-----+
-
-+-----+
-<myInteger>10</myInteger>
-+-----+
-
-*** Floating-Point Numbers
-
- This includes variables typed <<<double>>>, <<<Double>>>, <<<float>>>, and
- <<<Float>>>. When reading the configuration, the text in the XML file is
- converted to binary form using the <<<valueOf()>>> method for the appropriate
- class. This means that the strings can take on any format specified in
- section 3.10.2 of the Java Language Specification. Some samples of valid
- values are <<<1.0>>> and <<<6.02E+23>>>.
-
-+-----+
- /**
- * My Double.
- */
- @Parameter
- private Double myDouble;
-+-----+
-
-+-----+
-<myDouble>1.0</myDouble>
-+-----+
-
-*** Dates
-
- This includes variables typed <<<Date>>>. When reading the configuration,
- the text in the XML file is converted using one of the following date
- formats: "<<<yyyy-MM-dd HH:mm:ss.S a>>>" (a sample date is "2005-10-06
- 2:22:55.1 PM") or "<<<yyyy-MM-dd HH:mm:ssa>>>" (a sample date is "2005-10-06
- 2:22:55PM"). Note that parsing is done using <<<DateFormat.parse()>>> which
- allows some leniency in formatting. If the method can parse a date and time
- out of what is specified it will do so even if it doesn't exactly match the
- patterns above. Example:
-
-+-----+
- /**
- * My Date.
- */
- @Parameter
- private Date myDate;
-+-----+
-
-+-----+
-<myDate>2005-10-06 2:22:55.1 PM</myDate>
-+-----+
-
-*** Files and Directories
-
- This includes variables typed <<<File>>>. When reading the configuration,
- the text in the XML file is used as the path to the desired file or
- directory. If the path is relative (does not start with <<</>>> or a drive
- letter like <<<C:>>>), the path is relative to the directory containing
- the POM. Example:
-
-+-----+
- /**
- * My File.
- */
- @Parameter
- private File myFile;
-+-----+
-
-+-----+
-<myFile>c:\temp</myFile>
-+-----+
-
-*** URLs
-
- This includes variables typed <<<URL>>>. When reading the configuration, the
- text in the XML file is used as the URL. The format must follow the RFC 2396
- guidelines, and looks like any web browser URL
- (<<<scheme://host:port/path/to/file>>>). No restrictions are placed on the
- content of any of the parts of the URL while converting the URL.
-
-+-----+
- /**
- * My URL.
- */
- @Parameter
- private URL myURL;
-+-----+
-
-+-----+
-<myURL>http://maven.apache.org</myURL>
-+-----+
-
-*** Plain Text
-
- This includes variables typed <<<char>>>, <<<Character>>>,
<<<StringBuffer>>>,
- and <<<String>>>. When reading the configuration, the text in the XML file
is
- used as the value to be assigned to the parameter. For <<<char>>> and
- <<<Character>>> parameters, only the first character of the text is used.
-
-*** Enums
-
- Enumeration type parameters can also be used. First you need to define
- your enumeration type and afterwards you can use the enumeration type
- in the parameter definition:
-
-+-----+
- public enum Color {
- GREEN,
- RED,
- BLUE
- }
-
- /**
- * My Enum
- */
- @Parameter
- private Color myColor;
-+-----+
-
- So lets have a look like you can use such enumeration in your pom
configuration:
-
-+-----+
-<myColor>GREEN</myColor>
-+-----+
-
- You can also use elements from the enumeration type as defaultValues like the
- following:
-
-+-----+
- public enum Color {
- GREEN,
- RED,
- BLUE
- }
-
- /**
- * My Enum
- */
- @Parameter(defaultValue = "GREEN")
- private Color myColor;
-+-----+
-
-
-** Parameter Types With Multiple Values
-
- Listed below are the various types of composite objects which can be used as
- parameters in your mojos, along with any rules on how the values in the
- POM are interpreted. In general, the class of the object created to hold the
- parameter value (as well as the class for each element within the parameter
- value) is determined as follows (the first step which yields a valid class
- is used):
-
- [[1]] If the XML element contains an <<<implementation>>> hint attribute,
that is used
-
- [[2]] If the XML tag contains a <<<.>>>, try that as a fully qualified class
name
-
- [[3]] Try the XML tag (with capitalized first letter) as a class in the same
package as the mojo/object being
- configured
-
- [[4]] For arrays, use the component type of the array (for example, use
<<<String>>>
- for a <<<String[]>>> parameter); for collections and maps, use the
- class specified in the mojo configuration for the collection or map;
- use <<<String>>> for entries in a collection and values in a map
-
- []
-
- Once the type for the element is defined, the text in the XML file is
- converted to the appropriate type of object
-
-
-*** Arrays
-
- Array type parameters are configured by specifying the parameter multiple
- times. Example:
-
-+-----+
- /**
- * My Array.
- */
- @Parameter
- private String[] myArray;
-+-----+
-
-+-----+
-<myArray>
- <param>value1</param>
- <param>value2</param>
-</myArray>
-+-----+
-
-*** Collections
-
- This category covers any class which implements <<<java.util.Collection>>>
- such as <<<ArrayList>>> or <<<HashSet>>>. These parameters are configured by
- specifying the parameter multiple times just like an array. Example:
-
-+-----+
- /**
- * My List.
- */
- @Parameter
- private List myList;
-+-----+
-
-+-----+
-<myList>
- <param>value1</param>
- <param>value2</param>
-</myList>
-+-----+
-
- For details on the mapping of the individual collection elements, see
- {{{../mini/guide-configuring-plugins.html#Mapping_Lists}Mapping Lists}}.
-
-*** Maps
-
- This category covers any class which implements <<<java.util.Map>>>
- such as <<<HashMap>>> but does <<not>> implement <<<java.util.Properties>>>.
- These parameters are configured by including XML tags in the form
- <<< <key>value</key> >>> in the parameter configuration. Example:
-
-+-----+
- /**
- * My Map.
- */
- @Parameter
- private Map myMap;
-+-----+
-
-+-----+
-<myMap>
- <key1>value1</key1>
- <key2>value2</key2>
-</myMap>
-+-----+
-
-*** Properties
-
- This category covers any map which implements <<<java.util.Properties>>>.
- These parameters are configured by including XML tags in the form
- <<< <property><name>myName</name> <value>myValue</value> </property> >>>
- in the parameter configuration. Example:
-
-+-----+
- /**
- * My Properties.
- */
- @Parameter
- private Properties myProperties;
-+-----+
-
-+-----+
-<myProperties>
- <property>
- <name>propertyName1</name>
- <value>propertyValue1</value>
- </property>
- <property>
- <name>propertyName2</name>
- <value>propertyValue2</value>
- </property>
-</myProperties>
-+-----+
-
-*** Other Object Classes
-
- This category covers any class which does not implement <<<java.util.Map>>>,
- <<<java.util.Collection>>>, or <<<java.util.Dictionary>>>. Example:
-
-+-----+
- /**
- * My Object.
- */
- @Parameter
- private MyObject myObject;
-+-----+
-
-+-----+
-<myObject>
- <myField>test</myField>
-</myObject>
-+-----+
-
- Please see
{{{../mini/guide-configuring-plugins.html#Mapping_Complex_Objects}Mapping
Complex Objects}} for details
- on the strategy used to configure those kind of parameters.
-
* Using Setters
You are not restricted to using private field mapping which is good if you
are trying to make you Mojos resuable
