HiRISE

HiRISE.HiPlan.Utilities
Class Configuration_Helper

java.lang.Object
  extended by HiRISE.HiPlan.Utilities.Configuration_Helper

public class Configuration_Helper
extends Object

A helper utility for handling PVL configuration files and easily accessing their parameter values.

An object of this class is constructed with a set of named parameter groups akin to search paths. The set is defined by a preferred group and a set of secondary groups. If the preferred group is null, the first of the secondary groups is the de facto preferred group. If no secondary groups are provided, the HiPlan-centric default groups are used.

A configuration helper object features a number of accessor methods that search its parameter groups for a parameter of a given name. If found, and if the parameter value can be parsed as the appropriate type, that parsed value is returned. If not, an indicated default value is returned instead. For example, the boolean getValue(String,boolean) method searches for a named parameter, name. If not found, or if the parameter has no value, defaultValue is returned instead. And if the parameter is found and has a value, but the value cannot reasonably be interpreted as true or false, the defaultValue is returned.

The class features a handful of static methods similar to the aforementioned non-static methods. These methods search an indicated configuration for a particular named parameter amongst a list of named groups. These methods return string objects or lists of string objects, and they have no default value; if the named parameter is not found, they return null. These methods do have a default set of groups to search, however: the HiPlan-centric default groups.

Additional static class methods provide for easily loading a configuration file from a named source or falling back to a set of known configuration filenames if no source is provided; methods for accessing common parameters (SERVER and CATALOG); a method for masking passwords in a configuration for display; and other common configuration functions.

Example

A detailed example of the use of the configuration helper follows. First, assume a configuration has the following parameters:

        Read_Only = false
        Group = HiPlan
                Unbinned_Line_Increment = 100
                Binned_Line_Increment = foo
                Shadow_Tip_Difference_Max = 2.5
        End_Group
        Group = HiSEAS
                Shadow_Tip_Difference_Max = 1.5
        End_Group

Consider the following code snippet:

        Configuration config = Configuration_Helper.getConfiguration(null, null);
        Configuration_Helper helper = new Configuration_Helper(
                config, "HiSEAS"
        );
        System.out.println(helper.getGroups());
        System.out.println(helper.getValue("Unbinned_Line_Increment", 1500));
        System.out.println(helper.getValue("Binned_Line_Increment", 3500));
        System.out.println(helper.getValue("Shadow_Tip_Difference_Max", 3.0));

It produces the following output:

        [/HiSEAS/, /HiPlan/, /HOGG/, /, ]
        100
        3500
        1.5

The first value, 100, was identified as an integer value in the HiPlan group for the Unbinned_Line_Increment parameter.

The second value, 3500, is the default value supplied for the search for a parameter named Binned_Line_Increment. Although such a parameter exists, its value, foo, is not an integer, so the default value was used.

The final value, 1.5, was identified as a double precision value in the HiSEAS group, which was the preferred search group at construction. (Had it not been in the HiSEAS group, the value in the HiPlan group would have been found next.)

Version:
1.21
Author:
Christian Schaller - UA/PIRL

Field Summary
static String ID
          Class identification name with source code version and date.
static String PASSWORD_IDENTIFIER
          The text sequence identifying a password configuration parameter.
static String PASSWORD_MASK
          The text sequence used to mask a password.
static String PORT
          The identifier for an optional host port value.
 
Constructor Summary
Configuration_Helper(Configuration configuration, String preferredGroup, String... secondaryGroups)
          Constructs a new configuration helper from the indicated configuration and the indicated parameter search groups.
 
Method Summary
static String getCatalog(Configuration configuration, String... catalogGroups)
          Gets the value of the catalog parameter from the input configuration.
 Configuration getConfiguration()
          Gets the configuration used in the creation of this helper.
static Configuration getConfiguration(String source, String propertyName, String... defaultFilenames)
          Gets a configuration from a named source, a system property, or a set of default filenames.
static String getConfigurationValue(String name, Configuration configuration)
          Gets a string value from a named parameter in the indicated configuration.
static String getConfigurationValue(String name, Configuration configuration, List<String> groups)
          Gets a string value from a named parameter in the indicated configuration.
