Class CLIDefinitionParser

java.lang.Object

org.tquadrat.foundation.config.internal.CLIDefinitionParser

@ClassVersion(sourceVersion="$Id: CLIDefinitionParser.java 1258 2026-06-04 18:33:06Z tquadrat $")
@API(status=INTERNAL,
     since="0.0.1")
public final class CLIDefinitionParser
extends Object

Parses an XML CLI definition file.

Author:

Thomas Thrien (thomas.thrien@tquadrat.org)

Version:

$Id: CLIDefinitionParser.java 1258 2026-06-04 18:33:06Z tquadrat $

Since:

0.0.1

UML Diagram

⁠

UML Diagram for "org.tquadrat.foundation.config.internal.CLIDefinitionParser"

⁠

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
private static class	CLIDefinitionParser.CLIDefinitionResolver	An implementation of XMLResolver for this parser.
static final class	CLIDefinitionParser.ExceptionLocation	An implementation of Location. that is based on an instance of SAXParseException.

Field Summary

Fields

Modifier and Type	Field	Description
static final String	CLI_DEFINITION_DTD	The name for the CLI definition DTD file: "CLIDefinition.dtd".
static final String	CLI_DEFINITION_XSD	The name for the CLI definition XSD file: "CLIDefinition.xsd".
private final XMLEventReader	m_EventReader	The XML event reader that provides the CLI definition.
private final Map<String,Object>	m_PropertyMap	The property map.
private final String	m_XMLContents	The XML stream.
static final String	MSG_ExpectedStartEvent	The message indicating that a start element was expected, but another event was encountered: "Start event expected: %s".
static final String	MSG_InvalidStringConverter	The message indicating that a provided StringConverter implementation is invalid: "Invalid StringConverter implementation: %s".
static final String	MSG_InvalidValue	The message indicating that an attribute value is invalid: "Value \'%2$s\' for attribute \'%1$s\' is invalid".
static final String	MSG_MissingValue	The message indicating that an attribute does not have a value: "Value for attribute \'%1$s\' is missing".
static final String	MSG_UnexpectedEndEvent	The message indicating that a specific end element was expected, but another end element was encountered: "Unexpected End event: %1$s\n\'%3$s\' does not match the expected \'%2$s\'\n".
static final String	MSG_UnexpectedEvent	The message indicating that an unexpected event was encountered: "Unexpected event: %1$s".
static final String	MSG_WrongAttribute	The message indicating that an unexpected attribute was encountered: "Unexpected attribute: %1$s".
static final String	MSG_WrongElement1	The message indicating that an unexpected start element was encountered: "Expected \'%1$s\', but encountered \'%2$s\'".
static final String	MSG_WrongElement2	The message indicating that an unexpected start element was encountered: "Encountered \'%2$s\' while expected one of: %1$s".
static final String	XMLATTRIBUTE_Handler	The name for the XML attribute 'handler': "handler".
static final String	XMLATTRIBUTE_Index	The name for the XML attribute 'index': "index".
static final String	XMLATTRIBUTE_IsMultiValue	The name for the XML attribute 'isMultiValue': "isMultiValue".
static final String	XMLATTRIBUTE_IsRequired	The name for the XML attribute 'isRequired': "isRequired".
static final String	XMLATTRIBUTE_Key	The name for the XML attribute 'key': "key".
static final String	XMLATTRIBUTE_MetaVar	The name for the XML attribute 'metaVar': "metaVar".
static final String	XMLATTRIBUTE_PropertyName	The name for the XML attribute 'propertyName': "propertyName".
static final String	XMLATTRIBUTE_StringConversion	The name for the XML attribute 'stringConversion': "stringConversion".
static final String	XMLATTRIBUTE_Type	The name for the XML attribute 'type': "type".
static final String	XMLELEMENT_Alias	The name for the XML element 'alias': "alias".
static final String	XMLELEMENT_CLIArgument	The name for the XML element 'argument': "argument".
static final String	XMLELEMENT_CLIDefinition	The name for the XML element 'cliDefinition': "cliDefinition".
static final String	XMLELEMENT_CLIOption	The name for the XML element 'option': "option".
static final String	XMLELEMENT_Format	The name for the XML element 'format': "format".
static final String	XMLELEMENT_Usage	The name for the XML element 'usage': "usage".

