com.ice.util
Class UserProperties

java.lang.Object
  |
  +--com.ice.util.UserProperties

public abstract class UserProperties
extends java.lang.Object

The UserProperties class. This class is used to extend the concept of System.getProperty(). This class adds the following features:

Here is how it works. We have six levels of properties which are loaded based on various settings. The levels look like this:

  1. Hardwired defaults.
  2. Application defined defaults.
  3. Defaults resource.
  4. System level resource list.
  5. Application property file.
  6. Application resource list.

Resource lists are colon (:) separated strings listing resource names to be loaded into the properties.

In a typical deployment, the developer will place the defaults resource in the JAR file containing the application's classes. This file will then define the application properties file, which will usually be left empty allowing the user to place all customizations in this local file. For distributed applications, system resources will typically be supplied via simple web pages, which allows for automatic updates of many properties. The application resource list is then typically reserved for specific user customizations, or for distributed customizations, or updates.

Typically, the System Resource List is defined in the Defaults Resource. However, it can also be defined by the application defaults, or can be hardwired into the code if desired. Further, the Application Resource List is typically defined by the Application Property File, although it can be defined in any of the previous loaded resources.

Also note that the application prefix can be set at any point up to and including the defaults resource. After the defaults resource is loaded, the prefix property is consulted, and if set, is used as the new application prefix. The prefix property is named by adding together the application's package name and the string 'propertyPrefix'. Thus, the prefix property for 'com.ice.jcvs' would be named 'com.ice.jcvs.propertyPrefix', and would typically be set in the defaults resource.

Things the application must do to use this class:

Here is an example from a typical main():

		UserProperties.setPropertyPrefix( "WebTool." );

		UserProperties.setDefaultsResource
			( "/com/ice/webtool/defaults.txt" );

		// PROCESS PROPERTIES OPTIONS
		// The returned args are those not processed.
		args = UserProperties.processOptions( args );

		// Now app should process remaining arguments...

		// LOAD PROPERTIES 
		UserProperties.loadProperties( "com.ice.webtool", null );
 

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.

The following parameters are understood by processOptions():

Version:
$Revision: 1.10 $
Author:
Tim Endres, time@ice.com.

Constructor Summary
UserProperties()
           
 
Method Summary
static void addDefaultProperties(java.util.Properties props, java.util.Properties defaultProps)
           
static void defaultProperties(java.util.Properties props)
          Establishes critical default properties.
static int getClassConstant(java.lang.String name, int defval)
          Retrieve a system Class constant property.
static java.awt.Color getColor(java.lang.String name, java.awt.Color defaultColor)
           
static java.awt.Font getFont(java.lang.String name, java.awt.Font defaultFont)
           
static java.lang.String getLineSeparator()
           
static java.lang.String getOSName()
           
static boolean getProperty(java.lang.String name, boolean defval)
          Retrieve a system boolean property.
static double getProperty(java.lang.String name, double defval)
          Retrieve a system double property.
static int getProperty(java.lang.String name, int defval)
          Retrieve a system integer property.
static long getProperty(java.lang.String name, long defval)
          Retrieve a system long property.
static java.lang.String getProperty(java.lang.String name, java.lang.String defval)
          Retrieve a system string property.
static java.lang.String getPropertyPrefix()
           
static java.lang.String[] getStringArray(java.lang.String name, java.lang.String[] defval)
          Retrieve a system string array property list.
static java.util.Vector getStringVector(java.lang.String name, java.util.Vector defval)
           
static java.lang.String getUserHome()
           
static java.lang.String getUserName()
           
static void includeProperties(java.util.Properties into, java.util.Properties from)
           
static void loadProperties(java.lang.String packageName, java.util.Properties appProps)
          Load all related properties for this application.
static java.lang.String normalizePropertyName(java.lang.String name)
           
static java.lang.String prefixedPropertyName(java.lang.String name)
           
static void printContext(java.io.PrintStream out)
           
static void printUsage(java.io.PrintStream out)
           
static java.lang.String[] processOptions(java.lang.String[] args)
           
static void registerDynamicProperties(java.lang.String name, java.lang.String path, java.util.Properties props)
           
