Config (j(s)-lib Commons 1.2.0 API)

java.lang.Object
- js.lang.Config

```
public class Config
extends Object
```
Generic configuration object with XML like structure. A configuration object has a name, value, attributes, properties and optional parent and child configuration objects. Its structure closely resemble a XML tree structure. Therefore the usual way to load configuration object is from XML files.
One may wonder why to add extra processing and not use directly XML files. One reason would be XML has heavy dependencies, and this matter on embedded devices. The second is configuration object is not loaded only from XML. It can be loaded from Java properties files; in fact there is no formal requirements for specific format. This class can be used to unify varied configuration sources.
Configuration object resemble XML element. Its name is element tag name and attributes are mapped directly. Value is element text content and parent and children fields are similar and use for the same purpose: describe the tree structure. The only specialized field is properties that are stored in a standard Properties object.
```
 <emails repository="/srv/emails" files-pattern="*.html">
        <property name="mail.transport.protocol" value="smtp" />
        <property name="mail.debug" value="true" />
 </emails>
 
```
Above XML fragment describe an configuration object with name emails, two attributes repository and files-pattern and two properties, mail.transport.protocol and mail.debug.
Configuration object is not reusable and is not thread safe. Anyway, if a configurable instance does not alter state using setters, configuration object still can be used in a concurrent context.
Version:

final

Author:

Iulian Rotaru

Field Summary

Fields
Modifier and Type	Field and Description
`private Map<String,String>`	`attributes` Optional attributes list, possible empty.
`private List<Config>`	`children` Children list, possible empty.
`private Converter`	`converter` Converter for objects conversion to / from strings.
`private String`	`name` Configuration object name.
`private Config`	`parent` Parent reference, null if configuration object is root.
`private Properties`	`properties` Optional properties, possible empty.
`private Set<String>`	`usedProperties` Keep track of used properties.
`private String`	`value` Configuration object value.

Constructor Summary

Constructors
Constructor and Description

Config(String name)
Create configuration object with name.

Constructors
Constructor and Description
`Config(String name)` Create configuration object with name.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`addChild(Config child)` Add child configuration object.
`void`	`dump()` Dump configuration object tree to standard out, for debugging purposes.
`List<Config>`	`findChildren(String... name)` Find configuration object children with requested names.
`String`	`getAttribute(String name)` Get attribute value or null if there is no attribute with requested name.
`<T> T`	`getAttribute(String name, Class<T> type)` Get attribute value converted to requested type or null if there is no attribute with requested name.
`<T> T`	`getAttribute(String name, Class<T> type, T defaultValue)` Get attribute value converted to requested type or default value if there is no attribute with requested name.
`String`	`getAttribute(String name, String defaultValue)` Get attribute value or given default value if there is no attribute with requested name.
`Config`	`getChild(int index)` Get configuration object child by index.
`Config`	`getChild(String name)` Get configuration object first child with requested name or null if there is no child with given name.
`List<Config>`	`getChildren()` Get configuration object children list.
`int`	`getChildrenCount()` Get configuration object children count.
`String`	`getChildValue(String name)` Get named child string value or null if child not found or it has no value.
`String`	`getName()` Get configuration object name.
`Config`	`getParent()` Get configuration object parent.
`Properties`	`getProperties()` Get configuration object Java raw properties.
`String`	`getProperty(String name)` Get configuration object property value or null if there is no property with requested name.
`<T> T`	`getProperty(String name, Class<T> type)` Get configuration object property converter to requested type or null if there is no property with given name.
`<T> T`	`getProperty(String name, Class<T> type, T defaultValue)` Get configuration object property converter to requested type or default value if there is no property with given name.
`String`	`getProperty(String name, String defaultValue)` Get configuration object property value or default value if there is no property with requested name.
`Config`	`getRoot()` Get root of the tree this configuration object is part of.
`Properties`	`getUnusedProperties()` Get properties not yet used at the moment this method is executed.
`String`	`getValue()` Get this configuration object string value, possible null.
`<T> T`	`getValue(Class<T> type)` Get this configuration object value converted to requested type.
`boolean`	`hasAttribute(String name)` Test if configuration object has an attribute with requested name.
`boolean`	`hasAttribute(String name, String value)` Test if configuration object has an attribute with requested name and value.
`boolean`	`hasChild(String name)` Test if configuration object has at least a child with requested name.
`boolean`	`hasChildren()` Test if configuration object has children.
`boolean`	`hasProperty(String name)` Test if configuration object has named property.
`private void`	`print(Config config, int indent)` Recursively print configuration object tree to standard out.
`void`	`setAttribute(String name, String value)` Set configuration object attribute.
`void`	`setProperties(Properties properties)` Set this configuration object properties.
`void`	`setProperty(String name, Object value)` Set configuration object property.
`void`	`setProperty(String name, String value)` Set configuration object string property.
`void`	`setValue(Object value)` Set this configuration object value.
`String`	`toString()`

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Field Detail
  - name
