grace.util
Class Properties

java.lang.Object
  |
  +--grace.util.Properties

public class Properties
extends java.lang.Object

This class wraps and augments the behaviour of the java.util.Properties class. It is not inherited from the java class because bonheaded Javasoft made the properties class inherit from Hashtable. This has many problems which I will not go into here.

Anyway, this class allows a more flexible management of properties than the java version and allows a regular expression query mechanism. Note that this mechanism is a linear search as opposed to the get functions which use the hashtable lookup.

All properties loaded into this class are copied from their original list. This makes it easier to layer properties where different priorities are intended for differernt sources of properties. Typically, one would like to make default properties from the user's home directory the lowest priority, properties from a local file the next priority, properties from the command line the next, and properties set within the application the highest.

This class also manages parameters of an Applet so that users can treat properties and parameters as the same.

So, here is a typical use:

	grace.util.Properties properties = new grace.util.Properties();
	properties.loadParameters(anApplet);
	properties.loadHomeFile(".my-home-props");
	properties.loadFile(".my-local-props");
	properties.loadSystem();
      Vector someProps = properties.getRegexp("log.*");
 


Constructor Summary
Properties()
          A new empty list.
Properties(Properties properties)
          Constructs a property list that is a copy of the given list.
Properties(Properties properties)
          Constructs a property list that is a copy of the given list.
 
