CommandLinePropertySource

Abstract base class for PropertySource implementations backed by command line arguments. The parameterized type T represents the underlying source of command line options. This may be as simple as a String array in the case of SimpleCommandLinePropertySource, or specific to a particular API such as JOpt's OptionSet in the case of JOptCommandLinePropertySource. 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(); }

 @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; } }

As an alternative to injecting the Environment, Spring's @Value annotation may be used to inject these properties, given that a 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; } // ... }

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

 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 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.

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 property. If multiple non-option arguments are specified, the value of this property will be a comma-delimited string containing all of 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

 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(); }

Author
Chris Beams

Since
3.1

See Also
PropertySourceSimpleCommandLinePropertySourceJOptCommandLinePropertySource

Constructors

Properties

Functions

Inheritors

 public static void main(String[] args) { OptionParser parser = new OptionParser(); parser.accepts("option1"); parser.accepts("option2").withRequiredArg(); OptionSet options = parser.parse(args); PropertySource ps = new JOptCommandLinePropertySource(options); // ... }

--optName[=optValue]

 --foo --foo=bar --foo="bar then baz" --foo=bar,baz,biz

 -foo --foo bar --foo = bar --foo=bar --foo=baz --foo=biz

 public static void main(String[] args) { PropertySource ps = new SimpleCommandLinePropertySource(args); // ... }