Constructor Summary

Constructors

Modifier	Constructor	Description
private	CLIDefinitionParser(InputStream inputStream, Map<String,Object> propertyMap)	Creates a new CLIDefinitionParser instance.

Method Summary

Modifier and Type	Method	Description
private final <T> CmdLineValueHandler<T>	createHandler(Class<? extends T> type, Class<?> processClass, StringConverter<? extends T> stringConverter)	Creates the instance for the command line value handler based on the given class for the type and class for the handler implementation.
private final <T> StringConverter<T>	createStringConverter(Class<?> type, Class<? extends StringConverter<?>> stringConverterClass)	Creates the instance for the string converter based on the given class for the type and class for the string converter implementation.
private final List<CLIDefinition>	execute()	Executes the parsing.
static final URL	getCLIDefinitionDTDURL()	Retrieves the URL for the CLI definition DTD file from the resources.
static final URL	getCLIDefinitionXSDURL()	Retrieves the URL for the CLI definition XSD file from the resources.
private final String	handleAlias(StartElement element)	Handles the "alias" element.
private CLIDefinition	handleArgument(StartElement element)	Handles the "argument" element.
private final List<CLIDefinition>	handleCLIDefinition(StartElement element)	Handles the "cliDefinition" element.
private final String	handleFormat(StartElement element)	Handles the "format" element.
private final CLIDefinition	handleOption(StartElement element)	Handles the "option" element.
private final Map<String,String>	handleUsage(StartElement element)	Handles the "usage" element.
static final List<CLIDefinition>	parse(InputStream inputStream, Map<String,Object> propertyMap, boolean validate)	Parses the given InputStream.
private static final Class<? extends CmdLineValueHandler<?>>	processAttrHandler(Attribute attribute)	Processes the attribute "handler".
private static final String	processAttrName(Attribute attribute)	Processes the attribute "name".
private static final String	processAttrPropertyName(Attribute attribute)	Processes the attribute "propertyName".
private static final Class<? extends StringConverter<?>>	processAttrStringConversion(Attribute attribute)	Processes the attribute "stringConversion".
private static final Class<?>	processAttrType(Attribute attribute)	Processes the attribute "type".
static final InputStream	retrieveCLIDefinitionDTD()	Retrieves the CLI definition DTD file from the resources.
static final InputStream	retrieveCLIDefinitionXSD()	Retrieves the CLI definition XSD file from the resources.
private final Optional<Class<? extends CmdLineValueHandler<?>>>	retrieveValueHandlerClass(Class<?> propertyClass)	Retrieves the class for the value handler if the property class is not an enum type.
private final void	validate()	Validates the given XML.

Methods inherited from class Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details

CLI_DEFINITION_DTD

@API(status=INTERNAL,
     since="0.0.1")
public static final String CLI_DEFINITION_DTD

The name for the CLI definition DTD file: "CLIDefinition.dtd".

See Also:

• Constant Field Values

CLI_DEFINITION_XSD

@API(status=INTERNAL,
     since="0.0.1")
public static final String CLI_DEFINITION_XSD

The name for the CLI definition XSD file: "CLIDefinition.xsd".

See Also:

• Constant Field Values

MSG_ExpectedStartEvent

public static final String MSG_ExpectedStartEvent

The message indicating that a start element was expected, but another event was encountered: "Start event expected: %s".

See Also:

• Constant Field Values

MSG_InvalidStringConverter

public static final String MSG_InvalidStringConverter

The message indicating that a provided StringConverter implementation is invalid: "Invalid StringConverter implementation: %s".