static List<String> getConfigurationValueList(String name, Configuration configuration)
          Gets a list of strings from a named parameter in the indicated configuration.
static List<String> getConfigurationValueList(String name, Configuration configuration, List<String> groups)
          Gets a list of strings from a named parameter in the indicated configuration.
static String getConnectionInfo(Configuration configuration, String... catalogGroups)
          Gets a simple text summary of the database connection information from a configuration.
static File getDefaultConfigurationFile(String... defaultFilenames)
          Gets a file from a set of filenames.
 List<String> getGroups()
          Gets the list of groups to search for parameters.
 String getPreferredGroup()
          Gets the preferred group to search for parameters.
 String[] getSecondaryGroups()
          Gets the secondary groups to search for parameters.
static String getServer(Configuration configuration)
          Gets the value of the server parameter from the input configuration.
 boolean getValue(String name, boolean defaultValue)
          Gets a boolean value from a named parameter in this helper's configuration.
 boolean[] getValue(String name, boolean[] defaultArray)
          Gets an array of boolean primitives from a named parameter in this helper's configuration.
 Color getValue(String name, Color defaultValue)
          Gets a color from a named parameter in this helper's configuration.
 double getValue(String name, double defaultValue)
          Gets a double-precision value from a named parameter in this helper's configuration.
 double[] getValue(String name, double[] defaultArray)
          Gets an array of double primitives from a named parameter in this helper's configuration.
<E extends Enum<E>>
E
getValue(String name, E defaultValue)
          Gets an enum from a named parameter in this helper's configuration.
<E extends Enum<E>>
List<E>
getValue(String name, E[] defaultArray)
          Gets a list of enums from a named parameter in this helper's configuration.
 int getValue(String name, int defaultValue)
          Gets an integer value from a named parameter in this helper's configuration.
 int[] getValue(String name, int[] defaultArray)
          Gets an array of integer primitives from a named parameter in this helper's configuration.
 String getValue(String name, String defaultValue)
          Gets a text value from a named parameter in this helper's configuration.
 List<String> getValue(String name, String[] defaultArray)
          Gets a list of strings from a named parameter in this helper's configuration.
static List<String> makeGroups(String preferredGroup, String... groupAdditions)
          Creates a list of strings from the input strings, using default values as appropriate.
static Configuration maskPasswords(Configuration configuration)
          Sanitizes the input configuration by masking the value of each password parameter.
static void patchConfiguration(Configuration configuration, boolean override, String... catalogGroups)
          Patches the server group of the indicated input configuration.
static void patchConfiguration(Configuration configuration, String... catalogGroups)
          Patches the server group of the indicated input configuration.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

ID

public static final String ID
Class identification name with source code version and date.

See Also:
Constant Field Values

PASSWORD_IDENTIFIER

public static final String PASSWORD_IDENTIFIER
The text sequence identifying a password configuration parameter. If a parameter name ends with this sequence ("PASSWORD") (case-insensitive), it is presumed to be a password parameter whose value should be masked in the maskPasswords(Configuration) method.

See Also:
Constant Field Values

PASSWORD_MASK

public static final String PASSWORD_MASK
The text sequence used to mask a password. It is a set of eight asterisks: ********.

See Also:
maskPasswords(Configuration), PASSWORD_IDENTIFIER, Constant Field Values

PORT

public static final String PORT
The identifier for an optional host port value.

See Also:
MySQL_Data_Port.PORT, Constant Field Values
Constructor Detail

Configuration_Helper

public Configuration_Helper(Configuration configuration,
                            String preferredGroup,
                            String... secondaryGroups)
Constructs a new configuration helper from the indicated configuration and the indicated parameter search groups. This helper object's methods operate on the configuration using these groups to search for parameter values.

This new object's parameter search groups list is generated from the input preferredGroup and secondaryGroups. If the preferred group is null, the first item of the secondary group is the de facto preferred group. If the secondaryGroups array has a zero length, the HiPlan-centric Constants.BASE_CONFIGURATION_GROUPS is used. Note that an accurate list of the search groups is thus obtained from the getGroups() method; the getPreferredGroup() and getSecondaryGroups() methods reflect the construction arguments.

