Package rife.config

Class Config

java.lang.Object
rife.config.Config
All Implemented Interfaces:
Cloneable
public class Config extends Object implements Cloneable
The Config class manages the configuration of parameters and lists.

It is capable of being loaded from and stored into XML files or the JDK Preferences mechanism.

The XML schema includes additional tags that can be used when manually writing config XML files. These are all the supported XML tags:

  • <param name="param.name">value</param>
    sets a parameter to the provided value, optionally takes a final attribute
  • <list name="list.name"></list>
    creates a named list with item tags, optionally takes a final attribute
  • <item>value</item>
    adds an item to the list it's declared in
  • <property name="prop.name"/>
    will be replaced with the property value from the hierarchical properties
  • <value name="param.name"/>
    will be replaced with the previously declared parameter value of that name
  • <selector class="package.name"/>
    will be replaced with result of the provided NameSelector class
  • <include>config/name.xml</include>
    includes another configuration that's looked up through the same resource finder

Here's an example of a complete config XML file: 

 <?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE config SYSTEM "/dtd/config.dtd">
 <config>
     <list name="list1">
         <item>item1</item>
         <item>item2:<property name="prop.name"/></item>
     </list>
     <list name="list2" final="true">
         <item>item3</item>
         <item>item4</item>
     </list>
     <param name="param1">5133</param>
     <param name="param2">astring<value name="param1"/></param>
     <param name="param3" final="true">value</param>
     <include>xml/config-<selector class="NameSelectorHostname"/>.xml</include>
 </config>

Two special configuration parameters can be used in the XML to indicate where config should be stored to Preferences.

If both of these are specified, then the user one will take precedence:

  • config.preferences.user
  • config.preferences.system

For example: 

 <config>
   <param name="config.preferences.user">/myapplication</param>
   <param name="default.language">en</param>
 </config>

When loading this config file from a resource that's not writable, changes can then still be saved and stored in Preferences using the storeToPreferences() method.

As long as the special preferences parameter is part of the configuration, parameters and lists will be retrieved from the preferences node instead of from the static configuration file. If the preferences node doesn't exist or the parameter or list doesn't exist in the preferences node, then the static config value will be returned instead.

