edu.nrao.widar.util
Class SystemProperties

java.lang.Object
  edu.nrao.widar.util.SystemProperties

public class SystemProperties
extends java.lang.Object

General purpose utility class for working with the JVM's System Properites. Java's JVM maintains a set of system properties that include the platform's environment variables and information about the JVM itself. Other properties may be added to this set at run time and these properties will then be available for use by any process in the JVM simply by using the java.lang.System.getProperty() method.

This Class provides static convenience methods to load sets of properties from specified files into the System Properties set. It also provides methods for working with these properties.

Checks are made to ensure that any particular set of properties is only loaded once even if requested more than once by different processes running in the JVM.

When the static load method of this Class is called for the first time, it starts a logger and a timer, subsequent calls to load do not do this. Everytime the load method is called, the name of the property file is kept in a list. At some periodic rate CHANGE_CHECK_PERIOD_SECONDS all the files that have been loaded are checked to see if they changed. Any file that has changed is reloaded into the System Properties so that they dynamically reflect the state of the file (to the nearest CHANGE_CHECK_PERIOD_SECONDS).

If an application wants to ensure that it always has the latest value for a property, it must reference the property using the java.lang.System.getProperty() method every time it uses it instead of saving it one time to a local variable and using the variable.

The WIDAR property files are located by default at widar properties. However it is possible to load properties at a different location by setting the environment variable WIDAR_PROPERTIES_URL.

java.util.Properties.load(URL) is used to load a property file from the above URL. This can be done over the internet as long the property files can be served by a web server.

An example of the property file used for the WIDAR On The Sky Prototype testing is shown here:

 ots.server.remoteFile = 192.139.21.151
 ots.dir.main = /opt/widar/otsTesting/
 ots.dir.stb.output.data = /opt/widar/otsTesting/stbOutput/data/
 ots.dir.stb.output.data.golden = /opt/widar/otsTesting/stbOutput/data/golden/
 ots.dir.stb.output.config = /opt/widar/otsTesting/stbOutput/config/
 ots.file.stb.output.config.default = stbListenerConfigDefault.xml
 ots.dir.config = /opt/widar/otsTesting/configFiles/
 ots.id.stationBoard.1 = 001-0-0
 ots.id.stationBoard.2 = 001-0-1
 ots.id.baselineBoard.1 = 101-0-0
 ots.ip.stationBoard.1 = 10.64.97.25
 ots.ip.stationBoard.2 = 10.64.97.26
 ots.ip.stationBoard.3 = 10.64.97.22
 ots.ip.stationBoard.4 = 192.139.21.48
 ots.ip.stationBoard.5 = 192.139.21.151
 ots.ip.baselineBoard.1 = 10.64.97.30
 

These are similar to industry property files like Apple's .plist files and are recognized and readable as such by the Java language. The simple rules are:

One parameter name = value per line

'=' separates name and value

Since:

1.5

Author:

KJRyan

Created:

2008.05.24

Field Summary

static int	CHANGE_CHECK_PERIOD_SECONDS
static java.lang.String	DEFAULT_WIDAR_PROPERTIES_URL This is the default URL for WIDAR system properties.
static java.lang.String	MAIN_PROPERTY_FILE This is the name of the main property file that, among other things, specifies other property files to load.
static java.lang.String	WIDAR_PROPERTIES_URL

Constructor Summary

SystemProperties()

Method Summary

static java.lang.String	get(java.lang.String propertyName) Safe method for obtaining a System property value.
static float	get(java.lang.String propertyName, float defaultValue) Safe method for obtaining a specified System property value of a float type with a guaranteed value returned.
static int	get(java.lang.String propertyName, int defaultValue) Safe method for obtaining a specified System property value of an integer type with a guaranteed value returned.
static java.lang.String	get(java.lang.String propertyName, java.lang.String defaultValue) Safe method for obtaining a specified System property value with guaranteed value returned.
static java.util.Properties	getPropertySetCopy(java.lang.String propertySetName) Returns a deep copy of a specified property set.
static void	load() Loads the properties specified in the main properties file.
static void	load(java.lang.String filename) Loads the properties from a specified file into the JVM's System Properties.
static void	reload(java.lang.String filename) Reloads properties from a specified file.
static java.lang.String[]	startingWith(java.lang.String startString) Convenience method to return an java.util.ArrayList<String> of System Property names that begin with a specified String.
static java.lang.String[]	valuesForNamesStartingWith(java.lang.String startString) Convenience method to return a String[] of property values whose property names start with a specified value.
static java.lang.String[]	withAValueOf(java.lang.String valueString) Convenience method to return an String[]} of System Property names having a specified value.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DEFAULT_WIDAR_PROPERTIES_URL

