com.ice.pref
Class UserPrefs

java.lang.Object
  |
  +--java.util.Dictionary
        |
        +--java.util.Hashtable
              |
              +--java.util.Properties
                    |
                    +--com.ice.pref.UserPrefs
All Implemented Interfaces:
java.lang.Cloneable, java.util.Map, java.io.Serializable

public class UserPrefs
extends java.util.Properties

This class implements the "global" properties functionality. It should be used in place of the System.getProperty() functionality. The class operates as an instance, meaning that an application may have more than one instance of properties. Each instance is identified by its name, and can be retrieved from the class by name. The class manges a table of instances of properties. This allows the programmer to track properties for different parts of their code, such as transient properties versus user configuration properties. If you do nothing, the class will create a single properties named "DEFAULT" to handle all properties, so you do not need to manage multiple instances.

Things the application must do to use this class:

Here is an example from a typical main():

		UserPrefs props = UserPrefs.getInstance();
		props.setPropertyPrefix( "com.ice.client." );

		// LOAD PROPERTIES
      FileInputStream pin = new FileInputStream( PROP_FILE_NAME );
		props.loadProperties( in );
		pin.close();
 

Properties are accessed via the getProperty() methods, which provide versions for String, int, double, and boolean values. Any property is looked for as follows:

  1. fullname.osname.username
  2. fullname.username
  3. fullname.osname
  4. fullname
Whichever property is found first is returned. The fullname consists of the property name prefixed by the application's property prefix. The username and osname suffixes are used to override general properties by os or by user. These suffixes are printed at startup to System.err. The osname suffix is the osname with spaces replaced by underscores. The username suffix is the user's name with spaces replaced by underscores.

If the property name starts with a period (.), then the prefix is not added to get the full name. If the property name ends with a period (.), then none of the suffixes are applied, and only the name is used to search for a property.

Thus, while the property name "mainWindow.x" would match a property definition named "prefix.mainWindow.x.user", the property ".mainWindow.x." would match a property with only that name and no prefix or suffix, and the property "mainWindow.x." would match "prefix.mainWindow.x" only and not allow for suffix overrides.

Author:
Tim Endres, time@ice.com.
See Also:
Serialized Form

Nested Class Summary
 class UserPrefs.Pair
           
 class UserPrefs.Tuple
           
 
Field Summary
protected  java.util.Hashtable subScribers
           
 
Fields inherited from class java.util.Properties
defaults
 
Constructor Summary
UserPrefs(java.lang.String name)
          Construct a UserPrefs named name with the System properties.
UserPrefs(java.lang.String nm, java.util.Properties defProps)
          This contructor, available to the user, requires the defaults.
 
Method Summary
 void addPropertyChangeListener(java.lang.String propName, java.beans.PropertyChangeListener pL)
           
 UserPrefs createWorkingCopy(java.lang.String nm)
           
 java.lang.String escapeString(java.lang.String propStr)
          Escape a property string.
protected  void firePropertyChange(java.lang.String propName, java.lang.String oldVal, java.lang.String newVal)
           
 java.lang.String getBaseName(java.lang.String propName)
          Given a property name with a prefix, such as 'com.ice.jcvs.tempDir', return the 'base name', which is the name with the prefix stripped off.
 boolean getBoolean(java.lang.String name, boolean defval)
          Retrieve a system boolean property.
 java.awt.Rectangle getBounds(java.lang.String name, java.awt.Rectangle defval)
          Retrieve a Rectangle property.
 java.awt.Color getColor(java.lang.String name, java.awt.Color defaultColor)
          Retrieve a Color property.
 java.lang.String getCurrentDirectory()
          Get the current working directory path via the System property 'user.dir'.
 java.lang.String getDelimiter()
           
 java.awt.Dimension getDimension(java.lang.String name, java.awt.Dimension defval)
          Retrieve a Dimension property.
 double getDouble(java.lang.String name, double defval)
          Retrieve a system double property.
 float getFloat(java.lang.String name, float defval)
          Retrieve a system float property.
 java.awt.Font getFont(java.lang.String name, java.awt.Font defaultFont)
          Retrieve a Font property.
static UserPrefs getInstance()
          Get the current properties instance.
static UserPrefs getInstance(java.lang.String name)
          Get the current properties instance.
 int getInteger(java.lang.String name, int defval)
          Retrieve a system integer property.
