Description

The Named Parameter Converter can be used to convert command line input defined as named parameters in Java.

You can define easily the arguments and apply them together with the args[] string array and let it convert to a map or bean.

Beneath a parameter name you can define various aliases to be used as parameter name for the same parameter.

There are many definitions of named parameters around. For the Named Parameter Converter the following definitions are used.

• A named parameter consists of name and a value part.
• Name and value part are separated by one or more whitespace characters.
• Whitespace characters can not be used in name or value. There is no escape mechanism implemented yet. Whitespaces are not even allowed in lists separated by commata.
• The name must be preceeded by exactly one minus '-' character.
• Several named parameters can be defined in a command line as long as a parameter is not defined twice or more by the name or an alias.
• Lists can be added in a parameter value by a string separating the list elements by commata.
• Thus a comma cannot be used as a character in a value of a list. There is no escaping mechanism for this yet.

Use Cases

1. Ease of implementation of command line named parameters.

Language and Version

The Named Parameter Converter version 1.0.0 and later are compiled in the programming language Java in version 1.6.

The Named Parameter Converter version 0.0.0 is compiled in the programming language Java in version 1.8.

API

The following classes define the API of the Named Parameter Converter:

• ch.lyrer.walter.namedparameter.converter.NamedArgumentValidatingConverter
• ch.lyrer.walter.namedparameter.converter.ArgumentDefinition<T, DT>
• ch.lyrer.walter.namedparameter.converter.ArgumentDefinitionContainer

Class NamedArgumentValidatingConverter

The class ch.lyrer.walter.namedparameter.converter.NamedArgumentValidatingConverter has two convertArgs methods:

• Map<String, Object> convertArgs(String[] args, ArgumentDefinitionContainer argumentDefinitions)
• <T> T convertArgs(String[] args, ArgumentDefinitionContainer argumentDefinitions, Class<T> targetBeanType)

Both methods convert named parameters. The first method returns a converted map whereas the second method returns a bean object. Both methods do the following:

• Convert named parameters defined in the args[]string array as a Map or Bean.
• The parameter argumentDefinitions contains the definitions of the named parameters. With these definitions named parameters are parsed, validated and converted.

Class ArgumentDefinition

The class ch.lyrer.walter.namedparameter.converter.ArgumentDefinition defines one named parameter.

The information stored in the ArgumentDefinition is used to define, validate and convert the named parameter by the Named Parameter Converter.

The ArgumentDefinition must be configured programmatically.

There are two constructors you can use:

• ArgumentDefinition(String name, Class<T> type, Class<DT> dependentType, Set<String> aliases, boolean isMandatory)
• ArgumentDefinition(String name, Class<T> type, Set<String> aliases, boolean isMandatory)

The second constructor omits dependentType DT. The dependentType is used for classing having a single generic (multiple generics are not supported yet). Void is used for dependentType in the second constructor.

The constructor's parameter are defined as following:

• String name: Name of the parameter. This is also the name of the key in the converted map or the field name in the converted Bean.
• Class<T> type: The type of the parameter. Only the following types (or sub types of it) are allowed and accepted:
  • short
  • java.lang.Short
  • int
  • java.lang.Integer
  • long
  • java.lang.Long
  • float
  • java.lang.Float
  • double
  • java.lang.Double
  • byte
  • java.lang.Byte
  • boolean
  • java.lang.Boolean
  • char
  • java.lang.Character
  • java.lang.CharSequence
  • java.lang.Enum
  • java.io.File
  • java.util.List
• Class<DT> dependentType: An additional dependent type of the type above can be added. It uses the same types as defined above. Excepted is java.lang.List and additionally void and java.lang.Void are allowed.
• Set<String> aliases: A set of aliases for the parameter name. This can be used as alias in the command line named parameter. However when a parameter is defined in the command line by the name and one or more alias then a validation exception occurs.
• boolean isMandatory: Indicates whether the named parameter is mandatory or optional.

Several ArgumentDefinition instances can be added to the ArgumentDefinitionContainer.

Class ArgumentDefinitionContainer

Class ch.lyrer.walter.namedparameter.converter.ArgumentDefinitionContainer is a container for one or more ArgumentDefinition instances. Incomplete or invalid argument definitions are rejected by an ArgumentDefinitionException. Also the use of the same name or alias in different argument definitions causes a ArgumentDefinitionException.

The class ArgumentDefinitionContainer must be passed over to the validateArgs methods of class NamedArgumentValidatingConverter.

Features

All primitive types and their object representations are validated and converted.

Strings are "converted", too.

Values of any enumeration can be converted as enumeration value.

Lists of such objects can be converted, too (E.g. List<Integer> or List<Enum>). Lists cannot be used recursively (E.g. List<List<String>> is not allowed).

A command line parameter representing a list is defined by the single values separated by commata.

Dependencies of the Named Parameter Converter

The Named Parameter Converter has no dependencies to other classes as defined in the java JRE.

License

Apache Lisense 2.0

Disclaimer

The author cannot be made responsible for any damage caused by the Name Parameter Converter.
The usage of the Name Parameter Converter is on own risk.
The code is designed and implemented on best know-how and with good intensions by the author.

Author

Walter Lyrer

Other projects from same author

Converter Generator
StrategyStateGenerator

Notes

The wiki uses Markdown syntax.

Project Members:

• Walter Lyrer (admin)