HiRISE

HiRISE.HiPlan.Utilities
Class JmarsConfiguration

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

public class JmarsConfiguration
extends Object

A reimplementation of the JMARS configuration class. It has many of the same methods and uses the same logic. It provides some different functionality, however.

WARNING This class should not be used as a substitute for the JMARS configuration class Config. It should also not be used alongside the JMARS configuration class.

It's worth noting that this class uses the JMARS Main class and the JMARS configuration class. Each of these classes feature complex static initializers that ultimately initialize the JMARS configuration system itself, whether desired or not. These classes also log a lot of information to the JMARS logging system. It might be worth setting the JMARS logging output stream to null:

        edu.asu.jmars.util.DebugLog.setOutputStream(null);

Configuration Property Sources

JMARS has several sources for configuration properties: the so-called "jar" properties, the saved properties, the current-directory properties, and the Java system properties. Each of the file-based properties files is called jmars.config.

Jar Properties Jar properties are stored in the JMARS distribution package, at the root of the JMARS class hierarchy in a directory called resources. They are found here even if JMARS is not packaged as a jar. One can think of these as the application defaults.

Saved Properties The saved properties are typically found in the operator's home directory in a subdirectory called jmars. The actual location is determined via Main.getJMarsPath() and may be different. These properties are intended to be programmatically managed by JMARS, primarily. When the JMARS configuration class saves properties, they are written to this file, for example.

Current-Directory Properties The current-directory properties are found in the current working directory, typically the directory from which JMARS was started (assuming a command-line launch). These are the easily user-customizable properties. It is this config file that holds the PlanC-related JMARS configuration, including, especially, the layer factory properties that define the PlanC layers.

System Properties JMARS includes a fourth set of properties: The system properties themselves. Any system property prefixed by "jmars." is assumed to be a JMARS config property, with everything after the "jmars." portion being the property key. This is especially useful for adding a JMARS config property to the command line, e.g.,

        -Djmars.factory.10="org.uahirise.cassis.plan.layer FooFactory"

This command-line addition defines the JMARS property factory.10 with the value org.uahirise.cassis.plan.layer FooFactory. Note that in this case, quotes are needed because the key's value has two components: the package and the factory class.

JMARS attempts to load file-based configurations directly, unless the first two characters in the file are the shebang sequence, #!. If so, then JMARS attempts to execute the config file as a shell script and use the script's output as the configuration source.

JMARS also includes a facility for remote properties. If a give property key is of the form config.url.*, JMARS attempts to read from its value as a URL. The properties so read are treated as jar properties, even if the URL is found elsewhere in the configuration hierarchy. If the URL starts with http://, then the value of Main.About.SECS is appended to the URL as an optional parameter with the jmars_config key.

Note that the remote properties facility is not directly invoked by the JMARS configuration class; it is manually invoked in the JMARS application main class, Main. Thus, using the JMARS configuration class outside of JMARS itself does not guarantee that the remote properties will be loaded.

Precedence

JMARS obeys the following rules of precedence when retrieving a config parameter:

  1. System property
  2. Current-directory property
  3. Saved property
  4. Jar property and remote properties

(Lifted from PlanC.)

Version:
1.0
Author:
Christian Schaller - UA/LPL/PIRL
See Also:
Config, Properties

Field Summary
static String COMMAND_LINE_PROPERTY_TAG
           
static String CURRENT_DIRECTORY_PROPERTY_TAG
           
static String ID
          Class identification name with source code version and date.
static String JAR_PROPERTY_TAG
           
static String JMARS_CONFIG
          The JMARS configuration filename.
static String JMARS_RESOURCES_DIR
          The JMARS resources directory name.
static String JMARS_SYSTEM_PROPERTY_PREFIX
          The prefix for JMARS-related system properties.
static String REMOTE_PROPERTY_PREFIX
          The prefix for remote configuration properties.
static String SAVED_PROPERTY_TAG
           
 
Method Summary
static String appendDot(String prefix)
          Appends a dot character ('.') to the input configuration key prefix.
 String get(String key)
          Gets a named configuration property.
 boolean get(String key, boolean defaultValue)
          Gets a named boolean configuration property.
 double get(String key, double defaultValue)
          Gets a named double-precision floating point configuration property.
 int get(String key, int defaultValue)
          Gets a named integer configuration property.
 String get(String key, String defaultValue)
          Gets a named configuration property.
 List<KeyValuePair> getAll(String prefix)
          Gets every property with the indicated key prefix.
 List<KeyValuePair> getAllWithSource()
           
 List<KeyValuePair> getAllWithSource(String prefix)
           
 String[] getArray(String prefix)
          Gets an array of every key in an ordered list of keys with the indicated prefix.
 String[] getChildKeys(String parentKey)
          Returns every key that is a child of the indicated parent key.
