Package org.apache.juneau.collections

Class Args

java.lang.Object
java.util.AbstractMap<K,V>
java.util.HashMap<K,V>
java.util.LinkedHashMap<String,Object>
org.apache.juneau.collections.JsonMap
org.apache.juneau.collections.Args
All Implemented Interfaces:
Serializable, Cloneable, Map<String,Object>
public class Args extends JsonMap
Utility class to make it easier to work with command-line arguments pass in through a main(String[] args) method.

Used to parse command-line arguments of the form "[zero or more main arguments] [zero or more optional arguments]".

The format of a main argument is a token that does not start with '-'.

The format of an optional argument is "-argName [zero or more tokens]".

Command-line examples
  • java com.sample.MyClass mainArg1
  • java com.sample.MyClass mainArg1 mainArg2
  • java com.sample.MyClass mainArg1 -optArg1
  • java com.sample.MyClass -optArg1
  • java com.sample.MyClass mainArg1 -optArg1 optArg1Val
  • java com.sample.MyClass mainArg1 -optArg1 optArg1Val1 optArg1Val2
  • java com.sample.MyClass mainArg1 -optArg1 optArg1Val1 -optArg1 optArg1Val2
Example:

// Main method with arguments public static void main(String[] _args) { // Wrap in Args Args args = new Args(_args); // One main argument // a1 String a1 = args.getArg(0); // "a1" String a2 = args.getArg(1); // null // Two main arguments // a1 a2 String a1 = args.getArg(0); // "a1" String a2 = args.getArg(1); // "a2" // One main argument and one optional argument with no value // a1 -a2 String a1 = args.getArg(0); boolean hasA2 = args.hasArg("a2"); // true boolean hasA3 = args.hasArg("a3"); // false // One main argument and one optional argument with one value // a1 -a2 v2 String a1 = args.getArg(0); String a2 = args.getArg("a2"); // "v2" String a3 = args.getArg("a3"); // null // One main argument and one optional argument with two values // a1 -a2 v2a v2b String a1 = a.getArg(0); List<String> a2 = args.getArgs("a2"); // Contains ["v2a","v2b"] List<String> a3 = args.getArgs("a3"); // Empty list // Same as previous, except specify optional argument name multiple times // a1 -a2 v2a -a2 v2b String a1 = args.getArg(0); List<String> a2 = args.getArgs("a2"); // Contains ["v2a","v2b"] }

Main arguments are available through numeric string keys (e.g. "0", "1", ...). So you could use the JsonMap API to convert main arguments directly to POJOs, such as an Enum

// Get 1st main argument as an Enum MyEnum _enum = args.get(MyEnum.class, "0"); // Get 1st main argument as an integer int _int = args.get(int.class, "0");

Equivalent operations are available on optional arguments through the getArg(Class, String) method.