Parameters:
configuration - the configuration for this helper; may not be null
preferredGroup - the first group searched for a given parameter; may be null.
secondaryGroups - additional groups searched for a given parameter.
Throws:
NullPointerException - if the configuration is null.
Method Detail

getConfiguration

public Configuration getConfiguration()
Gets the configuration used in the creation of this helper.

Returns:
this helper's configuration.

getPreferredGroup

public String getPreferredGroup()
Gets the preferred group to search for parameters. This value may be null, depending on how the helper object was constucted. Use getGroups() for a complete and accurate list of the groups to be searched.

Returns:
the preferred group at construction; may be null.

getSecondaryGroups

public String[] getSecondaryGroups()
Gets the secondary groups to search for parameters. This value may have a length of 0, depending on how the helper object was constructed. Use getGroups() for a complete and accurate list of the groups to be searched.

Returns:
the array of secondary groups used at construction; may have a length of zero.

getGroups

public List<String> getGroups()
Gets the list of groups to search for parameters. This list may or may not reflect the values used at construction of this helper, depending on those values.

Returns:
the list of groups to search.
See Also:
Configuration_Helper(Configuration,String,String...)

getValue

public boolean getValue(String name,
                        boolean defaultValue)
Gets a boolean value from a named parameter in this helper's configuration. If the parameter is not found, or if it is found but cannot be parsed as a boolean, the indicated default value is returned. If the parameter is found, and its value is TRUE or YES (case-insensitive), this method returns true; if it is found and its value is FALSE or NO (case-insensitive) this method returns false.

This method searches for the named parameter in the list of named groups generated at construction time.

Parameters:
name - the configuration parameter name.
defaultValue - the default value when the parameter is not present.
Returns:
true, false, or the default value.

getValue

public boolean[] getValue(String name,
                          boolean[] defaultArray)
Gets an array of boolean primitives from a named parameter in this helper's configuration. If the parameter is not found, or if it is found but the value is null, or if it is not a sequence or a series, or if is empty, or if any of its elements cannot be parsed as a boolean (TRUE/YES or FALSE/NO, case-insensitive), the indicated default array is returned.

This method searches for the named parameter in the list of named groups generated at construction time.

Parameters:
name - the configuration parameter name.
defaultArray - the default array to return when the parameter is not present, etc.
Returns:
the array or the default array.

getValue

public int getValue(String name,
                    int defaultValue)
Gets an integer value from a named parameter in this helper's configuration. If the parameter is not found, or if it is found but cannot be parsed as an integer, the indicated default value is returned.

This method searches for the named parameter in the list of named groups generated at construction time.

Parameters:
name - the configuration parameter name.
defaultValue - the default value when the parameter is not present.
Returns:
the integer value of the parameter or the default value.

getValue

public int[] getValue(String name,
                      int[] defaultArray)
Gets an array of integer primitives from a named parameter in this helper's configuration. If the parameter is not found, or if it is found but the value is null, or if it is not a sequence or a series, or if is empty, or if any of its elements cannot be parsed as an integer, the indicated default array is returned.

This method searches for the named parameter in the list of named groups generated at construction time.

Parameters:
name - the configuration parameter name.
defaultArray - the default array to return when the parameter is not present, etc.
Returns:
the array or the default array.

getValue

public double getValue(String name,
                       double defaultValue)
Gets a double-precision value from a named parameter in this helper's configuration. If the parameter is not found, or if it is found but cannot be parsed as a double, the indicated default value is returned.

This method searches for the named parameter in the list of named groups generated at construction time.

Parameters:
name - the configuration parameter name.
defaultValue - the default value when the parameter is not present.
Returns:
the double-precision value of the parameter or the default value.

getValue

public double[] getValue(String name,
                         double[] defaultArray)
Gets an array of double primitives from a named parameter in this helper's configuration. If the parameter is not found, or if it is found but the value is null, or if it is not a sequence or a series, or if is empty, or if any of its elements cannot be parsed as a double, the indicated default array is returned.

This method searches for the named parameter in the list of named groups generated at construction time.

Parameters:
name - the configuration parameter name.
defaultArray - the default array to return when the parameter is not present, etc.
Returns:
the array or the default array.