static java.lang.String getLineSeparator()
          Get the System line separator property.
 java.awt.Point getLocation(java.lang.String name, java.awt.Point defval)
          Retrieve a Location property.
 long getLong(java.lang.String name, long defval)
          Retrieve a system long property.
 java.lang.String getName()
           
 java.lang.String getOSSuffix()
           
 java.awt.Point getPoint(java.lang.String name, java.awt.Point defval)
          Retrieve a Point property.
 java.lang.String getProperty(java.lang.String name)
          Retrieve a system string property.
 java.lang.String getProperty(java.lang.String name, java.lang.String defval)
          Retrieve a system string property.
 java.lang.String getPropertyPrefix()
           
 java.lang.String[] getStringArray(java.lang.String name, java.lang.String[] defval)
          Retrieve a system string array property list.
 java.util.Vector getStringVector(java.lang.String name, java.util.Vector defval)
          Retrieve a system string Vector property list.
 java.lang.String[] getTokens(java.lang.String name, java.lang.String[] defval)
           
 PrefsTupleTable getTupleTable(java.lang.String name, PrefsTupleTable defval)
           
 java.lang.String getUserHome()
          Get the user's home directory path via the System property 'user.home'.
 java.lang.String getUserSuffix()
           
 boolean isModified(java.lang.String propName)
           
 void loadProperties(java.io.InputStream in)
          Load the properties from the given InputStream into this UserPrefs table using the Properties load() method.
 void loadProperties(java.util.Properties ap)
          Load the properties from the given Properties into this UserPrefs table.
static void main(java.lang.String[] args)
          Simple test program.
 java.lang.String normalizedPropertyName(java.lang.String name)
          Return a normalized version of a property name.
 java.lang.String prefixedPropertyName(java.lang.String name)
          Return a property name prefixed by the prefix that is set for this UserPrefs instance.
 void removeProperty(java.lang.String propName)
           
 void removePropertyChangeListener(java.lang.String propName, java.beans.PropertyChangeListener pL)
           
 void removeStringArray(java.lang.String propName)
           
 void removeTupleTable(java.lang.String propName)
           
 void setBoolean(java.lang.String name, boolean value)
          Set a boolean property.
 void setBounds(java.lang.String name, java.awt.Rectangle value)
          Set a Rectangle property.
 void setColor(java.lang.String name, java.awt.Color value)
          Set a Color property using the standard format ( see getColor() ).
 void setDebug(boolean debug)
           
 void setDelimiter(java.lang.String delim)
           
 void setDimension(java.lang.String name, java.awt.Dimension value)
          Set a Dimension property.
 void setDouble(java.lang.String name, double value)
          Set a double property.
 void setFloat(java.lang.String name, float value)
          Set a float property.
 void setFont(java.lang.String name, java.awt.Font value)
          Set a Font property using the standard format ( see getFont() ).
static void setInstance(UserPrefs inst)
          Set the current properties instance.
 void setInteger(java.lang.String name, int value)
          Set an int property.
static java.lang.String setLineSeparator(java.lang.String sep)
          Set the System line separator property.
 void setLocation(java.lang.String name, java.awt.Point value)
          Set a Location property.
 void setLong(java.lang.String name, long value)
          Set an int property.
 void setOSSuffix(java.lang.String suffix)
           
 void setPoint(java.lang.String name, java.awt.Point value)
          Set a Point property.
 java.lang.Object setProperty(java.lang.String name, java.lang.String value)
          Set a property value and fire property change event.
protected  java.lang.String setPropertyNoFire(java.lang.String name, java.lang.String value)
          Set a property value without firing a property change event.
 void setPropertyPrefix(java.lang.String prefix)
           
 void setStringArray(java.lang.String name, java.lang.String[] strings)
          Set a String array property.
 void setTokens(java.lang.String name, java.lang.String[] tokes)
          Set a Tokens property.
 void setTupleTable(java.lang.String name, PrefsTupleTable table)
          Set a TupleTable property.
 void setUserHome(java.lang.String newHome)
          Get the user's home directory path via the System property 'user.home'.
 void setUserSuffix(java.lang.String suffix)
           
static java.lang.String[] splitString(java.lang.String splitStr, java.lang.String delim)
          NOTE That we use the vectorString() method, since it will return an empty ending token if the property ends with the delimiter.
 void storeProperties(java.io.OutputStream out, java.lang.String header)
          Store the properties into the provided OutputStream using the Properties save() method.
 
Methods inherited from class java.util.Properties
list, list, load, propertyNames, save, store
 
Methods inherited from class java.util.Hashtable
clear, clone, contains, containsKey, containsValue, elements, entrySet, equals, get, hashCode, isEmpty, keys, keySet, put, putAll, rehash, remove, size, toString, values
 
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