```
private final String name
```
    Configuration object name.
  - value
```
private String value
```
    Configuration object value.
  - parent
```
private Config parent
```
    Parent reference, null if configuration object is root.
  - children
```
private final List<Config> children
```
    Children list, possible empty. Children list is usually empty if value exists but is not mandatory.
  - attributes
```
private final Map<String,String> attributes
```
    Optional attributes list, possible empty. An attribute is a name/value string pair.
  - properties
```
private Properties properties
```
    Optional properties, possible empty. Properties are usually empty if value exists but is not mandatory.
  - usedProperties
```
private Set<String> usedProperties
```
    Keep track of used properties. This set is updated by getProperty(String) and tested by getUnusedProperties().
  - converter
```
private final Converter converter
```
    Converter for objects conversion to / from strings.
- Constructor Detail
  - Config
```
public Config(String name)
```
    Create configuration object with name.
    
    Parameters:
    
    name - configuration object name.
    
    Throws:
    
    IllegalArgumentException - if name argument is null or empty.
- Method Detail
  - addChild
```
public void addChild(Config child)
```
    Add child configuration object.
    
    Parameters:
    
    child - child configuration object.
    
    Throws:
    
    IllegalArgumentException - if child argument is null.
  - setAttribute
```
public void setAttribute(String name,
                         String value)
```
    Set configuration object attribute. If attribute already exists overwrite old value. Empty value is not accepted but null is considered indication to remove attribute. So that, an existing attribute cannot be either null or empty.
    
    Parameters:
    
    name - attribute name,
    
    value - attribute value, null ignored.
    
    Throws:
    
    IllegalArgumentException - if name argument is null or empty.
    
    IllegalArgumentException - if value argument is empty.
  - setProperties
```
public void setProperties(Properties properties)
```
    Set this configuration object properties. All individual properties set using setProperty(String, String) and setProperty(String, Object) are lost.
    
    Parameters:
    
    properties - properties.
  - setProperty
```
public void setProperty(String name,
                        String value)
```
    Set configuration object string property. If property already exists overwrite old value. If value argument is null this setter does nothing.
    
    Parameters:
    
    name - property name,
    
    value - property value, null ignored.
    
    Throws:
    
    IllegalArgumentException - if name argument is null or empty.
    
    IllegalArgumentException - if value argument is empty.
  - setProperty
```
public void setProperty(String name,
                        Object value)
```
    Set configuration object property. Convert value to string and set property. If property already exists overwrite old value. If value argument is null this setter does nothing.
    
    Parameters:
    
    name - property name,
    
    value - property value, null ignored.
    
    Throws:
    
    IllegalArgumentException - if name argument is null or empty.
    
    ConverterException - if there is no converter registered for value type.
  - setValue
```
public void setValue(Object value)
```
    Set this configuration object value. Value is converter to string before store it. If value argument is null this setter will reset this configuration object value.
    
    Parameters:
    
    value - value to set, null accepted.
    
    Throws:
    
    IllegalArgumentException - if value argument is an empty string.
    
    ConverterException - if there is no converter registered for value type.
  - getRoot
```
public Config getRoot()
```
    Get root of the tree this configuration object is part of.
    
    Returns:
    
    configuration object root.
  - getParent
```
public Config getParent()
```
    Get configuration object parent.
    
    Returns:
    
    configuration object parent.
  - getName
```
public String getName()
```
    Get configuration object name.
    
    Returns:
    
    configuration object name.
  - hasAttribute
```
public boolean hasAttribute(String name)
```
    Test if configuration object has an attribute with requested name.
    
    Parameters:
    
    name - attribute name to search for.
    
    Returns:
    
    true if configuration object has an attribute with requested name.
    
    Throws:
    
    IllegalArgumentException - if name argument is null or empty.
  - hasAttribute
