wt.util
Class WTProperties

java.lang.Object
  java.util.Dictionary<K,V>
      java.util.Hashtable<Object,Object>
          java.util.Properties
              wt.util.WTProperties

All Implemented Interfaces:

Serializable, Cloneable, Map<Object,Object>

public class WTProperties
extends Properties

Windchill configuration properties.

This is a convenience class providing static access to the following property sources:

System Properties

Properties supplied by the Java runtime system.

Configuration File

Properties loaded from a resource file named wt.properties. This is loaded just like a class file, and therefore it represents the properties associated with the software installation from which classes are being loaded. The file is loaded as a class resource of the WTProperties class. If the WTProperties class is loaded from the local class path, then this file will be loaded from the local class path. If the WTProperties class is loaded remotely, then this file may be loaded from either the local class path or remotely.

Application Arguments

Command line arguments to a Java application. The argument strings are parsed and any of the form name=value are made available as properties.

Server's Configuration File

Properties loaded from the server's properites file. These properties are loaded via a URL connection to wt.properties relative to the server's codebase URL. For applets, the codebase is the applet's codebase unless an applet parameter named wt.server.codebase indicates otherwise. For applications, it is the wt.server.codebase property as defined by any of the previous property sources.

Applet Parameters

Parameters of the current applet.

Access is provided at three levels with each level inheriting the lower levels as default values.

getLocalProperties ()

Properties defined by the application arguments, configuration file, and system properties. These properties are global to the Java Virtual Machine and the Java class files that are loaded.This level should be used for properties accessed by static class initializers.

getServerProperties

Properties defined in the server's configuration file. This interface is intended to allow a client to view the properties being used by the server, however, this object will only reflect the server's configuration file, not any additional system properties and command line parameters that may have been used.

getAppletProperties

The highest level where all properties defined in the above sources are visible, including applet parameters. Note, however, that applet parameters will not appear in enumerations of the properties since the list of available parameters is not exposed by the Applet class.

In all cases, the properties objects returned support a form of macro substitution in the property values so that values can be constructed from other property values. Values are parsed for expressions of the form $(name) and the value of the property name is substituted into the resulting property value. The expression $DATE(format) is a builtin SimpleDateFormat macro where format is a pattern expression such as MMddyy. It can be used to construct date/time based values such as log file names. The expression $LIB(key) is a builtin macro which lists the contents of the directory pointed at by key separated by File.pathSeparator.

The methods for accessing properties are static, making it very convenient for classes to access properties without the benefit of any other context. However, the server and applet properties are not static relative to this class. If this class was loaded from the local class path, it may be shared by multiple applets that may be communicating with multiple servers. Therefore, a simple convention is used to correctly associate the calling thread to the appropriate server and applet properties. This class uses the WTContext class to map the calling thread to appropriate server and applet properties objects. It is important that applications and applets call the WTContext.init method at startup. Applets should also call the destroy method when they are destoyed to remove this mapping and allow the timely garbage collection of the Applet object.

Example application main:

 public static void main (String args)
 {
    // Initialize WTContext with command line arguments
    WTContext.init(args);
 
    // Replace system properties with WTProperties
    Properties props = WTProperties.getLocalProperties();
    System.setProperties(props);
 
    // Get our wt.foo.bar property
    String bar = props.getProperty("wt.foo.bar");
    ...
 }
 

Example applet init:

public void init ()
 {
    // Initialize WTContext for this applet
    WTContext.init(this);
 
    // Get the wt.foo.bar property from applet parameters, server 
    // configuration properties, local configuration properties,
    // or system properties.
    Properties props = WTProperties.getAppletProperties();
    String bar = props.getProperty("wt.foo.bar");
    ...
 }
 
 public void destroy ()
 {
    // Destroy WTContext for this applet
    WTContext.getContext().destroy(this);
 }
 

Supported API: true
Extendable: false

See Also:

WTContext, Serialized Form

Constructor Summary

WTProperties(Properties defaults)
Construct a new WTProperties object.

Method Summary