getValue

public String getValue(String name,
                       String defaultValue)
Gets a text value from a named parameter in this helper's configuration. If the parameter is not found, or if it is found but the value is null, the indicated default value is returned.

This method searches for the named parameter in the list of named groups generated at construction time.

Parameters:
name - the configuration parameter name.
defaultValue - the default value when the parameter is not present.
Returns:
the text value of the parameter or the default value.

getValue

public List<String> getValue(String name,
                             String[] defaultArray)
Gets a list of strings from a named parameter in this helper's configuration. If the parameter is not found, or if it is found but the value is null, the indicated default array is returned (as a list).

This method searches for the named parameter in the list of named groups generated at construction time.

Parameters:
name - the configuration parameter name.
defaultArray - the default array to return (as a list) when the parameter is not present.
Returns:
the list or the default array as a list.

getValue

public Color getValue(String name,
                      Color defaultValue)
Gets a color from a named parameter in this helper's configuration. If the parameter is not found, or if it is found but the value cannot be parsed as a color, the indicated default value is returned instead.

The configuration parameter's value for the color is of the form parsed by Color.decode(String) (e.g., 0x0000FF for blue), with the HTML code being allowed as well (e.g., #0000FF).

This method searches for the named parameter in the list of named groups generated at construction time.

Parameters:
name - the configuration parameter name.
defaultValue - the default value when the parameter is not present.
Returns:
the parsed color or the default value.

getValue

public <E extends Enum<E>> E getValue(String name,
                                      E defaultValue)
Gets an enum from a named parameter in this helper's configuration. If the parameter is not found, or if it is found but the value cannot be parsed as an enum, the indicated default value is returned instead.

Note that this method assumes the names of the enum in question are all uppercase; if an enum value has a mixed-case name, this method will not recognize it. Correspondingly, the value of the configuration parameter is coerced to uppercase for the match.

This method searches for the named parameter in the list of named groups generated at construction time.

Parameters:
name - the configuration parameter name.
defaultValue - the default value when the parameter is not present.
Returns:
the enum value of the parameter or the default value.

getValue

public <E extends Enum<E>> List<E> getValue(String name,
                                            E[] defaultArray)
Gets a list of enums from a named parameter in this helper's configuration. If the parameter is not found, or if it is found but the value is null, or if it is not a sequence or a series, or if is empty, or if any of its elements cannot be parsed as an enum, the indicated default value is returned instead.

Note that this method assumes the names of the enum in question are all uppercase; if an enum value has a mixed-case name, this method will not recognize it. Correspondingly, the value of the configuration parameter is coerced to uppercase for the match.

This method searches for the named parameter in the list of named groups generated at construction time.

Parameters:
name - the configuration parameter name.
defaultArray - the default array to return (as a list) when the parameter is not present, etc.
Returns:
the array or the default array.

patchConfiguration

public static void patchConfiguration(Configuration configuration,
                                      boolean override,
                                      String... catalogGroups)
                               throws Configuration_Exception
Patches the server group of the indicated input configuration.

The "server group" is a PVL aggregate parameter that has the same as the value of the server parameter. It contains the information necessary to connect to given database via the PIRL Database class. Such information includes the operator's username, the operator's password, the database server, the database type, and the database catalog to use.

If the server group lacks a catalog parameter, a new one is created with the value of the catalog parameter found in the set of catalogGroups; if no catalogGroups are supplied, Constants.BASE_CONFIGURATION_GROUPS is used. If the server group already has a catalog parameter and override is true, the catalog parameter is updated; if false, the catalog parameter is left unchanged.

Parameters:
configuration - the configuration to be patched.
override - if true, the patching process overrides any pre-existing values; if false, pre-existing values are left unchanged, but non-existing parameters will still be created.
catalogGroups - the set of groups to search for the database catalog parameter; if not supplied, default values are used.
Throws:
Configuration_Exception - if the configuration cannot be patched.

patchConfiguration

public static void patchConfiguration(Configuration configuration,
                                      String... catalogGroups)
                               throws Configuration_Exception
Patches the server group of the indicated input configuration. Existing values will not be overridden.