See Also:

• Constant Field Values

MSG_InvalidValue

public static final String MSG_InvalidValue

The message indicating that an attribute value is invalid: "Value \'%2$s\' for attribute \'%1$s\' is invalid".

See Also:

• Constant Field Values

MSG_MissingValue

public static final String MSG_MissingValue

The message indicating that an attribute does not have a value: "Value for attribute \'%1$s\' is missing".

See Also:

• Constant Field Values

MSG_UnexpectedEndEvent

public static final String MSG_UnexpectedEndEvent

The message indicating that a specific end element was expected, but another end element was encountered: "Unexpected End event: %1$s\n\'%3$s\' does not match the expected \'%2$s\'\n".

See Also:

• Constant Field Values

MSG_UnexpectedEvent

public static final String MSG_UnexpectedEvent

The message indicating that an unexpected event was encountered: "Unexpected event: %1$s".

See Also:

• Constant Field Values

MSG_WrongAttribute

public static final String MSG_WrongAttribute

The message indicating that an unexpected attribute was encountered: "Unexpected attribute: %1$s".

See Also:

• Constant Field Values

MSG_WrongElement1

public static final String MSG_WrongElement1

The message indicating that an unexpected start element was encountered: "Expected \'%1$s\', but encountered \'%2$s\'".

See Also:

• Constant Field Values

MSG_WrongElement2

public static final String MSG_WrongElement2

The message indicating that an unexpected start element was encountered: "Encountered \'%2$s\' while expected one of: %1$s".

See Also:

• Constant Field Values

XMLATTRIBUTE_Handler

public static final String XMLATTRIBUTE_Handler

The name for the XML attribute 'handler': "handler".

See Also:

• Constant Field Values

XMLATTRIBUTE_Index

public static final String XMLATTRIBUTE_Index

The name for the XML attribute 'index': "index".

See Also:

• Constant Field Values

XMLATTRIBUTE_IsMultiValue

public static final String XMLATTRIBUTE_IsMultiValue

The name for the XML attribute 'isMultiValue': "isMultiValue".

See Also:

• Constant Field Values

XMLATTRIBUTE_IsRequired

public static final String XMLATTRIBUTE_IsRequired

The name for the XML attribute 'isRequired': "isRequired".

See Also:

• Constant Field Values

XMLATTRIBUTE_Key

public static final String XMLATTRIBUTE_Key

The name for the XML attribute 'key': "key".

See Also:

• Constant Field Values

XMLATTRIBUTE_MetaVar

public static final String XMLATTRIBUTE_MetaVar

The name for the XML attribute 'metaVar': "metaVar".

See Also:

• Constant Field Values

XMLATTRIBUTE_PropertyName

public static final String XMLATTRIBUTE_PropertyName

The name for the XML attribute 'propertyName': "propertyName".

See Also:

• Constant Field Values

XMLATTRIBUTE_StringConversion

public static final String XMLATTRIBUTE_StringConversion

The name for the XML attribute 'stringConversion': "stringConversion".

See Also:

• Constant Field Values

XMLATTRIBUTE_Type

public static final String XMLATTRIBUTE_Type

The name for the XML attribute 'type': "type".

See Also:

• Constant Field Values

XMLELEMENT_Alias

public static final String XMLELEMENT_Alias

The name for the XML element 'alias': "alias".

See Also:

• Constant Field Values

XMLELEMENT_CLIArgument

public static final String XMLELEMENT_CLIArgument

The name for the XML element 'argument': "argument".

See Also:

• Constant Field Values

XMLELEMENT_CLIDefinition

public static final String XMLELEMENT_CLIDefinition

The name for the XML element 'cliDefinition': "cliDefinition".

See Also:

• Constant Field Values

XMLELEMENT_CLIOption

public static final String XMLELEMENT_CLIOption

The name for the XML element 'option': "option".

See Also:

• Constant Field Values

XMLELEMENT_Format