static JmarsConfiguration getInstance()
          Gets the shared instance of the PlanC JAMRS configuration stand-in.
 Throwable getJarPropertiesException()
          Gets the exception thrown during the loading of the jar properties.
 Throwable getLocalPropertiesException()
          Gets the exception thrown during the loading of the local properties.
 Throwable getRemotePropertiesException()
          Gets the exception thrown during the loading of remote properties.
 Throwable getSavedPropertiesException()
          Gets the exception thrown during the loading of the saved properties.
 void loadRemoteProperties()
          Loads remote properties identified in the existing properties set.
static String truncateDot(String prefix)
          Removes a trailing dot character ('.') from the input configuration key prefix.
 
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

JMARS_CONFIG

public static final String JMARS_CONFIG
The JMARS configuration filename. The config file has this name whether it's for the jar properties, the saved properties, or the current-directory properties.

See Also:
Constant Field Values

JMARS_RESOURCES_DIR

public static final String JMARS_RESOURCES_DIR
The JMARS resources directory name. The so-called "jar" properties config file is found in this directory, located at the base of the JMARS class hierarchy:
        URL jarPropertiesUrl = edu.asu.jmars.Main.class.getResource(
                "/" + JMARS_RESOURCES_DIR + "/" + JMARS_CONFIG
        );

See Also:
Constant Field Values

JMARS_SYSTEM_PROPERTY_PREFIX

public static final String JMARS_SYSTEM_PROPERTY_PREFIX
The prefix for JMARS-related system properties. Note the prefix includes a dot character.

See Also:
Constant Field Values

REMOTE_PROPERTY_PREFIX

public static final String REMOTE_PROPERTY_PREFIX
The prefix for remote configuration properties. Note the prefix includes a dot character.

See Also:
Constant Field Values

JAR_PROPERTY_TAG

public static final String JAR_PROPERTY_TAG
See Also:
Constant Field Values

SAVED_PROPERTY_TAG

public static final String SAVED_PROPERTY_TAG
See Also:
Constant Field Values

CURRENT_DIRECTORY_PROPERTY_TAG

public static final String CURRENT_DIRECTORY_PROPERTY_TAG
See Also:
Constant Field Values

COMMAND_LINE_PROPERTY_TAG

public static final String COMMAND_LINE_PROPERTY_TAG
See Also:
Constant Field Values
Method Detail

loadRemoteProperties

public void loadRemoteProperties()
Loads remote properties identified in the existing properties set. A remote property is identified by the key prefix REMOTE_PROPERTY_PREFIX, and such a property may appear in any of the configuration files (jar, saved, or local).


get

public String get(String key,
                  String defaultValue)
Gets a named configuration property. See the "Precedence" section, above, for details. If the key cannot be found, defaultValue is returned.

Parameters:
key - the property key to search for.
defaultValue - the value to return if the key is not found; may be null.
Returns:
the property value or the default value; may be null.

get

public String get(String key)
Gets a named configuration property. See the "Precedence" section, above, for details. If the key cannot be found, this method returns a null value.

Parameters:
key - the property key to search for.
Returns:
the property value or null if not found.
See Also:
get(String,String)

get

public boolean get(String key,
                   boolean defaultValue)
Gets a named boolean configuration property. See the "Precedence" section, above, for details. If the key cannot be found, or if the value cannot be parsed as a boolean, defaultValue is returned.

YES and NO are acceptable alternatives to TRUE and FALSE, respectively. Case is ignored in parsing.

Parameters:
key - the property key to search for.
defaultValue - the value to return if the key is not found.
Returns:
the property value or the default value.

get

public int get(String key,
               int defaultValue)
Gets a named integer configuration property. See the "Precedence" section, above, for details. If the key cannot be found, or if the value cannot be parsed as an integer, defaultValue is returned.

Parameters:
key - the property key to search for.
defaultValue - the value to return if the key is not found.
Returns:
the property value or the default value.

get

public double get(String key,
                  double defaultValue)
Gets a named double-precision floating point configuration property. See the "Precedence" section, above, for details. If the key cannot be found, or if the value cannot be parsed as a double, defaultValue is returned.

Parameters:
key - the property key to search for.
defaultValue - the value to return if the key is not found.
Returns:
the property value or the default value.

getAll