```
public boolean hasAttribute(String name,
                            String value)
```
    Test if configuration object has an attribute with requested name and value.
    
    Parameters:
    
    name - name of the attribute to search for,
    
    value - attribute value.
    
    Returns:
    
    true if configuration object has an attribute with requested name and value.
    
    Throws:
    
    IllegalArgumentException - if name argument is null or empty.
    
    IllegalArgumentException - if value argument is null or empty.
  - getAttribute
```
public String getAttribute(String name)
```
    Get attribute value or null if there is no attribute with requested name. An existing attribute value cannot ever be empty or null so if this method returns null is for missing attribute.
    
    Parameters:
    
    name - attribute name.
    
    Returns:
    
    attribute value or null if named attribute not found.
    
    Throws:
    
    IllegalArgumentException - if name argument is null or empty.
  - getAttribute
```
public String getAttribute(String name,
                           String defaultValue)
```
    Get attribute value or given default value if there is no attribute with requested name. If given default value is null and attribute is not found this method still returns null, that is, requested default value.
    
    Parameters:
    
    name - attribute name.
    
    defaultValue - default value, null or empty accepted.
    
    Returns:
    
    attribute value or default value.
    
    Throws:
    
    IllegalArgumentException - if name argument is null or empty.
  - getAttribute
```
public <T> T getAttribute(String name,
                          Class<T> type)
```
    Get attribute value converted to requested type or null if there is no attribute with requested name.
    
    Type Parameters:
    
    T - type to convert attribute value.
    
    Parameters:
    
    name - attribute name,
    
    type - type to converter attribute value to.
    
    Returns:
    
    newly created value object or null if named attribute not found.
    
    Throws:
    
    IllegalArgumentException - if name argument is null or empty.
    
    IllegalArgumentException - if type argument is null.
    
    ConverterException - if there is no converter registered for value type or value parse fails.
  - getAttribute
```
public <T> T getAttribute(String name,
                          Class<T> type,
                          T defaultValue)
```
    Get attribute value converted to requested type or default value if there is no attribute with requested name. If given default value is null and attribute is not found this method still returns null, that is, the requested default value.
    
    Type Parameters:
    
    T - type to convert attribute value to.
    
    Parameters:
    
    name - attribute name,
    
    type - type to converter attribute value to,
    
    defaultValue - default value.
    
    Returns:
    
    newly created value object instance or default value.
    
    Throws:
    
    IllegalArgumentException - if name argument is null or empty.
    
    IllegalArgumentException - if type argument is null.
    
    ConverterException - if there is no converter registered for value type or value parse fails.
  - getProperties
```
public Properties getProperties()
```
    Get configuration object Java raw properties. This method returns reference to internal properties storage that can be manipulated directly. Changes on returned reference does affect configuration object internal properties.
    
    Returns:
    
    configuration object properties storage.
  - getUnusedProperties
```
public Properties getUnusedProperties()
```
    Get properties not yet used at the moment this method is executed. A method is considered used if is read at least once by getProperty(String) or related. This method returns a new properties instance. Changes on returned instance does not affect configuration object internal properties.
    
    Returns:
    
    yet unused properties.
  - hasProperty
```
public boolean hasProperty(String name)
```
    Test if configuration object has named property.
    
    Parameters:
    
    name - property name.
    
    Returns:
    
    true if configuration object has property.
    
    Throws:
    
    IllegalArgumentException - if name argument is null or empty.
  - getProperty
```
public String getProperty(String name)
```
    Get configuration object property value or null if there is no property with requested name.
    
    Parameters:
    
    name - property name.
    
    Returns:
    
    configuration object property value or null.
    
    Throws:
    
    IllegalArgumentException - if name argument is null or empty.
  - getProperty
```
public String getProperty(String name,
                          String defaultValue)
```
    Get configuration object property value or default value if there is no property with requested name.
    
    Parameters:
    
    name - property name,
    
    defaultValue - default value.
    
    Returns:
    
    configuration object property value or given default value.
    
    Throws:
    
    IllegalArgumentException - if name argument is null or empty.
  - getProperty