static void removeDynamicProperty(java.lang.String name, java.lang.String propName)
          This method removes a property from the dynamic properties.
static void saveDynamicProperties(java.lang.String name)
           
static void setDebug(boolean debug)
           
static void setDefaultsResource(java.lang.String rsrcName)
           
static void setDynamicProperties(java.lang.String name, java.util.Properties props)
           
static void setDynamicProperty(java.lang.String name, java.lang.String propName, java.lang.String propValue)
          This method expects the property keys to be not normalized, meaning that they are the full property name with the prefix added on.
static void setLocalPropertyFile(java.lang.String fileName)
           
static void setOSSuffix(java.lang.String suffix)
           
static void setPropertyPrefix(java.lang.String prefix)
           
static void setUserSuffix(java.lang.String suffix)
           
static void setVerbose(boolean verbose)
           
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

UserProperties

public UserProperties()
Method Detail

getOSName

public static java.lang.String getOSName()

getUserHome

public static java.lang.String getUserHome()

getUserName

public static java.lang.String getUserName()

setDebug

public static void setDebug(boolean debug)

setVerbose

public static void setVerbose(boolean verbose)

setLocalPropertyFile

public static void setLocalPropertyFile(java.lang.String fileName)

setDefaultsResource

public static void setDefaultsResource(java.lang.String rsrcName)

setOSSuffix

public static void setOSSuffix(java.lang.String suffix)

setUserSuffix

public static void setUserSuffix(java.lang.String suffix)

setPropertyPrefix

public static void setPropertyPrefix(java.lang.String prefix)

getPropertyPrefix

public static java.lang.String getPropertyPrefix()

getLineSeparator

public static java.lang.String getLineSeparator()

getFont

public static java.awt.Font getFont(java.lang.String name,
                                    java.awt.Font defaultFont)

getColor

public static java.awt.Color getColor(java.lang.String name,
                                      java.awt.Color defaultColor)

prefixedPropertyName

public static java.lang.String prefixedPropertyName(java.lang.String name)

normalizePropertyName

public static java.lang.String normalizePropertyName(java.lang.String name)

getProperty

public static 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.

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

getProperty

public static int getProperty(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.

getProperty

public static long getProperty(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.

getProperty

public static double getProperty(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.

getProperty

public static boolean getProperty(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.

getStringArray

public static 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 static java.util.Vector getStringVector(java.lang.String name,
                                               java.util.Vector defval)

getClassConstant

public static int getClassConstant(java.lang.String name,
                                   int defval)
Retrieve a system Class constant property.

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

defaultProperties

public static void defaultProperties(java.util.Properties props)
Establishes critical default properties.

Parameters:
props - The system properties to add properties into.

includeProperties

public static void includeProperties(java.util.Properties into,
                                     java.util.Properties from)

addDefaultProperties

public static void addDefaultProperties(java.util.Properties props,
                                        java.util.Properties defaultProps)

loadProperties

public static void loadProperties(java.lang.String packageName,
                                  java.util.Properties appProps)
Load all related properties for this application. This class method will look for a global properties file, loading it if found, then looks for a local properties file and loads that.


registerDynamicProperties

public static void registerDynamicProperties(java.lang.String name,
                                             java.lang.String path,
                                             java.util.Properties props)

setDynamicProperties

public static void setDynamicProperties(java.lang.String name,
                                        java.util.Properties props)

setDynamicProperty

public static void setDynamicProperty(java.lang.String name,
                                      java.lang.String propName,
                                      java.lang.String propValue)
This method expects the property keys to be not normalized, meaning that they are the full property name with the prefix added on.


removeDynamicProperty

public static void removeDynamicProperty(java.lang.String name,
                                         java.lang.String propName)
This method removes a property from the dynamic properties.


saveDynamicProperties

public static void saveDynamicProperties(java.lang.String name)
                                  throws java.io.IOException
java.io.IOException

printContext

public static void printContext(java.io.PrintStream out)

printUsage

public static void printUsage(java.io.PrintStream out)

processOptions

public static java.lang.String[] processOptions(java.lang.String[] args)


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