subScribers

protected java.util.Hashtable subScribers
Constructor Detail

UserPrefs

public UserPrefs(java.lang.String name)
Construct a UserPrefs named name with the System properties.


UserPrefs

public UserPrefs(java.lang.String nm,
                 java.util.Properties defProps)
This contructor, available to the user, requires the defaults. Use this constructor if you wish to set the default properties.

Parameters:
defProps - The default properties.
Method Detail

getInstance

public static UserPrefs getInstance()
Get the current properties instance.


getInstance

public static UserPrefs getInstance(java.lang.String name)
Get the current properties instance.


setInstance

public static void setInstance(UserPrefs inst)
Set the current properties instance.


getLineSeparator

public static java.lang.String getLineSeparator()
Get the System line separator property.

Returns:
The line separator property.

setLineSeparator

public static java.lang.String setLineSeparator(java.lang.String sep)
Set the System line separator property. This setting will affect the idea of lines for Writers and other core classes that work with text lines.

Parameters:
sep - The line separator property.
Returns:
The previous line separator property.

createWorkingCopy

public UserPrefs createWorkingCopy(java.lang.String nm)

getName

public java.lang.String getName()

setDebug

public void setDebug(boolean debug)

setDelimiter

public void setDelimiter(java.lang.String delim)

getOSSuffix

public java.lang.String getOSSuffix()

setOSSuffix

public void setOSSuffix(java.lang.String suffix)

getUserSuffix

public java.lang.String getUserSuffix()

setUserSuffix

public void setUserSuffix(java.lang.String suffix)

setPropertyPrefix

public void setPropertyPrefix(java.lang.String prefix)

getDelimiter

public java.lang.String getDelimiter()

getPropertyPrefix

public java.lang.String getPropertyPrefix()

getCurrentDirectory

public java.lang.String getCurrentDirectory()
Get the current working directory path via the System property 'user.dir'.

Returns:
The user's home directory path.

getUserHome

public java.lang.String getUserHome()
Get the user's home directory path via the System property 'user.home'.

Returns:
The user's home directory path.

setUserHome

public void setUserHome(java.lang.String newHome)
Get the user's home directory path via the System property 'user.home'.

Returns:
The user's home directory path.

getBaseName

public java.lang.String getBaseName(java.lang.String propName)
Given a property name with a prefix, such as 'com.ice.jcvs.tempDir', return the 'base name', which is the name with the prefix stripped off. So, if the prefix was 'com.ice.jcvs', the previous name would return 'tempDir'.

Parameters:
propName - The property name to get the base of.
Returns:
The base name, or the original name if it does not start with the prefix.

prefixedPropertyName

public java.lang.String prefixedPropertyName(java.lang.String name)
Return a property name prefixed by the prefix that is set for this UserPrefs instance.

Parameters:
name - The name of the property to normalize.
Returns:
The normalized property name.

normalizedPropertyName

public java.lang.String normalizedPropertyName(java.lang.String name)
Return a normalized version of a property name. If the name starts with a '.', we strip off the leading '.' and return the remainder of the name. That allows the user to specify property names that should not be prefixed. If the name does not start with a '.', then we return the named prefixed by the set prefix.

Parameters:
name - The name of the property to normalize.
Returns:
The normalized property name.

getProperty

public java.lang.String getProperty(java.lang.String name)
Retrieve a system string property. Returns a null if the property is not defined.

Overrides:
getProperty in class java.util.Properties
Parameters:
name - The name of the property to retrieve.
Returns:
The string value of the named property.

getProperty

public java.lang.String getProperty(java.lang.String name,
                                    java.lang.String defval)
Retrieve a system string property. Returns a provided default value if the property is not defined.

Overrides:
getProperty in class java.util.Properties
Parameters:
name - The name of the property to retrieve.
defval - A default string value.
Returns:
The string value of the named property.

getInteger

public int getInteger(java.lang.String name,
                      int defval)
Retrieve a system integer property. Returns a provided default value if the property is not defined.

Parameters:
name - The name of the property to retrieve.
defval - A default integer value.
Returns:
The integer value of the named property.

getLong

public long getLong(java.lang.String name,
                    long defval)
Retrieve a system long property. Returns a provided default value if the property is not defined.

Parameters:
name - The name of the property to retrieve.
defval - A default integer value.
Returns:
The integer value of the named property.

getFloat

public float getFloat(java.lang.String name,
                      float defval)
Retrieve a system float property. Returns a provided default value if the property is not defined.

