public class Configuration_Helper
extends java.lang.Object
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.
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.)
Modifier and Type | Field and Description |
---|---|
static java.lang.String |
ID
Class identification name with source code version and date.
|
static java.lang.String |
PASSWORD_IDENTIFIER
The text sequence identifying a password configuration parameter.
|
static java.lang.String |
PASSWORD_MASK
The text sequence used to mask a password.
|
static java.lang.String |
PORT
The identifier for an optional host port value.
|
Constructor and Description |
---|
Configuration_Helper(PIRL.Configuration.Configuration configuration,
java.lang.String preferredGroup,
java.lang.String... secondaryGroups)
Constructs a new configuration helper from the indicated configuration and
the indicated parameter search groups.
|
Modifier and Type | Method and Description |
---|---|
static java.lang.String |
getCatalog(PIRL.Configuration.Configuration configuration,
java.lang.String... catalogGroups)
Gets the value of the catalog parameter from the input configuration.
|
PIRL.Configuration.Configuration |
getConfiguration()
Gets the configuration used in the creation of this helper.
|
static PIRL.Configuration.Configuration |
getConfiguration(java.lang.String source,
java.lang.String propertyName,
java.lang.String... defaultFilenames)
Gets a configuration from a named source, a system property, or a set of
default filenames.
|
static java.lang.String |
getConfigurationValue(java.lang.String name,
PIRL.Configuration.Configuration configuration)
Gets a string value from a named parameter in the indicated configuration.
|
static java.lang.String |
getConfigurationValue(java.lang.String name,
PIRL.Configuration.Configuration configuration,
java.util.List<java.lang.String> groups)
Gets a string value from a named parameter in the indicated configuration.
|
static java.util.List<java.lang.String> |
getConfigurationValueList(java.lang.String name,
PIRL.Configuration.Configuration configuration)
Gets a list of strings from a named parameter in the indicated configuration.
|
static java.util.List<java.lang.String> |
getConfigurationValueList(java.lang.String name,
PIRL.Configuration.Configuration configuration,
java.util.List<java.lang.String> groups)
Gets a list of strings from a named parameter in the indicated configuration.
|
static java.lang.String |
getConnectionInfo(PIRL.Configuration.Configuration configuration,
java.lang.String... catalogGroups)
Gets a simple text summary of the database connection information from a
configuration.
|
static java.io.File |
getDefaultConfigurationFile(java.lang.String... defaultFilenames)
Gets a file from a set of filenames.
|
java.util.List<java.lang.String> |
getGroups()
Gets the list of groups to search for parameters.
|
java.lang.String |
getPreferredGroup()
Gets the preferred group to search for parameters.
|
java.lang.String[] |
getSecondaryGroups()
Gets the secondary groups to search for parameters.
|
static java.lang.String |
getServer(PIRL.Configuration.Configuration configuration)
Gets the value of the server parameter from the input configuration.
|
boolean |
getValue(java.lang.String name,
boolean defaultValue)
Gets a boolean value from a named parameter in this helper's configuration.
|
boolean[] |
getValue(java.lang.String name,
boolean[] defaultArray)
Gets an array of boolean primitives from a named parameter in this helper's
configuration.
|
java.awt.Color |
getValue(java.lang.String name,
java.awt.Color defaultValue)
Gets a color from a named parameter in this helper's configuration.
|
double |
getValue(java.lang.String name,
double defaultValue)
Gets a double-precision value from a named parameter in this helper's
configuration.
|
double[] |
getValue(java.lang.String name,
double[] defaultArray)
Gets an array of double primitives from a named parameter in this helper's
configuration.
|
<E extends java.lang.Enum<E>> |
getValue(java.lang.String name,
E defaultValue)
Gets an enum from a named parameter in this helper's configuration.
|
<E extends java.lang.Enum<E>> |
getValue(java.lang.String name,
E[] defaultArray)
Gets a list of enums from a named parameter in this helper's
configuration.
|
int |
getValue(java.lang.String name,
int defaultValue)
Gets an integer value from a named parameter in this helper's configuration.
|
int[] |
getValue(java.lang.String name,
int[] defaultArray)
Gets an array of integer primitives from a named parameter in this helper's
configuration.
|
java.lang.String |
getValue(java.lang.String name,
java.lang.String defaultValue)
Gets a text value from a named parameter in this helper's configuration.
|
java.util.List<java.lang.String> |
getValue(java.lang.String name,
java.lang.String[] defaultArray)
Gets a list of strings from a named parameter in this helper's configuration.
|
static java.util.List<java.lang.String> |
makeGroups(java.lang.String preferredGroup,
java.lang.String... groupAdditions)
Creates a list of strings from the input strings, using default values as
appropriate.
|
static PIRL.Configuration.Configuration |
maskPasswords(PIRL.Configuration.Configuration configuration)
Sanitizes the input configuration by masking the value of each password
parameter.
|
static void |
patchConfiguration(PIRL.Configuration.Configuration configuration,
boolean override,
java.lang.String... catalogGroups)
Patches the server group of the indicated input configuration.
|
static void |
patchConfiguration(PIRL.Configuration.Configuration configuration,
java.lang.String... catalogGroups)
Patches the server group of the indicated input configuration.
|
public static final java.lang.String ID
public static final java.lang.String PASSWORD_IDENTIFIER
masked
in the maskPasswords(Configuration)
method.public static final java.lang.String PASSWORD_MASK
public static final java.lang.String PORT
MySQL_Data_Port.PORT
,
Constant Field Valuespublic Configuration_Helper(PIRL.Configuration.Configuration configuration, java.lang.String preferredGroup, java.lang.String... secondaryGroups)
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.
configuration
- the configuration for this helper; may not be
nullpreferredGroup
- the first group searched for a given parameter; may
be null.secondaryGroups
- additional groups searched for a given parameter.java.lang.NullPointerException
- if the configuration is null.public PIRL.Configuration.Configuration getConfiguration()
public java.lang.String getPreferredGroup()
getGroups()
for a complete and accurate list of the groups to be searched.public java.lang.String[] getSecondaryGroups()
getGroups()
for a complete and accurate list of the groups to be searched.public java.util.List<java.lang.String> getGroups()
Configuration_Helper(Configuration,String,String...)
public boolean getValue(java.lang.String name, boolean defaultValue)
This method searches for the named parameter in the list
of named groups generated at construction time.
name
- the configuration parameter name.defaultValue
- the default value when the parameter is not present.public boolean[] getValue(java.lang.String name, boolean[] defaultArray)
This method searches for the named parameter in the list
of named groups generated at construction time.
name
- the configuration parameter name.defaultArray
- the default array to return when the parameter is
not present, etc.public int getValue(java.lang.String name, int defaultValue)
This method searches for the named parameter in the list
of named groups generated at construction time.
name
- the configuration parameter name.defaultValue
- the default value when the parameter is not present.public int[] getValue(java.lang.String name, int[] defaultArray)
This method searches for the named parameter in the list
of named groups generated at construction time.
name
- the configuration parameter name.defaultArray
- the default array to return when the parameter is
not present, etc.public double getValue(java.lang.String name, double defaultValue)
This method searches for the named parameter in the list
of named groups generated at construction time.
name
- the configuration parameter name.defaultValue
- the default value when the parameter is not present.public double[] getValue(java.lang.String name, double[] defaultArray)
This method searches for the named parameter in the list
of named groups generated at construction time.
name
- the configuration parameter name.defaultArray
- the default array to return when the parameter is
not present, etc.public java.lang.String getValue(java.lang.String name, java.lang.String defaultValue)
This method searches for the named parameter in the list
of named groups generated at construction time.
name
- the configuration parameter name.defaultValue
- the default value when the parameter is not present.public java.util.List<java.lang.String> getValue(java.lang.String name, java.lang.String[] defaultArray)
This method searches for the named parameter in the list
of named groups generated at construction time.
name
- the configuration parameter name.defaultArray
- the default array to return (as a list) when the
parameter is not present.public java.awt.Color getValue(java.lang.String name, java.awt.Color defaultValue)
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.
name
- the configuration parameter name.defaultValue
- the default value when the parameter is not present.public <E extends java.lang.Enum<E>> E getValue(java.lang.String name, E defaultValue)
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.
name
- the configuration parameter name.defaultValue
- the default value when the parameter is not present.public <E extends java.lang.Enum<E>> java.util.List<E> getValue(java.lang.String name, E[] defaultArray)
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.
name
- the configuration parameter name.defaultArray
- the default array to return (as a list) when the
parameter is not present, etc.public static void patchConfiguration(PIRL.Configuration.Configuration configuration, boolean override, java.lang.String... catalogGroups) throws PIRL.Configuration.Configuration_Exception
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.
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.PIRL.Configuration.Configuration_Exception
- if the configuration cannot be patched.public static void patchConfiguration(PIRL.Configuration.Configuration configuration, java.lang.String... catalogGroups) throws PIRL.Configuration.Configuration_Exception
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.PIRL.Configuration.Configuration_Exception
patchConfiguration(Configuration,boolean,String...)
public static PIRL.Configuration.Configuration maskPasswords(PIRL.Configuration.Configuration configuration)
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.
configuration
- the configuration to sanitize of passwords.public static java.lang.String getServer(PIRL.Configuration.Configuration configuration)
Database.SERVER
) identifies the group from which
to get database connection parameters. It must be located at the root
level of the configuration.configuration
- the configuration to search.public static java.lang.String getCatalog(PIRL.Configuration.Configuration configuration, java.lang.String... catalogGroups)
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.
configuration
- the configuration to search.catalogGroups
- the set of parameter groups to search in addition
to the server group.public static java.lang.String getConfigurationValue(java.lang.String name, PIRL.Configuration.Configuration configuration, java.util.List<java.lang.String> groups)
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.
name
- the name of the configuration parameter.configuration
- the configuration to search.groups
- the list of groups to search; may be null or empty.public static java.lang.String getConfigurationValue(java.lang.String name, PIRL.Configuration.Configuration configuration)
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.
name
- the name of the configuration parameter.configuration
- the configuration to search.getConfigurationValue(String,Configuration,List)
public static java.util.List<java.lang.String> getConfigurationValueList(java.lang.String name, PIRL.Configuration.Configuration configuration, java.util.List<java.lang.String> groups)
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.
name
- the name of the configuration parameter.configuration
- the configuration to search.groups
- the list of groups to search; may be null or empty.public static java.util.List<java.lang.String> getConfigurationValueList(java.lang.String name, PIRL.Configuration.Configuration configuration)
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.
name
- the name of the configuration parameter.configuration
- the configuration to search.getConfigurationValueList(String,Configuration,List)
public static java.lang.String getConnectionInfo(PIRL.Configuration.Configuration configuration, java.lang.String... catalogGroups)
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.
configuration
- the configuration to search.catalogGroups
- the set of parameter groups to search in addition
to the server group for the catalog parameter.public static PIRL.Configuration.Configuration getConfiguration(java.lang.String source, java.lang.String propertyName, java.lang.String... defaultFilenames) throws PIRL.Configuration.Configuration_Exception
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.
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.PIRL.Configuration.Configuration_Exception
- if a configuration cannot be built from the
loaded data.public static java.io.File getDefaultConfigurationFile(java.lang.String... defaultFilenames)
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:
If the method were called with HiCommand.conf as its only default filename, then the following files would be checked in the following order:
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.
defaultFilenames
- the set of filenames to check through various
variations outlined above.public static java.util.List<java.lang.String> makeGroups(java.lang.String preferredGroup, java.lang.String... groupAdditions)
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.
preferredGroup
- the first string of the resulting list; may be
null.groupAdditions
- additional values for the list.Copyright \ (C) Arizona Board of Regents on behalf of the \ Planetary Image Research Laboratory, Lunar and \ Planetary Laboratory at the University of Arizona