Since:
1.6.0

  • Field Details

  • Constructor Details

    • Config

      public Config()
      Creates a new Config instance.
      Since:
      1.6.0

  • Method Details

    • fromXmlFile

      public static Config fromXmlFile(File file) throws ConfigErrorException
      Creates a new Config instance that is parsed from an XML file. it will be treated as such regardless.

      The system hierarchical properties will be used.

      Parameters:
      file - the XML file to parse
      Returns:
      the resulting config instance
      Throws:
      ConfigErrorException - when an error occurred during parsing the XML file
      Since:
      1.6.0

    • fromXmlFile

      public static Config fromXmlFile(File file, HierarchicalProperties properties) throws ConfigErrorException
      Creates a new Config instance that is parsed from an XML file.
      Parameters:
      file - the XML file to parse
      properties - the hierarchical properties to use
      Returns:
      the resulting config instance
      Throws:
      ConfigErrorException - when an error occurred during parsing the XML file
      Since:
      1.6.0

    • fromXmlResource

      public static Config fromXmlResource(String resourceName, HierarchicalProperties properties) throws ConfigErrorException
      Creates a new Config instance that is parsed from an XML resource.

      The class path resource finder will be used.

      Parameters:
      resourceName - the name of the resource to parse
      properties - the hierarchical properties to use
      Returns:
      the resulting config instance
      Throws:
      ConfigErrorException - when an error occurred during parsing the XML resource
      Since:
      1.6.0

    • fromXmlResource

      public static Config fromXmlResource(String resourceName, ResourceFinder resourceFinder) throws ConfigErrorException
      Creates a new Config instance that is parsed from an XML resource.

      The system hierarchical properties will be used.

      Parameters:
      resourceName - the name of the resource to parse
      resourceFinder - the resource finder to use
      Returns:
      the resulting config instance
      Throws:
      ConfigErrorException - when an error occurred during parsing the XML resource
      Since:
      1.6.0

    • fromXmlResource

      public static Config fromXmlResource(String resourceName, ResourceFinder resourceFinder, HierarchicalProperties properties) throws ConfigErrorException
      Creates a new Config instance that is parsed from an XML resource.
      Parameters:
      resourceName - the name of the resource to parse
      properties - the hierarchical properties to use
      resourceFinder - the resource finder to use
      Returns:
      the resulting config instance
      Throws:
      ConfigErrorException - when an error occurred during parsing the XML resource
      Since:
      1.6.0

    • getXmlFile

      public File getXmlFile()
      Retrieves the XML file that is used for this config instance.

      This can be null if the config instance wasn't parsed from an XML file and the file wasn't explicitly set.

      Returns:
      the XML file used for this config instance; or null if no XML file is used
      Since:
      1.6.0

    • xmlFile

      public Config xmlFile(File file)
      Set the XML file that should be used for this config instance.

      This method simply changes the XML file, it doesn't perform storage or any other file-related operations.

      Parameters:
      file - the XML file to use
      Returns:
      this config instance
      Since:
      1.6.0

    • preferencesNode

      public Config preferencesNode(Preferences node)
      Sets the Preferences node that should be used for storing this config data.
      Parameters:
      node - the preferences node to use
      Returns:
      this config instance
      Since:
      1.6.0

    • hasPreferencesNode

      public boolean hasPreferencesNode()
      Indicates whether this config instance is using a Preferences node.
      Returns:
      true if this config instance is using a preferences node; or false otherwise
      Since:
      1.6.0

    • getPreferencesNode

      public Preferences getPreferencesNode()
      Retrieves the Preferences node that is used by this config instance.
      Returns:
      the used preferences node; or null if no preferences node is used
      Since:
      1.6.0

    • hasParameter

      public boolean hasParameter(String parameter)
      Returns whether a parameter exists.
      Parameters:
      parameter - the name of the parameter
      Returns:
      true of the parameter exists; or false otherwise
      Since:
      1.6.0

    • isFinalParameter

      public boolean isFinalParameter(String parameter)
      Indicates whether a parameter is final.

      A final parameter can not be changed.

      Parameters:
      parameter - the name of the parameter
      Returns:
      true if the parameter is final; or false otherwise
      Since:
      1.6.0

    • countParameters

      public int countParameters()
      Returns the number of parameters that are present.
      Returns:
      the number of parameters
      Since:
      1.6.0

    • getString

      public String getString(String parameter)
      Retrieves the string value of a parameter.
      Parameters:
      parameter - the name of the parameter
      Returns:
      the string value; or null if the parameter doesn't exist
      Since:
      1.6.0

    • getString

      public String getString(String parameter, String defaultValue)
      Retrieves the string value of a parameter.
      Parameters:
      parameter - the name of the parameter
      defaultValue - the default value to use when the parameter doesn't exist
      Returns:
      the string value; or the provided default value if the parameter doesn't exist
      Since:
      1.6.0

    • getBool

      public boolean getBool(String parameter)
      Retrieves the boolean value of a parameter.
      Parameters:
      parameter - the name of the parameter
      Returns:
      the boolean value; or false if the parameter doesn't exist
      Since:
      1.6.0

    • getBool

      public boolean getBool(String parameter, boolean defaultValue)
      Retrieves the boolean value of a parameter.
      Parameters:
      parameter - the name of the parameter
      defaultValue - the default value to use when the parameter doesn't exist
      Returns:
      the boolean value; or the provided default value if the parameter doesn't exist
      Since:
      1.6.0

    • getChar

      public char getChar(String parameter)
      Retrieves the char value of a parameter.
      Parameters:
      parameter - the name of the parameter
      Returns:
      the char value; or '0' if the parameter doesn't exist
      Since:
      1.6.0

    • getChar

      public char getChar(String parameter, char defaultValue)
      Retrieves the char value of a parameter.
      Parameters:
      parameter - the name of the parameter
      defaultValue - the default value to use when the parameter doesn't exist
      Returns:
      the char value; or the provided default value if the parameter doesn't exist
      Since:
      1.6.0

    • getInt

      public int getInt(String parameter)
      Retrieves the int value of a parameter.
      Parameters:
      parameter - the name of the parameter
      Returns:
      the int value; or 0 if the parameter doesn't exist
      Since:
      1.6.0

    • getInt

      public int getInt(String parameter, int defaultValue)
      Retrieves the int value of a parameter.
      Parameters:
      parameter - the name of the parameter
      defaultValue - the default value to use when the parameter doesn't exist
      Returns:
      the int value; or the provided default value if the parameter doesn't exist
      Since:
      1.6.0

    • getLong

      public long getLong(String parameter)
      Retrieves the long value of a parameter.
      Parameters:
      parameter - the name of the parameter
      Returns:
      the long value; or 0L if the parameter doesn't exist
      Since:
      1.6.0

    • getLong

      public long getLong(String parameter, long defaultValue)
      Retrieves the long value of a parameter.
      Parameters:
      parameter - the name of the parameter
      defaultValue - the default value to use when the parameter doesn't exist
      Returns:
      the long value; or the provided default value if the parameter doesn't exist
      Since:
      1.6.0

    • getFloat

      public float getFloat(String parameter)
      Retrieves the float value of a parameter.
      Parameters:
      parameter - the name of the parameter
      Returns:
      the float value; or 0F if the parameter doesn't exist
      Since:
      1.6.0

    • getFloat

      public float getFloat(String parameter, float defaultValue)
      Retrieves the float value of a parameter.
      Parameters:
      parameter - the name of the parameter
      defaultValue - the default value to use when the parameter doesn't exist
      Returns:
      the float value; or the provided default value if the parameter doesn't exist
      Since:
      1.6.0

    • getDouble

      public double getDouble(String parameter)
      Retrieves the double value of a parameter.
      Parameters:
      parameter - the name of the parameter
      Returns:
      the double value; or 0D if the parameter doesn't exist
      Since:
      1.6.0

    • getDouble

      public double getDouble(String parameter, double defaultValue)
      Retrieves the double value of a parameter.
      Parameters:
      parameter - the name of the parameter
      defaultValue - the default value to use when the parameter doesn't exist
      Returns:
      the double value; or the provided default value if the parameter doesn't exist
      Since:
      1.6.0

    • getSerializable

      public <TargetType extends Serializable> TargetType getSerializable(String parameter)
      Retrieves a serialized instance of a parameter.
      Parameters:
      parameter - the name of the parameter
      Returns:
      the instance of the serialized value; or null if the parameter doesn't exist or can't be deserialized
      Since:
      1.6.0

    • getSerializable

      public <TargetType extends Serializable> TargetType getSerializable(String parameter, TargetType defaultValue)
      Retrieves a serialized instance of a parameter.
      Parameters:
      parameter - the name of the parameter
      defaultValue - the default value to use when the parameter doesn't exist
      Returns:
      the double value; or the provided default value if the parameter doesn't exist
      Since:
      1.6.0

    • finalParameter

      public Config finalParameter(String parameter, boolean isFinal)
      Sets whether a parameter is final or not.
      Parameters:
      parameter - the name of the parameter
      isFinal - true to make the parameter final; or false otherwise
      Returns:
      this config instance
      Since:
      1.6.0

    • put

      public Config put(String parameter, String value)
      Sets the string value of a parameter.
      Parameters:
      parameter - the name of the parameter
      value - the value of the parameter
      Returns:
      this config instance
      Since:
      1.6.0

    • put

      public Config put(String parameter, boolean value)
      Sets the boolean value of a parameter.
      Parameters:
      parameter - the name of the parameter
      value - the value of the parameter
      Returns:
      this config instance
      Since:
      1.6.0

    • put

      public Config put(String parameter, char value)
      Sets the char value of a parameter.
      Parameters:
      parameter - the name of the parameter
      value - the value of the parameter
      Returns:
      this config instance
      Since:
      1.6.0

    • put

      public Config put(String parameter, int value)
      Sets the int value of a parameter.
      Parameters:
      parameter - the name of the parameter
      value - the value of the parameter
      Returns:
      this config instance
      Since:
      1.6.0

    • put

      public Config put(String parameter, long value)
      Sets the long value of a parameter.
      Parameters:
      parameter - the name of the parameter
      value - the value of the parameter
      Returns:
      this config instance
      Since:
      1.6.0

    • put

      public Config put(String parameter, float value)
      Sets the float value of a parameter.
      Parameters:
      parameter - the name of the parameter
      value - the value of the parameter
      Returns:
      this config instance
      Since:
      1.6.0

    • put

      public Config put(String parameter, double value)
      Sets the double value of a parameter.
      Parameters:
      parameter - the name of the parameter
      value - the value of the parameter
      Returns:
      this config instance
      Since:
      1.6.0

    • put

      public Config put(String parameter, Serializable value) throws ConfigErrorException
      Sets the serializable value of a parameter.
      Parameters:
      parameter - the name of the parameter
      value - the value of the parameter
      Returns:
      this config instance
      Throws:
      ConfigErrorException
      Since:
      1.6.0

    • remove

      public void remove(String parameter)
      Removes a parameter.
      Parameters:
      parameter - the parameter name
      Since:
      1.6.0

    • isFinalList

      public boolean isFinalList(String list)
      Indicates whether a list is final.

      A final list can not be changed.

      Parameters:
      list - the name of the list
      Returns:
      true if the list is final; or false otherwise
      Since:
      1.6.0

    • getStringItems

      public List<String> getStringItems(String list)
      Retrieves a list as string items.
      Parameters:
      list - the name of the list
      Returns:
      the requested list; or null of the list couldn't be found
      Since:
      1.6.0

    • getBoolItems

      public List<Boolean> getBoolItems(String list)
      Retrieves a list as boolean items.
      Parameters:
      list - the name of the list
      Returns:
      the requested list; or null of the list couldn't be found
      Since:
      1.6.0

    • getCharItems

      public List<Character> getCharItems(String list)
      Retrieves a list as char items.

      Any item that couldn't be converted to a char will be excluded.

      Parameters:
      list - the name of the list
      Returns:
      the requested list; or null of the list couldn't be found
      Since:
      1.6.0

    • getIntItems

      public List<Integer> getIntItems(String list)
      Retrieves a list as int items.

      Any item that couldn't be converted to an int will be excluded.

      Parameters:
      list - the name of the list
      Returns:
      the requested list; or null of the list couldn't be found
      Since:
      1.6.0

    • getLongItems

      public List<Long> getLongItems(String list)
      Retrieves a list as long items.

      Any item that couldn't be converted to a long will be excluded.

      Parameters:
      list - the name of the list
      Returns:
      the requested list; or null of the list couldn't be found
      Since:
      1.6.0

    • getFloatItems

      public List<Float> getFloatItems(String list)
      Retrieves a list as float items.

      Any item that couldn't be converted to a float will be excluded.

      Parameters:
      list - the name of the list
      Returns:
      the requested list; or null of the list couldn't be found
      Since:
      1.6.0

    • getDoubleItems

      public List<Double> getDoubleItems(String list)
      Retrieves a list as double items.

      Any item that couldn't be converted to a double will be excluded.

      Parameters:
      list - the name of the list
      Returns:
      the requested list; or null of the list couldn't be found
      Since:
      1.6.0

    • getSerializableItems

      public <TargetType extends Serializable> List<TargetType> getSerializableItems(String list)
      Retrieves a list as serializable items.

      Any item that couldn't be deserialized will be excluded.

      Parameters:
      list - the name of the list
      Returns:
      the requested list; or null of the list couldn't be found
      Since:
      1.6.0

    • hasList

      public boolean hasList(String list)
      Returns whether a list exists.
      Parameters:
      list - the name of the list
      Returns:
      true if the list exists; or false otherwise
      Since:
      1.6.0

    • countLists

      public int countLists()
      Returns the number of lists that are present.
      Returns:
      the number of lists
      Since:
      1.6.0

    • putItem

      public Config putItem(String list, String item)
      Adds a new string item to a list.
      Parameters:
      list - the name of the list
      item - the value of the item
      Returns:
      this config instance
      Since:
      1.6.0

    • putItem

      public Config putItem(String list, boolean item)
      Adds a new boolean item to a list.
      Parameters:
      list - the name of the list
      item - the value of the item
      Returns:
      this config instance
      Since:
      1.6.0

    • putItem

      public Config putItem(String list, char item)
      Adds a new char item to a list.
      Parameters:
      list - the name of the list
      item - the value of the item
      Returns:
      this config instance
      Since:
      1.6.0

    • putItem

      public Config putItem(String list, int item)
      Adds a new int item to a list.
      Parameters:
      list - the name of the list
      item - the value of the item
      Returns:
      this config instance
      Since:
      1.6.0

    • putItem

      public Config putItem(String list, long item)
      Adds a new long item to a list.
      Parameters:
      list - the name of the list
      item - the value of the item
      Returns:
      this config instance
      Since:
      1.6.0

    • putItem

      public Config putItem(String list, float item)
      Adds a new float item to a list.
      Parameters:
      list - the name of the list
      item - the value of the item
      Returns:
      this config instance
      Since:
      1.6.0

    • putItem

      public Config putItem(String list, double item)
      Adds a new double item to a list.
      Parameters:
      list - the name of the list
      item - the value of the item
      Returns:
      this config instance
      Since:
      1.6.0

    • putItem

      public Config putItem(String list, Serializable item) throws ConfigErrorException
      Adds a new serializable item to a list.
      Parameters:
      list - the name of the list
      item - the value of the item
      Returns:
      this config instance
      Throws:
      ConfigErrorException
      Since:
      1.6.0

    • clearList

      public void clearList(String list)
      Clears all the items from a list.

      If the list doesn't exist, nothing will happen.

      Parameters:
      list - the name of the list
      Since:
      1.6.0

    • removeList

      public void removeList(String list)
      Removes a list.

      If the list doesn't exist, nothing will happen.

      Parameters:
      list - the name of the list
      Since:
      1.6.0

    • finalList

      public Config finalList(String list, boolean isFinal)
      Sets whether a list is final or not.
      Parameters:
      list - the name of the parameter
      isFinal - true to make the list final; or false otherwise
      Returns:
      this config instance
      Since:
      1.6.0

    • toXml

      public String toXml()
      Generates an XML presentation of the current state of this config instance.
      Returns:
      the generates XML
      Since:
      1.6.0

    • storeToXml

      public void storeToXml() throws ConfigErrorException
      Store this config instance to its XML file.
      Throws:
      ConfigErrorException - when an error occurred during the storage of the XML file or when no XML file was set
      Since:
      1.6.0
      See Also:

    • storeToXml

      public void storeToXml(File destination) throws ConfigErrorException
      Store this config instance to a specific XML file.
      Parameters:
      destination - the file to store this config instance to
      Throws:
      ConfigErrorException - when an error occurred during the storage of the XML file
      Since:
      1.6.0

    • storeToPreferences

      public void storeToPreferences() throws ConfigErrorException
      Store this config instance to its assigned Preferences node.
      Throws:
      ConfigErrorException - when an error occurred during the storage or when no preferences node was assigned
      Since:
      1.6.0

    • storeToPreferences

      public void storeToPreferences(Preferences preferences) throws ConfigErrorException
      Store this config instance to a specific Preferences node.
      Throws:
      ConfigErrorException - when an error occurred during the storage
      Since:
      1.6.0

    • clone

      public Config clone()
      Overrides:
      clone in class Object