static WTProperties	getAppletProperties() Get a properties object for the current thread that includes applet parameters (if any), server configuration file properties, and local properties.
static WTProperties	getLocalProperties() Get a properties object that includes application arguments, properties from the resource file wt.properties in the local codebase, and Java system properties.
String	getProperty(String key) Searches for the property with the specified key in this property list.
boolean	getProperty(String key, boolean default_value) Convenience method to get a boolean property string and convert it to a boolean value.
int	getProperty(String key, int default_value) Convenience method to get an integer property string and convert it to an int value.
static URL	getServerCodebase() Convenience method to retrieve server codebase URL for the current thread.
static URL	getServerCodebase(Applet applet, Properties props) Get server codebase URL as determined from applet codebase or property value.
static WTProperties	getServerProperties() Get a properties object for the current thread that includes properties from the server's wt.properties configuration file in addition to local properties.
static WTProperties	getServerProperties(URL codebase) Get a properties object for the given server codebase that includes server configuration file properties and local properties.
URL	getURL() Gets the URL from which the corresponding local or server properties where loaded.
void	list(String prefix, PrintStream out) Prints this property list out to the specified output stream.
static void	main(String[] args) Simple tester.
void	parseArgs(String[] args) Parse name=value pairs from a string array into this properties object.
static void	reset() Reset the WTProperties class to its initial state.
static void	setLocalPropertiesOnly(boolean local_only) Sets to allow only local properties to be loaded.
static void	setVerbose(boolean verbose) Set verbose mode for debugging.
String	substitute(String str) Substitutes expressions of the form $(name) in strings with property values from this properties object.

Methods inherited from class java.util.Properties

getProperty, list, list, load, loadFromXML, save, store, storeToXML, storeToXML

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

Constructor Detail

WTProperties

public WTProperties(Properties defaults)

Construct a new WTProperties object. Normally, references to the standard properties objects are returned by static methods of this class. This constructor exists for applications that wish to load their own private properties files and take advantage of the extra utility functions or macro substitution.

Supported API: true

Method Detail

getLocalProperties

public static WTProperties getLocalProperties()
                                       throws IOException

Get a properties object that includes application arguments, properties from the resource file wt.properties in the local codebase, and Java system properties.

Supported API: true

Returns:

the local WTProperties object

Throws:

IOException

getServerProperties

public static WTProperties getServerProperties()
                                        throws IOException

Get a properties object for the current thread that includes properties from the server's wt.properties configuration file in addition to local properties.

Supported API: true

Returns:

a server WTProperties object

Throws:

IOException

getServerProperties

public static WTProperties getServerProperties(URL codebase)
                                        throws IOException

Get a properties object for the given server codebase that includes server configuration file properties and local properties. If the codebase argument is null, the properties for the default server are returned.

Supported API: true

Parameters:

codebase - the server codebase to load properties from

Returns:

a server WTProperties object

Throws:

IOException

getServerCodebase

public static URL getServerCodebase()
                             throws IOException

Convenience method to retrieve server codebase URL for the current thread. If called from an applet context, it will be the applet's codebase unless overridden by an applet parameter named wt.server.codebase. If called from an application, it will return the URL for the local wt.server.codebase property.

Supported API: true

Returns:

the codebase URL

Throws:

IOException

getServerCodebase

public static URL getServerCodebase(Applet applet,
                                    Properties props)
                             throws IOException

Get server codebase URL as determined from applet codebase or property value. If the specified applet is non-null, it will be the applet's codebase unless overridden by an applet parameter named wt.server.codebase. If the codebase is not available from the applet, it will return the URL for the wt.server.codebase property in the given property object. If wt.server.codebase is not specified, but wt.server.codebase.locator is specified, the given URL will be opened and used to read the server codebase URL as the first line of the response body.

Supported API: true

Parameters:

applet - the Applet object

props - the Properties object

Returns:

the codebase URL

Throws:

IOException

getAppletProperties

public static WTProperties getAppletProperties()
                                        throws IOException

Get a properties object for the current thread that includes applet parameters (if any), server configuration file properties, and local properties.

Supported API: true

Returns:

a applet WTProperties object

Throws:

IOException

getURL

public URL getURL()

Gets the URL from which the corresponding local or server properties where loaded. If no properties file was found for this WTProperties object, null is returned.

