NamedParameterConverter Files

ÿþ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 0.0.0 and later are compiled in the programming language Java in version 1.6.





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)

- Map<String, Object> convertArgs(String[] args, ArgumentDefinitionContainer argumentDefinitions)



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. 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. Thus Void is used for dependentType.



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





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

The usage of the Named-Parameter-Converter is on own risk.

The code is designed and implemented on best know-how and with good intensions by the author.

Escpecially is to mention that the generated code of the Converter-Generator is not guaranteed to run instantly correct.

Manual supervision is necessary and crucial.





Author

======



Walter Lyrer



#### Other projects from same author



[Converter Generator](https://sourceforge.net/projects/convertergenerator/)

[Strategy Generator](https://sourceforge.net/projects/strategygenerator/)