public class JmarsConfiguration
extends java.lang.Object
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);
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.
JMARS obeys the following rules of precedence when retrieving a config parameter:
(Lifted from PlanC.)
Config
,
Properties
Modifier and Type | Field and Description |
---|---|
static java.lang.String |
COMMAND_LINE_PROPERTY_TAG |
static java.lang.String |
CURRENT_DIRECTORY_PROPERTY_TAG |
static java.lang.String |
ID
Class identification name with source code version and date.
|
static java.lang.String |
JAR_PROPERTY_TAG |
static java.lang.String |
JMARS_CONFIG
The JMARS configuration filename.
|
static java.lang.String |
JMARS_RESOURCES_DIR
The JMARS resources directory name.
|
static java.lang.String |
JMARS_SYSTEM_PROPERTY_PREFIX
The prefix for JMARS-related system properties.
|
static java.lang.String |
REMOTE_PROPERTY_PREFIX
The prefix for remote configuration properties.
|
static java.lang.String |
SAVED_PROPERTY_TAG |
Modifier and Type | Method and Description |
---|---|
static java.lang.String |
appendDot(java.lang.String prefix)
Appends a dot character ('.') to the input configuration key prefix.
|
java.lang.String |
get(java.lang.String key)
Gets a named configuration property.
|
boolean |
get(java.lang.String key,
boolean defaultValue)
Gets a named boolean configuration property.
|
double |
get(java.lang.String key,
double defaultValue)
Gets a named double-precision floating point configuration property.
|
int |
get(java.lang.String key,
int defaultValue)
Gets a named integer configuration property.
|
java.lang.String |
get(java.lang.String key,
java.lang.String defaultValue)
Gets a named configuration property.
|
java.util.List<KeyValuePair> |
getAll(java.lang.String prefix)
Gets every property with the indicated key prefix.
|
java.util.List<KeyValuePair> |
getAllWithSource() |
java.util.List<KeyValuePair> |
getAllWithSource(java.lang.String prefix) |
java.lang.String[] |
getArray(java.lang.String prefix)
Gets an array of every key in an ordered list of keys with the indicated
prefix.
|
java.lang.String[] |
getChildKeys(java.lang.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.
|
java.lang.Throwable |
getJarPropertiesException()
Gets the exception thrown during the loading of the jar properties.
|
java.lang.Throwable |
getLocalPropertiesException()
Gets the exception thrown during the loading of the local properties.
|
java.lang.Throwable |
getRemotePropertiesException()
Gets the exception thrown during the loading of remote properties.
|
java.lang.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 java.lang.String |
truncateDot(java.lang.String prefix)
Removes a trailing dot character ('.') from the input configuration key
prefix.
|
public static final java.lang.String ID
public static final java.lang.String JMARS_CONFIG
public static final java.lang.String JMARS_RESOURCES_DIR
URL jarPropertiesUrl = edu.asu.jmars.Main.class.getResource( "/" + JMARS_RESOURCES_DIR + "/" + JMARS_CONFIG );
public static final java.lang.String JMARS_SYSTEM_PROPERTY_PREFIX
public static final java.lang.String REMOTE_PROPERTY_PREFIX
public static final java.lang.String JAR_PROPERTY_TAG
public static final java.lang.String SAVED_PROPERTY_TAG
public static final java.lang.String CURRENT_DIRECTORY_PROPERTY_TAG
public static final java.lang.String COMMAND_LINE_PROPERTY_TAG
public void loadRemoteProperties()
REMOTE_PROPERTY_PREFIX
,
and such a property may appear in any of the configuration files (jar,
saved, or local).public java.lang.String get(java.lang.String key, java.lang.String defaultValue)
key
- the property key to search for.defaultValue
- the value to return if the key is not found; may be
null.public java.lang.String get(java.lang.String key)
key
- the property key to search for.get(String,String)
public boolean get(java.lang.String key, boolean defaultValue)
YES and NO are acceptable alternatives to TRUE and FALSE, respectively. Case is ignored in parsing.
key
- the property key to search for.defaultValue
- the value to return if the key is not found.public int get(java.lang.String key, int defaultValue)
key
- the property key to search for.defaultValue
- the value to return if the key is not found.public double get(java.lang.String key, double defaultValue)
key
- the property key to search for.defaultValue
- the value to return if the key is not found.public java.util.List<KeyValuePair> getAll(java.lang.String prefix)
The returned list is sorted.
prefix
- the prefix to search for; may be null.public java.util.List<KeyValuePair> getAllWithSource(java.lang.String prefix)
public java.util.List<KeyValuePair> getAllWithSource()
public java.lang.String[] getChildKeys(java.lang.String parentKey)
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"}.
parentKey
- the parent key for the search.appendDot(String)
public java.lang.String[] getArray(java.lang.String prefix)
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.
prefix
- the key prefix for the ordered list of parameter keys.appendDot(String)
public java.lang.Throwable getJarPropertiesException()
public java.lang.Throwable getSavedPropertiesException()
public java.lang.Throwable getLocalPropertiesException()
public java.lang.Throwable getRemotePropertiesException()
public static java.lang.String appendDot(java.lang.String prefix)
This method also trims whitespace from the beginning and end of the prefix prior to modification.
prefix
- the configuration key prefix to modify; may be null.String.trim()
public static java.lang.String truncateDot(java.lang.String prefix)
This method also trims whitespace from the beginning and end of the prefix prior to modification.
prefix
- the configuration key prefix to modify; may be null.String.trim()
public static JmarsConfiguration getInstance()
Note that remote properties are not loaded when the shared instance
is created; a separate call to loadRemoteProperties()
is required.
getJarPropertiesException()
,
getSavedPropertiesException()
,
getLocalPropertiesException()
Copyright \ (C) Arizona Board of Regents on behalf of the \ Planetary Image Research Laboratory, Lunar and \ Planetary Laboratory at the University of Arizona