public static final java.lang.String DEFAULT_WIDAR_PROPERTIES_URL

This is the default URL for WIDAR system properties. To point to a different set of properties set the environment variable WIDAR_PROPERTIES_URL to point to the properties;

See Also:

Constant Field Values

WIDAR_PROPERTIES_URL

public static java.lang.String WIDAR_PROPERTIES_URL

MAIN_PROPERTY_FILE

public static final java.lang.String MAIN_PROPERTY_FILE

This is the name of the main property file that, among other things, specifies other property files to load.

See Also:

Constant Field Values

CHANGE_CHECK_PERIOD_SECONDS

public static final int CHANGE_CHECK_PERIOD_SECONDS

See Also:

Constant Field Values

Constructor Detail

SystemProperties

public SystemProperties()

Method Detail

load

public static void load()
                 throws java.io.IOException

Loads the properties specified in the main properties file. Programs do not have to specify the property file to load; this provides flexibility in that the loaded property file can change (by editiing the main file) without having to recompile. For example: during OTS testing we will use special OTS directory structure so the the main property file specifies to load 'otsTesting.properties' which specifies the OTS directory structure. When we finish OTS testing a different file structure will probably be used for configurations and whatnot.

Throws:

java.io.IOException - if problems ore encounterd during the load.

reload

public static void reload(java.lang.String filename)
                   throws java.io.IOException

Reloads properties from a specified file. In order to reduce extraneous work, the normal load method checks to see if a file of properties has already been loaded before loading it again. In order to force a new load use this method. It not only reloads the System properties from the file but also clears out the old properties from System so that if the file changed from a removed property that property will also be removed from the System.

Throws:

java.io.IOException

load

public static void load(java.lang.String filename)
                 throws java.io.IOException

Loads the properties from a specified file into the JVM's System Properties.
This method simplifies the loading from file and storing to System. It also provides encapsulation of the main properties directory URL from users so if it changes it only has to be changed once here.

Throws:

java.io.IOException - if problems are encountered loading the properties.

Parameters:

filename - the name of the file in the main properties directory.

getPropertySetCopy

public static java.util.Properties getPropertySetCopy(java.lang.String propertySetName)

Returns a deep copy of a specified property set. A clone of the specified set is return consiting of a new Properties object containing new key/value Strings. This is to protect our original from nefarious tinkerers. This wouild certainly be necessary when we did differences between our version of a loaded property file and the file itself for automatic updating. Even though we do not do that now, it is still a good idea keep our copy safe in case we ever do decide to use it in a way that necessitates it remains the way we got it. A property 'set' normally refers to a set of properties loaded from a file and the set's name is the filename which is how it is keyed in our propertiesCopy Hashtable. But we will not limit this set name to the syntax of a filename in case future requirements allow loading properties from other sources. So the property set name is any String that is used as a key into our Hashtable of copies of the properties we loaded.

Parameters:

propertySetName - the name of the properties to fetch ex: 'system.properties' for the set of properties that were loaded from the file of that name.

Returns:

a deep copy of the Properties obtained from our archive of property sets previous loaded or null if no set is found matching propertySetName

get

public static java.lang.String get(java.lang.String propertyName)

Safe method for obtaining a System property value. This method uses the java.lang.System.getProperty method but catches all the possible exceptions so routine users do not have to. If any exception is experienced a null is returned just as if the property did not exist.

Parameters:

propertyName - the name of the system property to fetch

Returns:

the value of the specified system property or null if the property does not exist or if an exception was thrown attempting to fetch it