Parameters:
name - The name of the property to retrieve.
defval - A default float value.
Returns:
The float value of the named property.

getDouble

public double getDouble(java.lang.String name,
                        double defval)
Retrieve a system double property. Returns a provided default value if the property is not defined.

Parameters:
name - The name of the property to retrieve.
defval - A default double value.
Returns:
The double value of the named property.

getBoolean

public boolean getBoolean(java.lang.String name,
                          boolean defval)
Retrieve a system boolean property. Returns a provided default value if the property is not defined.

Parameters:
name - The name of the property to retrieve.
defval - A default boolean value.
Returns:
The boolean value of the named property.

getFont

public java.awt.Font getFont(java.lang.String name,
                             java.awt.Font defaultFont)
Retrieve a Font property. Fonts are represented with one of the standard representations: fontname-style-pointsize fontname-pointsize fontname-style fontname

Parameters:
name - The name of the property to retrieve.
Returns:
The Font identified by the named property.

getColor

public java.awt.Color getColor(java.lang.String name,
                               java.awt.Color defaultColor)
Retrieve a Color property. Colors are represented by an integer property.

Parameters:
name - The name of the property to retrieve.
Returns:
The Color value of the named property.

getPoint

public java.awt.Point getPoint(java.lang.String name,
                               java.awt.Point defval)
Retrieve a Point property. Points are represented with a delimiter seperated string in the order x, y.

Parameters:
name - The name of the property to retrieve.
defval - A default value.
Returns:
The Point value of the named property.

getLocation

public java.awt.Point getLocation(java.lang.String name,
                                  java.awt.Point defval)
Retrieve a Location property. This is simply a cover for getPoint().

Parameters:
name - The name of the property to retrieve.
defval - A default value.
Returns:
The Point value of the named property.

getDimension

public java.awt.Dimension getDimension(java.lang.String name,
                                       java.awt.Dimension defval)
Retrieve a Dimension property. Points are represented with a delimiter seperated string in the order width, height.

Parameters:
name - The name of the property to retrieve.
defval - A default value.
Returns:
The Dimension value of the named property.

getBounds

public java.awt.Rectangle getBounds(java.lang.String name,
                                    java.awt.Rectangle defval)
Retrieve a Rectangle property. Rectangles are represented with a delimiter seperated string in the order x, y, w, h.

Parameters:
name - The name of the property to retrieve.
defval - A default value.
Returns:
The Rectangle value of the named property.

getStringArray

public java.lang.String[] getStringArray(java.lang.String name,
                                         java.lang.String[] defval)
Retrieve a system string array property list. String arrays are represented by colon separated strings. Returns a provided default value if the property is not defined.

Parameters:
name - The name of the property to retrieve.
defval - A default boolean value.
Returns:
The string array value of the named property.

getStringVector

public java.util.Vector getStringVector(java.lang.String name,
                                        java.util.Vector defval)
Retrieve a system string Vector property list. String vectors are represented by colon separated strings. Returns a provided default value if the property is not defined.

Parameters:
name - The name of the property to retrieve.
defval - A default boolean value.
Returns:
The Vector of strings of the named property.

getTokens

public java.lang.String[] getTokens(java.lang.String name,
                                    java.lang.String[] defval)

splitString

public static java.lang.String[] splitString(java.lang.String splitStr,
                                             java.lang.String delim)
NOTE That we use the vectorString() method, since it will return an empty ending token if the property ends with the delimiter. Currently, splitString() does not do this.


getTupleTable

public PrefsTupleTable getTupleTable(java.lang.String name,
                                     PrefsTupleTable defval)

isModified

public boolean isModified(java.lang.String propName)

escapeString

public java.lang.String escapeString(java.lang.String propStr)
Escape a property string. This will replace every occurence of the delim character with "'\' + this.delim".

Returns:
The replaced value of the property if it exists.

addPropertyChangeListener

public void addPropertyChangeListener(java.lang.String propName,
                                      java.beans.PropertyChangeListener pL)

removePropertyChangeListener

public void removePropertyChangeListener(java.lang.String propName,
                                         java.beans.PropertyChangeListener pL)

firePropertyChange

protected void firePropertyChange(java.lang.String propName,
                                  java.lang.String oldVal,
                                  java.lang.String newVal)

setPropertyNoFire

protected java.lang.String setPropertyNoFire(java.lang.String name,
                                             java.lang.String value)
Set a property value without firing a property change event.

Parameters:
name - The name of the property to retrieve.
value - The property's value.
Returns:
The replaced value of the property if it exists.