public static final String XMLELEMENT_Format

The name for the XML element 'format': "format".

See Also:

• Constant Field Values

XMLELEMENT_Usage

public static final String XMLELEMENT_Usage

The name for the XML element 'usage': "usage".

See Also:

• Constant Field Values

m_EventReader

private final XMLEventReader m_EventReader

The XML event reader that provides the CLI definition.

m_PropertyMap

private final Map<String,Object> m_PropertyMap

The property map.

m_XMLContents

private final String m_XMLContents

The XML stream.

Constructor Details

CLIDefinitionParser

private CLIDefinitionParser(InputStream inputStream,
 Map<String,Object> propertyMap)
                     throws XMLStreamException,
IOException

Creates a new CLIDefinitionParser instance.

Parameters:

inputStream - The input stream that should contain the XML CLI definition.

propertyMap - The target data structure for the values from the command line.

Throws:

XMLStreamException - Cannot create a XMLEventReader instance for the given input stream.

IOException - Cannot read the given input stream.

Method Details

createHandler

private final <T> CmdLineValueHandler<T> createHandler(Class<? extends T> type,
 Class<?> processClass,
 StringConverter<? extends T> stringConverter)
                                                throws IllegalArgumentException

Creates the instance for the command line value handler based on the given class for the type and class for the handler implementation. If processClass is null, the method will search for a specialised handler class in the internal registry; if none can be found, and stringConverter is not null, it creates an instance of SimpleCmdLineValueHandler with it. But if stringConverter is null, an exception will be thrown.

If processClass is not null, it has to be a class that implements CmdLineValueHandler. In that case that class will be instantiated.

Type Parameters:

T - The type of the property the set.

Parameters:

type - The class for the property to set.

processClass - This is either the handler class or null.

stringConverter - The StringConverter instance for the property; can be null.

Returns:

The command line value handler instance.

Throws:

IllegalArgumentException - A command line value handler instance cannot be created.

createStringConverter

private final <T> StringConverter<T> createStringConverter(Class<?> type,
 Class<? extends StringConverter<?>> stringConverterClass)

Creates the instance for the string converter based on the given class for the type and class for the string converter implementation. If stringConverterClass is null, the method will search for an implementation class in the internal registry; if none can be found, null will be returned.

Type Parameters:

T - The type of the property to convert.

Parameters:

type - The class for the property to convert.

stringConverterClass - The String converter class or null.

Returns:

The String converter instance.

execute

private final List<CLIDefinition> execute()
                                   throws XMLStreamException

Executes the parsing.

Returns:

The parsed CLI definition.

Throws:

XMLStreamException - Cannot parse the given input stream.

getCLIDefinitionDTDURL

@API(status=INTERNAL,
     since="0.0.1")
public static final URL getCLIDefinitionDTDURL()

Retrieves the URL for the CLI definition DTD file from the resources.

Returns:

The URL for the file.

getCLIDefinitionXSDURL

@API(status=INTERNAL,
     since="0.0.1")
public static final URL getCLIDefinitionXSDURL()

Retrieves the URL for the CLI definition XSD file from the resources.

Returns:

The URL for the file.

handleAlias

private final String handleAlias(StartElement element)
                          throws XMLStreamException

Handles the "alias" element.

Parameters:

element - The current element.

Returns:

The option alias.

Throws:

XMLStreamException - A problem occurred while parsing the element.

handleArgument

private CLIDefinition handleArgument(StartElement element)
                              throws XMLStreamException

Handles the "argument" element.

Parameters:

element - The current element.

Returns:

The parsed CLI definition.

Throws:

XMLStreamException - A problem occurred while parsing the element.

handleCLIDefinition

private final List<CLIDefinition> handleCLIDefinition(StartElement element)
                                               throws XMLStreamException

Handles the "cliDefinition" element.

Parameters:

element - The current element.

Returns:

The parsed CLI definition.

Throws:

XMLStreamException - A problem occurred while parsing the element.