```
public <T> T getProperty(String name,
                         Class<T> type)
```
    Get configuration object property converter to requested type or null if there is no property with given name.
    
    Type Parameters:
    
    T - value type.
    
    Parameters:
    
    name - property name.
    
    type - type to convert property value to.
    
    Returns:
    
    newly created value object or null.
    
    Throws:
    
    IllegalArgumentException - if name argument is null or empty.
    
    IllegalArgumentException - if type argument is null.
    
    ConverterException - if there is no converter registered for value type or value parse fails.
  - getProperty
```
public <T> T getProperty(String name,
                         Class<T> type,
                         T defaultValue)
```
    Get configuration object property converter to requested type or default value if there is no property with given name.
    
    Type Parameters:
    
    T - value type.
    
    Parameters:
    
    name - property name.
    
    type - type to convert property value to,
    
    defaultValue - default value, possible null or empty.
    
    Returns:
    
    newly created value object or default value.
    
    Throws:
    
    IllegalArgumentException - if name argument is null or empty.
    
    IllegalArgumentException - if type argument is null.
    
    ConverterException - if there is no converter registered for value type or value parse fails.
  - hasChildren
```
public boolean hasChildren()
```
    Test if configuration object has children.
    
    Returns:
    
    true if configuration object has children.
  - getChildrenCount
```
public int getChildrenCount()
```
    Get configuration object children count.
    
    Returns:
    
    configuration object children count.
  - getChildren
```
public List<Config> getChildren()
```
    Get configuration object children list.
    
    Returns:
    
    configuration object children list.
  - hasChild
```
public boolean hasChild(String name)
```
    Test if configuration object has at least a child with requested name.
    
    Parameters:
    
    name - child name.
    
    Returns:
    
    true if configuration object has at least one child with requested name.
    
    Throws:
    
    IllegalArgumentException - if name argument is null or empty.
  - getChild
```
public Config getChild(String name)
```
    Get configuration object first child with requested name or null if there is no child with given name.
    
    Parameters:
    
    name - child name.
    
    Returns:
    
    configuration object child or null.
    
    Throws:
    
    IllegalArgumentException - if name argument is null or empty.
  - getChild
```
public Config getChild(int index)
```
    Get configuration object child by index. Given index should be in range so that invoking this method on empty children list will throw exception.
    
    Parameters:
    
    index - child index.
    
    Returns:
    
    configuration object child at requested index.
    
    Throws:
    
    IllegalArgumentException - if index argument is not in range.
  - findChildren
```
public List<Config> findChildren(String... name)
```
    Find configuration object children with requested names.
    
    Parameters:
    
    name - one or more child names.
    
    Returns:
    
    configuration object children with requested names, possible empty.
    
    Throws:
    
    IllegalArgumentException - if name list does not contains at least one item.
  - getValue
```
public String getValue()
```
    Get this configuration object string value, possible null.
    
    Returns:
    
    configuration object string value, possible null.
    
    See Also:
    
    value
  - getValue
```
public <T> T getValue(Class<T> type)
```
    Get this configuration object value converted to requested type. Returns null if this configuration object has no value.
    
    Type Parameters:
    
    T - value type.
    
    Parameters:
    
    type - desired value object type.
    
    Returns:
    
    newly created value object or null.
    
    Throws:
    
    IllegalArgumentException - if type argument is null.
    
    ConverterException - if there is no converter registered for value type or value parse fails.
  - getChildValue
```
public String getChildValue(String name)
```
    Get named child string value or null if child not found or it has no value.
    
    Parameters:
    
    name - name of the child to retrieve value from.
    
    Returns:
    
    named child string value, possible null.
  - dump
```
public void dump()
```
    Dump configuration object tree to standard out, for debugging purposes.
  - print
```
private void print(Config config,
                   int indent)
```
    Recursively print configuration object tree to standard out.
    
    Parameters:
    
    config - configuration object,
    
    indent - indentation index.
  - toString
```
public String toString()
```
    Overrides:
    
    toString in class Object

Class Config

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

name

value

parent

children

attributes

properties

usedProperties

converter

Constructor Detail

Config

Method Detail

addChild

setAttribute

setProperties

setProperty

setProperty

setValue

getRoot

getParent

getName

hasAttribute

hasAttribute

getAttribute

getAttribute

getAttribute

getAttribute

getProperties

getUnusedProperties

hasProperty

getProperty

getProperty

getProperty

getProperty

hasChildren

getChildrenCount

getChildren

hasChild

getChild

getChild

findChildren

getValue

getValue

getChildValue

dump

print

toString