Abstract base class for PropertySource implementations backed by command line arguments. The parameterized type T represents the underlying source of command line options. For instance, SimpleCommandLinePropertySource uses a String array.

Purpose and General Usage

For use in standalone Spring-based applications, i.e. those that are bootstrapped via a traditional main method accepting a String[] of arguments from the command line. In many cases, processing command-line arguments directly within the main method may be sufficient, but in other cases, it may be desirable to inject arguments as values into Spring beans. It is this latter set of cases in which a CommandLinePropertySource becomes useful. A CommandLinePropertySource will typically be added to the Environment of the Spring ApplicationContext, at which point all command line arguments become available through the Environment#getProperty(String) family of methods. For example:

public static void main(String[] args) {
    CommandLinePropertySource clps = ...;
    AnnotationConfigApplicationContext ctx = new AnnotationConfigApplicationContext();
    ctx.getEnvironment().getPropertySources().addFirst(clps);
    ctx.register(AppConfig.class);
    ctx.refresh();
}

With the bootstrap logic above, the AppConfig class may @Inject the Spring Environment and query it directly for properties:

@Configuration
public class AppConfig {

    @Inject Environment env;

    @Bean
    public void DataSource dataSource() {
        MyVendorDataSource dataSource = new MyVendorDataSource();
        dataSource.setHostname(env.getProperty("db.hostname", "localhost"));
        dataSource.setUsername(env.getRequiredProperty("db.username"));
        dataSource.setPassword(env.getRequiredProperty("db.password"));
        // ...
        return dataSource;
    }
}

Because the CommandLinePropertySource was added to the Environment's set of MutablePropertySources using the #addFirst method, it has the highest search precedence, meaning that while "db.hostname" and other properties may exist in other property sources such as the system environment variables, it will be chosen from the command line property source first. This is a reasonable approach given that arguments specified on the command line are naturally more specific than those specified as environment variables.

As an alternative to injecting the Environment, Spring's @Value annotation may be used to inject these properties, given that a PropertySourcesPropertyResolver bean has been registered, either directly or through using the <context:property-placeholder> element. For example:

@Component
public class MyComponent {

    @Value("my.property:defaultVal")
    private String myProperty;

    public void getMyProperty() {
        return this.myProperty;
    }

    // ...
}

Working with option arguments

Individual command line arguments are represented as properties through the usual PropertySource#getProperty(String) and PropertySource#containsProperty(String) methods. For example, given the following command line:

--o1=v1 --o2

'o1' and 'o2' are treated as "option arguments", and the following assertions would evaluate true:

CommandLinePropertySource<?> ps = ...
assert ps.containsProperty("o1") == true;
assert ps.containsProperty("o2") == true;
assert ps.containsProperty("o3") == false;
assert ps.getProperty("o1").equals("v1");
assert ps.getProperty("o2").equals("");
assert ps.getProperty("o3") == null;

Note that the 'o2' option has no argument, but getProperty("o2") resolves to empty string ("") as opposed to null, while getProperty("o3") resolves to null because it was not specified. This behavior is consistent with the general contract to be followed by all PropertySource implementations.

Note also that while "--" was used in the examples above to denote an option argument, this syntax may vary across individual command line argument libraries. For example, a JOpt- or Commons CLI-based implementation may allow for single dash ("-") "short" option arguments, etc.

Working with non-option arguments

Non-option arguments are also supported through this abstraction. Any arguments supplied without an option-style prefix such as "-" or "--" are considered "non-option arguments" and available through the special "nonOptionArgs" property. If multiple non-option arguments are specified, the value of this property will be a comma-delimited string containing all the arguments. This approach ensures a simple and consistent return type (String) for all properties from a CommandLinePropertySource and at the same time lends itself to conversion when used in conjunction with the Spring Environment and its built-in ConversionService. Consider the following example:

--o1=v1 --o2=v2 /path/to/file1 /path/to/file2

In this example, "o1" and "o2" would be considered "option arguments", while the two filesystem paths qualify as "non-option arguments". As such, the following assertions will evaluate true:

CommandLinePropertySource<?> ps = ...
assert ps.containsProperty("o1") == true;
assert ps.containsProperty("o2") == true;
assert ps.containsProperty("nonOptionArgs") == true;
assert ps.getProperty("o1").equals("v1");
assert ps.getProperty("o2").equals("v2");
assert ps.getProperty("nonOptionArgs").equals("/path/to/file1,/path/to/file2");

As mentioned above, when used in conjunction with the Spring Environment abstraction, this comma-delimited string may easily be converted to a String array or list:

Environment env = applicationContext.getEnvironment();
String[] nonOptionArgs = env.getProperty("nonOptionArgs", String[].class);
assert nonOptionArgs[0].equals("/path/to/file1");
assert nonOptionArgs[1].equals("/path/to/file2");

The name of the special "non-option arguments" property may be customized through the setNonOptionArgsPropertyName(String) method. Doing so is recommended as it gives proper semantic value to non-option arguments. For example, if filesystem paths are being specified as non-option arguments, it is likely preferable to refer to these as something like "file.locations" than the default of "nonOptionArgs":

public static void main(String[] args) {
    CommandLinePropertySource clps = ...;
    clps.setNonOptionArgsPropertyName("file.locations");

    AnnotationConfigApplicationContext ctx = new AnnotationConfigApplicationContext();
    ctx.getEnvironment().getPropertySources().addFirst(clps);
    ctx.register(AppConfig.class);
    ctx.refresh();
}

Limitations

This abstraction is not intended to expose the full power of underlying command line parsing APIs such as JOpt or Commons CLI. Its intent is rather just the opposite: to provide the simplest possible abstraction for accessing command line arguments after they have been parsed. So the typical case will involve fully configuring the underlying command line parsing API, parsing the String[] of arguments coming into the main method, and then simply providing the parsing results to an implementation of CommandLinePropertySource. At that point, all arguments can be considered either 'option' or 'non-option' arguments and as described above can be accessed through the normal PropertySource and Environment APIs.