String arrays as command line arguments for maven plugin

Question

I\'m writing a maven plugin that has a parameter that\'s a String[].

Like this:

/**
* @parameter expression=\"${args}\"
*/
protected String[] args;
<         


        

Answer 1

The way to specify a list of values via system property, for a plugin depends on how up to date the plugin is.

However, if you are dealing with a proper implemented plugin that is up to date, then the correct way of specifying an array of values to a plugin is via comma separated strings.

Here is a reference: http://blog.sonatype.com/2011/03/configuring-plugin-goals-in-maven-3/

Here is a quote from the reference:

For many plugin parameters it is occasionally convenient to specify their values from the command line via system properties. In the past, this was limited to parameters of simple types like String or Boolean. The latest Maven release finally allows plugin users to configure collections or arrays from the command line via comma-separated strings. Take for example a plugin parameter like this:

Going a little bit further, we can look at more concrete example. Consider, the Wildfly maven plugin. This plugin has a deprecated configuration property called: jvmArgs.

This was expected to be passed in as a space separated list of values. As we all know, in the command line, messing around with spaces is not adorable. So if we look at the definition of this paramter in the plugin mojo code, you will find something like this (here goes another quote).

/**
 * A space delimited list of JVM arguments.
 *
 * @deprecated use {@link #javaOpts}
 */
@Parameter(alias = "jvm-args", property = PropertyNames.JVM_ARGS)
@Deprecated
private String jvmArgs;

So this is the old way of doing stuff.

Now, if you are using the latest version of this plugin (e.g. Alpha6). Then the source code will have a nice new field called javaOpts. Let us look at what the field looks like in the code.

/**
 * The JVM options to use.
 */
@Parameter(alias = "java-opts", property = PropertyNames.JAVA_OPTS)
private String[] javaOpts;

So what we see is that we have a nice array field in the StartMojo. This array field is properly annoted. And the maven engine will do the heavy lifting of setting the values into the Mojo.

When you want to pump data into this field via the command line, you would in you batch file specify something of the form:

-Dwildfly.javaOpts="-Xmx1536M,-Xms1536M,-XX:MaxMetaspaceSize=512M,-XX:-HeapDumpOnOutOfMemoryError"

If you try the samething using sapces instead of commans. I will show you what happens:

[INFO] STANDALONE server is starting up. Invalid maximum heap size: -Xmx1536M -XX:MaxMetaspaceSize=512m -XX:-HeapDumpOnOutOfMemoryError

So you see, maven when it with swallowed my system property full of spaces it did not do a string split. So Wildfly tried to setup the jvm memory settings as if the max memory was that full string. On the other hand, when I use commas to separate it, the Mojo is properly enriched and I can take control of the memory settings of the app server when it starts up.

And of course, you want to use system properties and not pom.xml XML configuration, for tasks like setting up Jenkins jobs. With system properties you are rather more flexible.

That is it.

Answer 2

According to Sonatype's blog here, if you are a plugin developer and

1. use Maven 3

2. and annotate your array/collection type plugin parameter using annotation like:

   /** @parameter expression="${args}" */

In this way, the plugin parameter can be processed by Maven automatically and plugin users can provide the plugin array/collection type parameters via CLI using a comma separated system property like mvn myplugin:mygoal -Dargs=a,b,c

Answer 3

To update on @nybon’s answer a bit, it seems

@Parameter(property="your.param")
private List<String> yourParam;

works, at least when using maven-plugin-annotations:3.5 in Maven 3.5.0. Running with

-Dyour.param=val1,val2

sets the list.

Answer 4

Latest maven (3.0.3) should works with:

-DaddArgs=arg1,arg2,arg3

Answer 5

You can't do it directly as far as I know, but it is pretty common practice to accept a delimited String and split that into an array yourself.

For example the maven-site-plugin allows you to specify a comma-delimited String of locales, while the maven-scala-plugin handles this by allowing you to define the arguments with a pipe separator. You can look at the relevant Mojos to see how the argument is processed.

Some example usages below:

site-plugin:

-Dlocales=enGB,frFR

scala-plugin:

-DaddArgs=arg1|arg2|arg3

Update: if you want to handle this more elegantly, you could use maven-shared-io to allow definition of an external descriptor file, then pass the descriptor location as a property. This means a single command-line argument can reference a structure of configuration.

If this sounds like it might work for you, have a look at this answer that describes how to use external descriptors in the properties plugin, or this answer that does similar for the xml-maven-plugin. Or you can just look at the assembly-plugin for ideas.