Package org.spiderwiz.zutils

Class ZConfig

java.lang.Object
org.spiderwiz.zutils.ZConfig
public class ZConfig
extends Object
A class that manages application configuration files.

An application configuration file is a text file that contains mapping of property names (the keys) to property values. Each line in the file has the format:

[property name]property value

This class has methods for reading configuration files into a map object, retrieving and interpreting configuration properties, modifying properties, updating configuration files and some other tools.

Note that a configuration map allows only one value per property. If the configuration file contains multiple definitions of the same property, then when loading the file into a configuration map the latter in the file will step over the earlier. Also lines that do not have the structure of a configuration property will be ignored.

  • Constructor Details

    • ZConfig

      public ZConfig()
      Class constructor.

  • Method Details

    • init

      public boolean init​(String pathname)
      Initializes the object with a file pathname and the default character set (UTF-8).

      The method opens the specified file that is supposed to contain UTF-8 text, reads its content, parses the configuration properties into the map managed by this object, then closes the file.

      Parameters:
      pathname - the system-dependent file pathname.
      Returns:
      true if the file exists and the object has been initialized successfully, false otherwise.
      See Also:
      init(pathname, charset), getPropertySheet()

    • init

      public boolean init​(String pathname, String charset)
      Initializes the object with a file pathname and the specified character set.

      The method opens the specified file that is supposed to contain text in the specified character set, reads its content, parses the configuration properties into the map managed by this object, then closes the file.

      Parameters:
      pathname - the system-dependent file pathname.
      charset - the character set used for the text in the file.
      Returns:
      true if the file exists and the object has been initialized successfully, false otherwise.
      See Also:
      init(pathname)

    • reload

      public boolean reload()
      Reloads the properties from the file used to initialize the object.

      Call this method if the configuration file was modified externally and you want to reload it into the map managed by this object.

      Returns:
      true if the file used for initializing the object exists and its content has been reloaded successfully, false otherwise.
      See Also:
      init(pathname), init(pathname, charset)

    • getProperty

      public final String getProperty​(String prop)
      Returns the value to which the specified property is mapped.

      Returns the value to which the specified property is mapped, or null if the configuration contains no mapping for the property.

      Parameters:
      prop - the property whose associated value is to be returned.
      Returns:
      the value to which the specified property is mapped, or null if the configuration contains no mapping for the property.
      See Also:
      getIntProperty()

    • getIntProperty

      public int getIntProperty​(String prop)
      Returns the value to which the specified property is mapped converted to an integer.

      Returns the value to which the specified property is mapped converted to an integer, or zero if the property is not an integer number or the configuration contains no mapping for the property.

      Parameters:
      prop - the property whose associated value is to be returned.
      Returns:
      the value to which the specified property is mapped converted to an integer, or zero if the property is not an integer number or the configuration contains no mapping for the property.
      See Also:
      getProperty()

    • isPropertySet

      public final boolean isPropertySet​(String... props)
      Returns true if at least one property from a given list is set on.

      A property is considered to be set on if it exists in the configuration map and its value is neither an empty string nor does it start with the letters "no", case insensitive. This method accepts as parameters a list of property names and returns true if and only if at least one of the properties is set on.

      Parameters:
      props - zero or more property names.
      Returns:
      true if and only if at least one of the specified properties is set on.

    • setProperty

      public final void setProperty​(String prop, String value)
      Sets a property value or remove it.

      If value is not null the method updates the value of the property if it exists and will add it if it does not. If value is null the property is deleted if it exists.

      Parameters:
      prop - the property to be set.
      value - the value to set. If null then the property is removed if it exists.
      See Also:
      setProperties()

    • setProperties

      public final void setProperties​(String assignments)
      Sets values in a list of properties.

      The assignments parameter is a list assignments property=value concatenated by a semicolon, i.e.:

      property1=value1;property2=value2;...

      The method sets each of the properties in the list to the specified value.

      Parameters:
      assignments - a list of properties in the format property1=value1;property2=value2;...
      See Also:
      setProperty()

    • saveConfiguration

      public final void saveConfiguration()
      Saves the loaded configuration map in the configuration file.

      Saves the current configuration map image in the file provided in the call to init(). The order of the properties in the saved file is not guaranteed, and if the original file contains multiple definitions of the same property, only the last one is stored in the newly written file. Lines that do not have the configuration structure are written to the new file.

    • getPropertySheet

      public ZConfig.PropertySheet getPropertySheet() throws IOException
      Returns a list that contains the content of the configuration file.

      This method loads the configuration file into a PropertySheet object that lists all the properties contained in the configuration file, in the order they appear in the file. If there are multiple definitions of the same property, they are copied to the returned object as they appear in the file.

      You can use this method in conjunction with savePropertySheet() in order to edit the file without shuffling its content.

      Returns:
      a list that contains the content of the configuration file.
      Throws:
      IOException
      See Also:
      savePropertySheet()

    • savePropertySheet

      public void savePropertySheet​(ZConfig.PropertySheet properties) throws FileNotFoundException, UnsupportedEncodingException
      Uses a list of properties to rewrite the configuration file and reloads the running application configuration.

      This method gets a PropertySheet object that contains a list of properties and saves them in the configuration file, in the order they appear in the list, rewriting over the file's previous content. If the list contains multiple definitions of the same property, they are all written to the file as they appear in the list.

      Besides writing to the file, the method reloads the property map of the running application with the values contained in the list. If the list contains multiple definitions of the same property, the value of the latter steps over the earlier.

      You can use this method in conjunction with getPropertySheet() in order to edit the file without shuffling its content.

      Parameters:
      properties - a list of properties to store in the file.
      Throws:
      FileNotFoundException
      UnsupportedEncodingException
      See Also:
      getPropertySheet()

    • processAllProperties

      public void processAllProperties()
      Performs custom processing for each property included in the configuration map.

      This method activates processProperty() for each property included in the configuration map. You can override that method in order to perform custom processing for each property.

      See Also:
      processProperty()

    • processProperty

      protected void processProperty​(String prop, String value)
      Processes the given property.

      This method is activated from processAllProperties(). Override it to perform custom processing on the given property.

      Parameters:
      prop - name of the property to be processed.
      value - value of the property to be processed.
      See Also:
      processAllProperties()