Supported API: true

Returns:

the URL used to load this WTProperties object

reset

public static void reset()
                  throws IOException

Reset the WTProperties class to its initial state. This discards any current property objects, causing reloading when they are next accessed. It is used to force reloading of property values from their original sources.

If the local properties object was set as the system property object, it is reloaded immediately and set to be the system property object again.

This method may be necessary to build very long lived applets or applications that need to recover from exceptions due to property changes that take place during their lifetimes. For example, a long lived client that needs to recover even if its server host or port number is changed while it is active.

Note that resetting the WTProperties will not affect static class initialization performed in existing classes. Often, classes will use local properties to initialize static final values that cannot be reset later.

Supported API: true

Throws:

IOException

setLocalPropertiesOnly

public static void setLocalPropertiesOnly(boolean local_only)

Sets to allow only local properties to be loaded. This forces the local properties to be used as the server properties. This can be called during initialization of applications that want to limit themselves to properties found in the local class path.

Classes that load and execute in both client and server processes may request the server properties. Server applications can use this method to bypass attempts to load server properties which will ultimately be identical to the local properties already loaded.

Supported API: true

Parameters:

local_only - the setting.

parseArgs

public void parseArgs(String[] args)

Parse name=value pairs from a string array into this properties object. If a string does not contain a name=value string, it is skipped. This method can be used to add command line arguments to the properties object.

Supported API: true

Parameters:

args - string array

getProperty

public String getProperty(String key)

Searches for the property with the specified key in this property list. If the key is not found in this property list, the default property list, and its defaults, recursively, are then checked. The method returns null if the property is not found. Expresions of the form $(name) are substituted with the value of the named property if it is found, otherwise they are replaced by an empty string. If the entire value is a substitution and the named property does not exist, null is returned instead. Substitution is only performed for properties contained in this object. Properties found in the default property list are returned unchanged. The expression $DATE(format) is a builtin SimpleDateFormat macro where format is a pattern expression such as MMddyy. It can be used to construct date/time based values such as log file names. The expression $LIB(key) is a builtin macro which lists the contents of the directory pointed at by key separated by File.pathSeparator. Once a substitution has been performed, the substituted value is cached and will continue to be returned for consistency.

Supported API: true

Overrides:

getProperty in class Properties

Parameters:

key - the property key.

Returns:

the value in this property list with the specified key value.

getProperty

public int getProperty(String key,
                       int default_value)

Convenience method to get an integer property string and convert it to an int value.

Supported API: true

Parameters:

key - the property key.

default - value returned if named property does not exist

Returns:

the value as an int.

getProperty

public boolean getProperty(String key,
                           boolean default_value)

Convenience method to get a boolean property string and convert it to a boolean value.

Supported API: true

Parameters:

key - the property key.

default - value returned if named property does not exist

Returns:

the value as a boolean.

substitute

public String substitute(String str)

Substitutes expressions of the form $(name) in strings with property values from this properties object. If the entire value is a substitution and the named property is not found, null is returned instead of an empty string. The expression $DATE(format) is a builtin SimpleDateFormat macro where format is a pattern expression such as MMddyy. It can be used to construct date/time based values such as log file names. The expression $LIB(key) is a builtin macro which lists the contents of the directory pointed at by key separated by File.pathSeparator.

This is used internally to the WTProperties.getProperty method. It is exposed as a public method to allow the same substitutions to be applied against arbitrary strings.

Supported API: true

Parameters:

str - the string to be parsed for substitutions

Returns:

the substituted string

setVerbose

public static void setVerbose(boolean verbose)

Set verbose mode for debugging. When true, this class will display where properties are being loaded from.

Supported API: true

Parameters:

verbose - the verbose setting

list

public void list(String prefix,
                 PrintStream out)

Prints this property list out to the specified output stream. This method is useful for debugging.

Supported API: true

Parameters:

prefix - Optional prefix filter for property names

out - a print stream

main

public static void main(String[] args)
                 throws IOException

Simple tester. Prints local and server properties lists. If an argument is specified, it is used as a prefix filter on the keys.

Supported API: true

Throws:

IOException