Notes:
  • This class is not thread safe.

  • Constructor Details

    • Args

      public Args(String args)
      Constructor.
      Parameters:
      args - Arguments passed in as a raw command line.

    • Args

      public Args(String[] args)
      Constructor.
      Parameters:
      args - Arguments passed in through a main(String[] args) method.

  • Method Details

    • append

      public Args append(Map<String,Object> values)
      Description copied from class: JsonMap
      Appends all the entries in the specified map to this map.
      Overrides:
      append in class JsonMap
      Parameters:
      values - The map to copy. Can be null.
      Returns:
      This object.

    • append

      public Args append(String key, Object value)
      Description copied from class: JsonMap
      Adds an entry to this map.
      Overrides:
      append in class JsonMap
      Parameters:
      key - The key.
      value - The value.
      Returns:
      This object.

    • appendIf

      public Args appendIf(boolean flag, String key, Object value)
      Description copied from class: JsonMap
      Add if flag is true.
      Overrides:
      appendIf in class JsonMap
      Parameters:
      flag - The flag to check.
      key - The key.
      value - The value.
      Returns:
      This object.

    • filtered

      public Args filtered(Predicate<Object> value)
      Description copied from class: JsonMap
      Enables filtering based on a predicate test.

      If the predicate evaluates to false on values added to this map, the entry will be skipped.

      Overrides:
      filtered in class JsonMap
      Parameters:
      value - The value tester predicate.
      Returns:
      This object.

    • getArg

      public <T> T getArg(Class<T> c, String name)
      Returns the optional argument value converted to the specified object type.

      If the optional arg has multiple values, returns only the first converted value.

      Example:

      // Command: java com.sample.MyClass -verbose true -debug 5 boolean bool = args.getArg(boolean.class, "verbose"); int _int = args.getArg(int.class, "debug");

      Type Parameters:
      T - The class type to convert the value to.
      Parameters:
      c - The class type to convert the value to.
      name - The optional argument name.
      Returns:
      The optional argument value, or blank if the optional argument was not specified.

    • getArg

      public String getArg(int i)
      Returns main argument at the specified index, or null if the index is out of range.

      Can be used in conjunction with hasArg(int) to check for existence of arg.

      // Check for no arguments if (! args.hasArg(0)) printUsageAndExit(); // Get the first argument String firstArg = args.getArg(0);

      Since main arguments are stored as numeric keys, this method is essentially equivalent to...

      // Check for no arguments if (! args.containsKey("0")) printUsageAndExit(); // Get the first argument String firstArg = args.getString("0");

      Parameters:
      i - The index position of the main argument (zero-indexed).
      Returns:
      The main argument value, or "" if argument doesn't exist at that position.

    • getArg

      public String getArg(String name)
      Returns the optional argument value, or blank if the optional argument was not specified.

      If the optional arg has multiple values, returns values as a comma-delimited list.

      Parameters:
      name - The optional argument name.
      Returns:
      The optional argument value, or blank if the optional argument was not specified.

    • getArgs

      public List<String> getArgs(String name)
      Returns the optional argument values as a list of strings.
      Example:

      // Command: java com.sample.MyClass -extraArgs foo bar baz List<String> list1 = args.getArgs("extraArgs"); // ['foo','bar','baz'] List<String> list2 = args.getArgs("nonExistentArgs"); // An empty list

      Parameters:
      name - The optional argument name.
      Returns:
      The optional argument values, or an empty list if the optional argument was not specified.

    • hasArg

      public boolean hasArg(int i)
      Returns true if argument exists at specified index.
      Parameters:
      i - The zero-indexed position of the argument.
      Returns:
      true if argument exists at specified index.

    • hasArg

      public boolean hasArg(String name)
      Returns true if the named argument exists.
      Parameters:
      name - The argument name.
      Returns:
      true if the named argument exists.

    • inner

      public Args inner(Map<String,Object> inner)
      Description copied from class: JsonMap
      Set an inner map in this map to allow for chained get calls.

      If JsonMap.get(Object) returns null, then JsonMap.get(Object) will be called on the inner map.

      In addition to providing the ability to chain maps, this method also provides the ability to wrap an existing map inside another map so that you can add entries to the outer map without affecting the values on the inner map.

      JsonMap map1 = JsonMap.ofJson("{foo:1}"); JsonMap map2 = JsonMap.of().setInner(map1); map2.put("foo", 2); // Overwrite the entry int foo1 = map1.getInt("foo"); // foo1 == 1 int foo2 = map2.getInt("foo"); // foo2 == 2

      Overrides:
      inner in class JsonMap
      Parameters:
      inner - The inner map. Can be null to remove the inner map from an existing map.
      Returns:
      This object.

    • keepAll

      public Args keepAll(String... keys)
      Description copied from class: JsonMap
      The opposite of JsonMap.removeAll(String...).

      Discards all keys from this map that aren't in the specified list.

      Overrides:
      keepAll in class JsonMap
      Parameters:
      keys - The keys to keep.
      Returns:
      This map.

    • modifiable

      public Args modifiable()
      Description copied from class: JsonMap
      Returns a modifiable copy of this map if it's unmodifiable.
      Overrides:
      modifiable in class JsonMap
      Returns:
      A modifiable copy of this map if it's unmodifiable, or this map if it is already modifiable.

    • session

      public Args session(BeanSession session)
      Description copied from class: JsonMap
      Override the default bean session used for converting POJOs.

      Default is BeanContext.DEFAULT, which is sufficient in most cases.

      Useful if you're serializing/parsing beans with transforms defined.

      Overrides:
      session in class JsonMap
      Parameters:
      session - The new bean session.
      Returns:
      This object.

    • setBeanSession

      public Args setBeanSession(BeanSession value)
      Description copied from class: JsonMap
      Sets the BeanSession currently associated with this map.
      Overrides:
      setBeanSession in class JsonMap
      Parameters:
      value - The BeanSession currently associated with this map.
      Returns:
      This object.

    • unmodifiable

      public Args unmodifiable()
      Description copied from class: JsonMap
      Returns an unmodifiable copy of this map if it's modifiable.
      Overrides:
      unmodifiable in class JsonMap
      Returns:
      An unmodifiable copy of this map if it's modifiable, or this map if it is already unmodifiable.