get

public static java.lang.String get(java.lang.String propertyName,
                                   java.lang.String defaultValue)

Safe method for obtaining a specified System property value with guaranteed value returned. This method uses the java.lang.System.getProperty method but catches all the possible exceptions so routine users do not have to. If the property is not found or if any exception is experienced, the specified default valued is returned.

Parameters:

propertyName - the name of the system property to fetch

defaultValue - the value to be returned if propertyName does not exist or if an exception is experienced

Returns:

the value of the specified system property or the specified default value if the property does not exist or if an exception was thrown attempting to fetch it

get

public static int get(java.lang.String propertyName,
                      int defaultValue)

Safe method for obtaining a specified System property value of an integer type with a guaranteed value returned. Enough properties in the WIDAR system are used to specify an integer value that this method is warranted and will save the users from having to convert the String value themselves. This method requires a default value to be supplied which will be returned if any Exceptions occur while obtaining the specified System Property or while converting it from a String to an integer.

Parameters:

propertyName - the name of the system property to fetch

defaultValue - the value to be returned if propertyName does not exist or if an exception is experienced during the property fetching or while converting it to an int

Returns:

the integer value of the specified system property or the specified default value if the property does not exist or if an exception was thrown attempting to fetch it or convert it from String to integer

get

public static float get(java.lang.String propertyName,
                        float defaultValue)

Safe method for obtaining a specified System property value of a float type with a guaranteed value returned. This method requires a default value to be supplied which will be returned if any Exceptions occur while obtaining the specified System Property or while converting it from a String to an integer.

Parameters:

propertyName - the name of the system property to fetch

defaultValue - the value to be returned if propertyName does not exist or if an exception is experienced during the property fetching or while converting it to an int

Returns:

the float value of the specified system property or the specified default value if the property does not exist or if an exception was thrown attempting to fetch it or convert it from String to integer

startingWith

public static java.lang.String[] startingWith(java.lang.String startString)

Convenience method to return an java.util.ArrayList<String> of System Property names that begin with a specified String.
The following code snippit is an example of how this may be used to get the IP addresses of all the Station Boards. It first fetches a list of the the property names and then gets each's value to load into a drop-down field.

 for (String ip : SystemProperties.startingWith("ots.ip.station"))
    fldStbIpAddress.addItem(System.getProperty(ip));
 

Parameters:

startString - the String that is to be used by the java.lang.String.startsWith() method to find the System Properties whos names start with it

Returns:

a String[] of System Property names starting with startString

valuesForNamesStartingWith

public static java.lang.String[] valuesForNamesStartingWith(java.lang.String startString)

Convenience method to return a String[] of property values whose property names start with a specified value.
The following code snippit is an example of how this may be used to get the IP addresses of all the Station Boards.

 for (String ip : SystemProperties.valuesForNamesstartingWith
                  ("ots.ip.station"))
    fldStbIpAddress.addItem(ip);
 

Parameters:

startString - the String that is to be used by the java.lang.String.startsWith() method to find the System Properties whos names start with it

Returns:

a String[] of System Property values whose property names start with startString

withAValueOf

public static java.lang.String[] withAValueOf(java.lang.String valueString)

Convenience method to return an String[]} of System Property names having a specified value.
The following code snippit is an example of how this may be used to find the IP address of a board whose ID is known. The example assumes that the property names for IDs start with "ots.id" and those for IP Addresses start with "ots.ip" like this:

 ots.id.baselineBoard.2 = BB-2002
 ots.ip.baselineBoard.2 = 192.139.21.154
 

It finds the property(s) whose value is 'BB-2002' and then replaces the 'id' in the property name with 'ip' to fetch the corresponding 'ip' property value ('192.139.21.154').

            for(String prop : SystemProperties.withAValueOf(id)) {
                if (prop.startsWith("ots.id.")) {
                    prop = prop.replaceFirst("id", "ip");
                    boardIp = System.getProperty(prop);
                }
            }
 

Parameters:

valueString - the String that is to be used by the java.lang.String.equals() method to find the System Properties whos value equals it.

Returns:

a String[] of System Property names whose values match valueString