setProperty

public java.lang.Object setProperty(java.lang.String name,
                                    java.lang.String value)
Set a property value and fire property change event.

Overrides:
setProperty in class java.util.Properties
Parameters:
name - The name of the property to retrieve.
value - The property's value.
Returns:
The replaced value of the property if it exists.

setInteger

public void setInteger(java.lang.String name,
                       int value)
Set an int property.

Parameters:
name - The name of the property to set.
value - The property's value.

setLong

public void setLong(java.lang.String name,
                    long value)
Set an int property.

Parameters:
name - The name of the property to set.
value - The property's value.

setFloat

public void setFloat(java.lang.String name,
                     float value)
Set a float property.

Parameters:
name - The name of the property to set.
value - The property's value.

setDouble

public void setDouble(java.lang.String name,
                      double value)
Set a double property.

Parameters:
name - The name of the property to set.
value - The property's value.

setBoolean

public void setBoolean(java.lang.String name,
                       boolean value)
Set a boolean property.

Parameters:
name - The name of the property to set.
value - The property's value.

setPoint

public void setPoint(java.lang.String name,
                     java.awt.Point value)
Set a Point property.

Parameters:
name - The name of the property to set.
value - The property's value.

setLocation

public void setLocation(java.lang.String name,
                        java.awt.Point value)
Set a Location property. This is simply a cover for setPoint().

Parameters:
name - The name of the property to set.
value - The property's value.

setDimension

public void setDimension(java.lang.String name,
                         java.awt.Dimension value)
Set a Dimension property.

Parameters:
name - The name of the property to set.
value - The property's value.

setBounds

public void setBounds(java.lang.String name,
                      java.awt.Rectangle value)
Set a Rectangle property.

Parameters:
name - The name of the property to set.
value - The property's value.

setFont

public void setFont(java.lang.String name,
                    java.awt.Font value)
Set a Font property using the standard format ( see getFont() ).

Parameters:
name - The name of the property to set.
value - The property's value.

setColor

public void setColor(java.lang.String name,
                     java.awt.Color value)
Set a Color property using the standard format ( see getColor() ).

Parameters:
name - The name of the property to set.
value - The property's value.

setStringArray

public void setStringArray(java.lang.String name,
                           java.lang.String[] strings)
Set a String array property. Each string is stored as a separate property.

Parameters:
name - The name of the property to set.

setTokens

public void setTokens(java.lang.String name,
                      java.lang.String[] tokes)
Set a Tokens property. Tokens are short string values that are stored as a single property with the tokens separated by the delim.

Parameters:
name - The name of the property to set.

setTupleTable

public void setTupleTable(java.lang.String name,
                          PrefsTupleTable table)
Set a TupleTable property. Tuple tables are stored as a string matrix where every cell of that matrix is a property string named using the matrix indices.
 Thus, the table:

 key.0 val.0.0 val.0.1 val.0.2
 key.1 val.1.0 val.1.1 val.1.2
 key.2 val.2.0 val.2.1 val.2.2

 would be stored as properties in this fashion:

 propName.0.key=key.0
 propName.0.0=val.0.0
 propName.0.1=val.0.1
 propName.0.2=val.0.2
 propName.1.key=key.1
 propName.1.0=val.1.0
 propName.1.1=val.1.1
 propName.1.2=val.1.2
 propName.2.key=key.2
 propName.2.0=val.2.0
 propName.2.1=val.2.1
 propName.2.2=val.2.2

 
This design allows the property code to simply use a for loop incrementing the indices until a property returns null indicating the end of tuple values or the end of table (when a ".key" property returns null).

Parameters:
name - The name of the property to set.

removeProperty

public void removeProperty(java.lang.String propName)

removeStringArray

public void removeStringArray(java.lang.String propName)

removeTupleTable

public void removeTupleTable(java.lang.String propName)

loadProperties

public void loadProperties(java.util.Properties ap)
Load the properties from the given Properties into this UserPrefs table.


loadProperties

public void loadProperties(java.io.InputStream in)
                    throws java.io.IOException
Load the properties from the given InputStream into this UserPrefs table using the Properties load() method.

java.io.IOException

storeProperties

public void storeProperties(java.io.OutputStream out,
                            java.lang.String header)
                     throws java.io.IOException
Store the properties into the provided OutputStream using the Properties save() method.

java.io.IOException

main

public static void main(java.lang.String[] args)
Simple test program. Run with no arguments. This code could be much more robust.



Copyright © 1997-2003, Timothy G. Endres, All Rights Reserved.