Parameters:
configuration - the configuration to be patched.
catalogGroups - the set of groups to search for the database catalog parameter; if not supplied, default values are used.
Throws:
Configuration_Exception
See Also:
patchConfiguration(Configuration,boolean,String...)

maskPasswords

public static Configuration maskPasswords(Configuration configuration)
Sanitizes the input configuration by masking the value of each password parameter.

A "password" parameter is one for which Parameter.Is_Assignment() is true and whose name ends with the text PASSWORD_IDENTIFIER (case-insensitive). The value of such a parameter is changed to PASSWORD_MASK.

This method works on and returns a clone of the configuration, leaving the original configuration untouched.

Parameters:
configuration - the configuration to sanitize of passwords.
Returns:
a configuration containing the contents of the original configuration, but with password values masked.

getServer

public static String getServer(Configuration configuration)
Gets the value of the server parameter from the input configuration. The server parameter (Database.SERVER) identifies the group from which to get database connection parameters. It must be located at the root level of the configuration.

Parameters:
configuration - the configuration to search.
Returns:
the server parameter value, or null if no such parameter is found.

getCatalog

public static String getCatalog(Configuration configuration,
                                String... catalogGroups)
Gets the value of the catalog parameter from the input configuration. The catalog parameter (Database.CATALOG) identifies the catalog (or "database," in MySQL parlance) to use for database operations.

This method searches a list of parameter groups for the catalog parameter, identified by the input catalogGroups vararg array. If the array is zero length, the Constants.BASE_CONFIGURATION_GROUPS array is used instead. In any case, however, the server group is searched first.

Parameters:
configuration - the configuration to search.
catalogGroups - the set of parameter groups to search in addition to the server group.
Returns:
the catalog parameter value, or null if no such parameter is found.

getConfigurationValue

public static String getConfigurationValue(String name,
                                           Configuration configuration,
                                           List<String> groups)
Gets a string value from a named parameter in the indicated configuration. The indicated list of parameter groups is searched; if the list is null or if it is empty, the Constants.BASE_CONFIGURATION_GROUPS is searched instead.

If the parameter is an array type (a set or a series), the entire array is returned as a single string. If the parameter is a token (i.e., no value), the parameter name itself is returned. If the parameter is not found, null is returned.

Parameters:
name - the name of the configuration parameter.
configuration - the configuration to search.
groups - the list of groups to search; may be null or empty.
Returns:
the value of the named parameter or null if it cannot be found.

getConfigurationValue

public static String getConfigurationValue(String name,
                                           Configuration configuration)
Gets a string value from a named parameter in the indicated configuration. The Constants.BASE_CONFIGURATION_GROUPS list is searched.

If the parameter is an array type (a set or a series), the entire array is returned as a single string. If the parameter is a token (i.e., no value), the parameter name itself is returned. If the parameter is not found, null is returned.

Parameters:
name - the name of the configuration parameter.
configuration - the configuration to search.
Returns:
the value of the named parameter or null if it cannot be found.
See Also:
getConfigurationValue(String,Configuration,List)

getConfigurationValueList

public static List<String> getConfigurationValueList(String name,
                                                     Configuration configuration,
                                                     List<String> groups)
Gets a list of strings from a named parameter in the indicated configuration. The indicated list of parameter groups is searched; if the list is null or if it is empty, the Constants.BASE_CONFIGURATION_GROUPS is searched instead.

If the parameter is an array type (a set or a series), the list contains each element of the array, as a string, in the order found in the array. If the parameter is a simple assignment, the list contains only its single value. If the parameter is any other type, including a token (i.e., no value), or if the parameter is not found, a null is returned.

Parameters:
name - the name of the configuration parameter.
configuration - the configuration to search.
groups - the list of groups to search; may be null or empty.
Returns:
a list of the values of the named parameter or null if it cannot be found.

getConfigurationValueList

public static List<String> getConfigurationValueList(String name,
                                                     Configuration configuration)
Gets a list of strings from a named parameter in the indicated configuration. The Constants.BASE_CONFIGURATION_GROUPS list is searched.

If the parameter is an array type (a set or a series), the list contains each element of the array, as a string, in the order found in the array. If the parameter is a simple assignment, the list contains only its single value. If the parameter is any other type, including a token (i.e., no value), or if the parameter is not found, a null is returned.

