Java Doc for UserProperties.java in  » Source-Control » jcvsweb » com » ice » util » Java Source Code / Java DocumentationJava Source Code and Java Documentation

• A hierarchical property definition structure.
• Typed property retrieval with default values.
• Hierarchical overrides allowings properties to be overridden on a per user or per host or per host and user basis.
• The ability to load from any valid resource, including files stored in JAR files, files located via the file system, which includes networked file systems, as well as any other resource that can be identified via a URL, including web pages, FTP-ed files, and more.

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:

• Set the property prefix via UserProperties.setPropertyPrefix()
• Set the defaults resource via UserProperties.setDefaultsResource()
• Process any arguments via UserProperties.processOptions()
• Load all properties.

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

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():

• -propPrefix prefix -- sets the property prefix.
• -propFile filename -- sets the application property file.
• -propDefaults resource -- sets the defaults resource name.
• -propDebug -- turns on debugging of property handling.
• -propVerbose -- turns on verbosity.
• -propOS osname -- set the property os suffix.
• -propUser username -- set the property user name suffix.