public List<KeyValuePair> getAll(String prefix)
Gets every property with the indicated key prefix. If the prefix is null or the empty string (""), all properties are returned. If the prefix is not empty and does not end with a '.' character, one is appended.

The returned list is sorted.

Parameters:
prefix - the prefix to search for; may be null.
Returns:
a sorted list of key-value pairs; each key matches and includes the input key prefix.

getAllWithSource

public List<KeyValuePair> getAllWithSource(String prefix)

getAllWithSource

public List<KeyValuePair> getAllWithSource()

getChildKeys

public String[] getChildKeys(String parentKey)
Returns every key that is a child of the indicated parent key. The configuration keys are treated as paths from the configuration tree's root node down to the referenced node, where each node in the path is separated from the others by a dot (".") character.

Consider the following configuration parameters:

        a.b.c 1
        a.b.d 2
        a.c.x 3
        a.d   4

getChildKeys("a") returns {"a.b", "a.c", "a.d"}.

getChildKeys("a.b") returns {"a.b.c", "a.b.d"}.

Parameters:
parentKey - the parent key for the search.
Returns:
an array of unique child keys for the parent key; may be empty but will not be null.
See Also:
appendDot(String)

getArray

public String[] getArray(String prefix)
Gets an array of every key in an ordered list of keys with the indicated prefix. The keys will be in the form prefix.n where n starts at 1. The ordered list is terminated by a break in the numbering or by an empty value. For example, given the following parameters, getArray("foo") will return the first four keys:
        foo.1 abc
        foo.2 def
        foo.3 ghi
        foo.4 jkl
        foo.6 pqr

Because there is no "foo.5" key, the array ends with "foo.4." Similarly, for the following parameters, getArray("bar") returns the first two keys:

        bar.1 abc
        bar.2 def
        bar.3
        bar.4 jkl

The blank value for "bar.3" terminates the list.

If prefix does not end with a dot (".") character, one will be appended.

Parameters:
prefix - the key prefix for the ordered list of parameter keys.
Returns:
an ordered array of keys with the indicated prefix; may be empty but will not be null.
See Also:
appendDot(String)

getJarPropertiesException

public Throwable getJarPropertiesException()
Gets the exception thrown during the loading of the jar properties. If no exception was thrown, this method returns a null.

Returns:
an exception if one was thrown while reading the JMARS jar properties or null.

getSavedPropertiesException

public Throwable getSavedPropertiesException()
Gets the exception thrown during the loading of the saved properties. If no exception was thrown, this method returns a null.

Returns:
an exception if one was thrown while reading the JMARS saved properties or null.

getLocalPropertiesException

public Throwable getLocalPropertiesException()
Gets the exception thrown during the loading of the local properties. If no exception was thrown, this method returns a null.

Returns:
an exception if one was thrown while reading the JMARS local properties or null.

getRemotePropertiesException

public Throwable getRemotePropertiesException()
Gets the exception thrown during the loading of remote properties. If no exception was thrown, this method returns a null.

Returns:
an exception if one was thrown while reading remote JMARS properties or null.

appendDot

public static String appendDot(String prefix)
Appends a dot character ('.') to the input configuration key prefix. If the key is the empty string (""), the dot is not appended. If the key is null, this method returns the empty string (and does not append a dot!).

This method also trims whitespace from the beginning and end of the prefix prior to modification.

Parameters:
prefix - the configuration key prefix to modify; may be null.
Returns:
the prefix with extra whitespace trimmed and a dot character appended, or the empty string if the prefix is null or is already the empty string.
See Also:
String.trim()

truncateDot

public static String truncateDot(String prefix)
Removes a trailing dot character ('.') from the input configuration key prefix. If the key is null, this method returns the empty string.

This method also trims whitespace from the beginning and end of the prefix prior to modification.

Parameters:
prefix - the configuration key prefix to modify; may be null.
Returns:
the prefix with extra whitespace trimmed and a dot character removed from the end, or the empty string if the prefix is null.
See Also:
String.trim()

getInstance

public static JmarsConfiguration getInstance()
Gets the shared instance of the PlanC JAMRS configuration stand-in. If the configuration has not been created, it is created and the jar, saved, and local properties are read. Exceptions may be thrown at that time; if so, they are saved and may be retrieved by appropriate methods.

Note that remote properties are not loaded when the shared instance is created; a separate call to loadRemoteProperties() is required.

Returns:
the PlanC JMARS configuration stand-in.
See Also:
getJarPropertiesException(), getSavedPropertiesException(), getLocalPropertiesException()

HiRISE

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