Parameters:
name - the name of the configuration parameter.
configuration - the configuration to search.
Returns:
a list of the values of the named parameter or null if it cannot be found.
See Also:
getConfigurationValueList(String,Configuration,List)

getConnectionInfo

public static String getConnectionInfo(Configuration configuration,
                                       String... catalogGroups)
Gets a simple text summary of the database connection information from a configuration. The catalogGroups varargs parameter identifies additional groups to search for the catalog parameter if it is not found in the server group. If catalogGroups is not supplied, Constants.BASE_CONFIGURATION_GROUPS is used.

The summary is of the form

        Catalog CATALOG on host HOST ("SERVER")

with no trailing period and no newline. HOST is the database host. If a PORT parameter is supplied as well, it is appended to the HOST.

Parameters:
configuration - the configuration to search.
catalogGroups - the set of parameter groups to search in addition to the server group for the catalog parameter.
Returns:
a text summary of the database connection information.

getConfiguration

public static Configuration getConfiguration(String source,
                                             String propertyName,
                                             String... defaultFilenames)
                                      throws Configuration_Exception
Gets a configuration from a named source, a system property, or a set of default filenames.

If source is not null, this method will attempt to get the configuration from the file or resource named. The source can be a named local file or a URL pointing to a configuration.

If source is null, this method will attempt to get the configuration from the file or resource named in the system propertyName. If the propertyName parameter is null, Constants.CONFIGURATION_PROPERTY is used.

Finally, if source is null and the value of the named or default system property is null, this method will search for a configuration through a set of defaultFilenames. If there are no such filenames, the HiPlan-centric Constants.CONFIGURATION_FILENAMES are used; see getDefaultConfigurationFile(String...).

If a configuration cannot be loaded, this method returns null.

Parameters:
source - a named configuration source; may be null.
propertyName - the name of a system property whose value is a configuration source; may be null.
defaultFilenames - a set of default filenames to check.
Returns:
a configuration or null if no configuration can be loaded.
Throws:
Configuration_Exception - if a configuration cannot be built from the loaded data.

getDefaultConfigurationFile

public static File getDefaultConfigurationFile(String... defaultFilenames)
Gets a file from a set of filenames. If no default filenames are provided, the HiPlan-centric Constants.CONFIGURATION_FILENAMES are used (HiPlan.conf, HOGG.conf).

Several variations of the filenames are tried. The bare filename is tried, followed by the filename preceded by a dot (e.g, HiPlan.conf and then .HiPlan.conf). The user's current directory is checked first, followed by the user's home directory.

Thus, on a UNIX-like system, using the HiPlan-centric filenames, the following files are checked in the following order:

  1. ./HiPlan.conf
  2. ./HOGG.conf
  3. ./.HiPlan.conf
  4. ./.HOGG.conf
  5. ~/HiPlan.conf
  6. ~/HOGG.conf
  7. ~/.HiPlan.conf
  8. ~/.HOGG.conf

If the method were called with HiCommand.conf as its only default filename, then the following files would be checked in the following order:

  1. ./HiCommand.conf
  2. ./.HiCommand.conf
  3. ~/HiCommand.conf
  4. ~/.HiCommand.conf

If a file is found and it is a proper file (not a directory) and the operator can read it, that file is returned. If no file can be found, null is returned.

Parameters:
defaultFilenames - the set of filenames to check through various variations outlined above.
Returns:
a file if found and readable, or null.

makeGroups

public static List<String> makeGroups(String preferredGroup,
                                      String... groupAdditions)
Creates a list of strings from the input strings, using default values as appropriate. Each string is presumed to be a PVL group name.

If preferredGroup is null, the first element of the list is the first element of groupAdditions.

If there are no group additions, Constants.BASE_CONFIGURATION_GROUPS is used instead.

Parameters:
preferredGroup - the first string of the resulting list; may be null.
groupAdditions - additional values for the list.
Returns:
a list of strings.

HiRISE

Copyright (C) Arizona Board of Regents on behalf of the Planetary Image Research Laboratory, Lunar and Planetary Laboratory at the University of Arizona