handleFormat

private final String handleFormat(StartElement element)
                           throws XMLStreamException

Handles the "format" element.

Parameters:

element - The current element.

Returns:

The format.

Throws:

XMLStreamException - A problem occurred while parsing the element.

handleOption

private final CLIDefinition handleOption(StartElement element)
                                  throws XMLStreamException

Handles the "option" element.

Parameters:

element - The current element.

Returns:

The parsed CLI definition.

Throws:

XMLStreamException - A problem occurred while parsing the element.

handleUsage

private final Map<String,String> handleUsage(StartElement element)
                                      throws XMLStreamException

Handles the "usage" element.

Parameters:

element - The current element.

Returns:

The usage and the usage key.

Throws:

XMLStreamException - A problem occurred while parsing the element.

parse

public static final List<CLIDefinition> parse(InputStream inputStream,
 Map<String,Object> propertyMap,
 boolean validate)
                                       throws XMLStreamException,
IOException

Parses the given InputStream.

Parameters:

inputStream - The input stream that should contain the XML CLI definition.

propertyMap - The target data structure for the values from the command line.

validate - true if the given XML should be validated against the schema CLIDefinition.xsd previous to parsing it, false if the validation can be omitted.

Returns:

The parsed CLI definition.

Throws:

XMLStreamException - Cannot parse the given input stream.

IOException - Cannot read the given input stream.

processAttrHandler

private static final Class<? extends CmdLineValueHandler<?>> processAttrHandler(Attribute attribute)
                                                                         throws XMLStreamException

Processes the attribute "handler".

Parameters:

attribute - The attribute.

Returns:

The handler class.

Throws:

XMLStreamException - The attribute is somehow invalid.

processAttrName

private static final String processAttrName(Attribute attribute)
                                     throws XMLStreamException

Processes the attribute "name".

Parameters:

attribute - The attribute.

Returns:

The property name.

Throws:

XMLStreamException - The attribute is somehow invalid.

processAttrPropertyName

private static final String processAttrPropertyName(Attribute attribute)
                                             throws XMLStreamException

Processes the attribute "propertyName".

Parameters:

attribute - The attribute.

Returns:

The property name.

Throws:

XMLStreamException - The attribute is somehow invalid.

processAttrStringConversion

private static final Class<? extends StringConverter<?>> processAttrStringConversion(Attribute attribute)
                                                                              throws XMLStreamException

Processes the attribute "stringConversion".

Parameters:

attribute - The attribute.

Returns:

The StringConverter implementation class.

Throws:

XMLStreamException - The attribute is somehow invalid.

processAttrType

private static final Class<?> processAttrType(Attribute attribute)
                                       throws XMLStreamException

Processes the attribute "type".

Parameters:

attribute - The attribute.

Returns:

The class for the type.

Throws:

XMLStreamException - The attribute is somehow invalid.

retrieveCLIDefinitionDTD

@API(status=INTERNAL,
     since="0.0.1")
public static final InputStream retrieveCLIDefinitionDTD()

Retrieves the CLI definition DTD file from the resources.

Returns:

The input stream for the file.

retrieveCLIDefinitionXSD

@API(status=INTERNAL,
     since="0.0.1")
public static final InputStream retrieveCLIDefinitionXSD()

Retrieves the CLI definition XSD file from the resources.

Returns:

The input stream for the file.

retrieveValueHandlerClass

private final Optional<Class<? extends CmdLineValueHandler<?>>> retrieveValueHandlerClass(Class<?> propertyClass)

Retrieves the class for the value handler if the property class is not an enum type.

enum types have to be handled separately.

Parameters:

propertyClass - The class of the property that should be set.

Returns:

An instance of Optional that holds the effective handler class if the property class is not an enum.

validate

private final void validate()
                     throws IOException,
XMLStreamException

Validates the given XML.

Throws:

XMLStreamException - The validation failed.

IOException - Cannot read the given input stream.