Method Summary
 java.lang.String get(java.lang.String name)
          Returns the value of the property referred to by name or null if the named property does not exist.
 java.lang.String get(java.lang.String[] names)
          Returns a property by searching linearly for each name in the array of names.
 java.lang.String get(java.lang.String[] names, java.lang.String defaultValue)
          Returns a property value by searching linearly for each name in array of names.
 java.lang.String get(java.lang.String name, java.lang.String defaultValue)
          Returns the value of the property referred to by name or defaultValue if the named property does not exist.
 java.util.Properties getJavaProperties()
          Returns a list of the properties.
 void integrateWithSystemProperties()
          If this set of properties is currently not a view of the System properties, then the System properties are loaded into this (just to make sure it doesn't wipe out any System properties), and the System properties are set to this collection.
 void load(Properties properties)
          Loads the given properties into this list by coping each property out of the given list and into this list.
 void load(Properties properties)
          Loads the given properties into this list by coping each property out of the given list and into this list.
 boolean loadFile(java.lang.String propertyFilename)
          Reads properties from the given file into this list.
 void loadHomeFile(java.lang.String basePropertyFilename)
          Reads properties from the given file into this list where the given file is assumed to be located in the user.home directory.
 void loadSystem()
          Loads a copy of the System properties (System.getProperties()) into this list.
 java.util.Enumeration names()
          Allows interation over all of the names of properties held by this class.
 java.util.Vector names(gnu.regexp.RE regexp)
          This returns a vector or names that match the given regular expression.
 java.util.Vector names(java.lang.String regexp)
          This returns a vector or properties names that match the given regular expression.
 void put(java.lang.String name, java.lang.String value)
          Sets the value of the property referred to by name.
 void segregateFromSystemProperties()
          If this set of properties is currently a view of the System properties, then a new interal property collection is created and the System properties are copied into the newly created collection.
 void set(java.util.Properties list)
          Sets the list of the properties maintained by this class.
static void setApplet(java.applet.Applet a)
          Remembers the given applet such that all subsequent get() functions on this class will query the applet for a named parameter using the Applet.getParameter(String) call.
 void setSystemProperties()
          This sets the System properties to the set managed by this class.
 Properties subset(gnu.regexp.RE regexp)
          Returns a subset of this Properties list narrowed by the given regular expression.
 Properties subset(gnu.regexp.RE regexp, java.lang.String nameSubstitution)
          Returns a subset of this Properties list narrowed by the given regular expression but with the names substituted with the given nameSubstitution.
 Properties subset(java.lang.String regexp)
          Returns a subset of this Properties list narrowed by the given regular expression.
 Properties subset(java.lang.String regexp, java.lang.String nameSubstitution)
           
 java.lang.String toString()
          Formats all of the properties as a String.
 java.util.Enumeration values()
          Allows interation over all of the values of properties held by this class.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

Properties

public Properties()
A new empty list.

Properties

public Properties(Properties properties)
Constructs a property list that is a copy of the given list.

Properties

public Properties(Properties properties)
Constructs a property list that is a copy of the given list.
Method Detail

load

public void load(Properties properties)
Loads the given properties into this list by coping each property out of the given list and into this list. Thus, the given properties will override any existing properties in this list.

load

public void load(Properties properties)
Loads the given properties into this list by coping each property out of the given list and into this list. Thus, the given properties will override any existing properties in this list.

setApplet

public static void setApplet(java.applet.Applet a)
Remembers the given applet such that all subsequent get() functions on this class will query the applet for a named parameter using the Applet.getParameter(String) call. The getParameter call is made only when the lookup fails to find the name in this list. Thus Applet parameters are lower priority than these properties. Also, none of the functions of this class that return vectors or Enumerations work with Applets parameters. Don't blame me; blame the Javasoft geniuses.

This is static right now because I can't figure out how to handle applets.


loadSystem

public void loadSystem()
Loads a copy of the System properties (System.getProperties()) into this list.

loadFile

public boolean loadFile(java.lang.String propertyFilename)
Reads properties from the given file into this list.

loadHomeFile

public void loadHomeFile(java.lang.String basePropertyFilename)
Reads properties from the given file into this list where the given file is assumed to be located in the user.home directory.

put

public void put(java.lang.String name,
                java.lang.String value)
Sets the value of the property referred to by name.
Parameters:
name - of property to set

get

public java.lang.String get(java.lang.String name)
Returns the value of the property referred to by name or null if the named property does not exist.
Parameters:
name - of property to get
Returns:
value of named property or null property doesn't exist

get

public java.lang.String get(java.lang.String name,
                            java.lang.String defaultValue)
Returns the value of the property referred to by name or defaultValue if the named property does not exist.

Note: This calls grace.util.Properties.get(String);

Parameters:
name - of property to get
defaultValue - to return if named property doesn't exist
Returns:
value of named property or defaultValue property doesn't exist

get

public java.lang.String get(java.lang.String[] names)
Returns a property by searching linearly for each name in the array of names. As soon as a name is found, it's value is returned. This is useful for looking up properties known by potentially many names.

Note: This calls grace.util.Properties.get(String[], String);

Parameters:
names - sequential list of names for which to search
Returns:
value of named property or null if not existent

get

public java.lang.String get(java.lang.String[] names,
                            java.lang.String defaultValue)
Returns a property value by searching linearly for each name in array of names. As soon as a name is found, it's value is returned. This is useful for looking up properties known by potentially many names. If no properties are found, the defaultValue is returned.

Note: This calls grace.util.Properties.get(String);

Parameters:
names - sequential list of names for which to search
defaultValue - to return if no properties are found
Returns:
value of named property or defaultValue if not existent

names

public java.util.Vector names(java.lang.String regexp)
                       throws gnu.regexp.REException
This returns a vector or properties names that match the given regular expression.

These results do not include parameters held by an applet. This is because of general lame design of Javasoft.

Note: calls grace.util.Properties.names(RE);


names

public java.util.Vector names(gnu.regexp.RE regexp)
This returns a vector or names that match the given regular expression.

These results do not include parameters held by an applet. This is because of general lame design of Javasoft.


subset

public Properties subset(java.lang.String regexp)
                  throws gnu.regexp.REException
Returns a subset of this Properties list narrowed by the given regular expression.

subset

public Properties subset(gnu.regexp.RE regexp)
Returns a subset of this Properties list narrowed by the given regular expression.

subset

public Properties subset(gnu.regexp.RE regexp,
                         java.lang.String nameSubstitution)
Returns a subset of this Properties list narrowed by the given regular expression but with the names substituted with the given nameSubstitution. This allows the caller to build a subset of this Properties list with names that are also narrowed. The nameSubstitution can contain regalar expression match sequences $0-$9.

For example, given a properties list of:


subset

public Properties subset(java.lang.String regexp,
                         java.lang.String nameSubstitution)
                  throws gnu.regexp.REException
See Also:
subset(RE, String)

names

public java.util.Enumeration names()
Allows interation over all of the names of properties held by this class. This doesn't include the applet parameters.

values

public java.util.Enumeration values()
Allows interation over all of the values of properties held by this class. This doesn't include the applet parameters.

setSystemProperties

public void setSystemProperties()
This sets the System properties to the set managed by this class. It keeps this set of properties segregated from System properties.

segregateFromSystemProperties

public void segregateFromSystemProperties()
If this set of properties is currently a view of the System properties, then a new interal property collection is created and the System properties are copied into the newly created collection. If this collection of properties is not mapped to the System properties, then this call does nothing.

integrateWithSystemProperties

public void integrateWithSystemProperties()
If this set of properties is currently not a view of the System properties, then the System properties are loaded into this (just to make sure it doesn't wipe out any System properties), and the System properties are set to this collection. If this collection of properties is already mapped to the System properties, then this call does nothing.

toString

public java.lang.String toString()
Formats all of the properties as a String. This doesn't include the applet parameters.
Overrides:
toString in class java.lang.Object

getJavaProperties

public java.util.Properties getJavaProperties()
Returns a list of the properties. This doesn't include the applet parameters.

set

public void set(java.util.Properties list)
Sets the list of the properties maintained by this class. This doesn't include the applet parameters.