wt.util
Class WTProperties

java.lang.Object
  java.util.Dictionary
      java.util.Hashtable
          java.util.Properties
              wt.util.WTProperties

All Implemented Interfaces:

Cloneable, Map, Serializable

Direct Known Subclasses:

DBProperties, DSProperties, ExportProperties, FvProperties, ImportProperties, MasterProperties, MeetingCenterProperties, NestedProperties, NMImportProperties, ReplicaProperties, ReplicationProperties, SchedulerProperties

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

Nested Class Summary

Nested classes inherited from class java.util.Hashtable

Field Summary

private boolean	applet
private WTProperties	appletProperties
private static String	CLASSNAME
private static Hashtable	codebaseMap
private Properties	defaults
private Object	key
private static Hashtable	keyMap
private static String	LINE_SEPARATOR
private static boolean	localPropertiesOnly
private static WTProperties	localProps
private static URL	localPropsURL
private static Object	lock
private static ClassLoader	propClassLoader
private static String	RESOURCE
static String	RESOURCE_NAME Name of the properties resource file.
static String	SERVER_CODEBASE_LOCATOR Server codebase locator property name
static String	SERVER_CODEBASE_PROPERTY Server codebase property name
private static Object	serverPropertiesKey
private URL	url
private Hashtable	valueCache
private static boolean	verbose
private static Object	writeLock

Fields inherited from class java.util.Properties

Fields inherited from class java.util.Hashtable

Constructor Summary

private	WTProperties() Private constructor to allow for empty WTProperties creation.
	WTProperties(Properties defaults) Construct a new WTProperties object.

Method Summary

private void	appendPropertiesToFile(WTProperties prop, String header, String filepath) This will open the specified wt.properties file and append a key/value pair to the end of the file.
void	appendPropertyToFile(String key, String value, String header) This will open the current wt.properties file and append a key/value pair to the end of the file.
void	appendPropertyToFile(String key, String value, String header, String filepath) This will open the current wt.properties file and append a key/value pair to the end of the file.
protected static void	copyFile(String file1, String file2, boolean override) Will copy a file to another.
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.
private WTProperties	keepOnlyPropertyChanges(BufferedReader in) This method will return a Properties object of ONLY the values that are NOT in the properties object.
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.
Enumeration	propertyNames() Returns an enumeration of all the keys in this property list, including the keys in the default property list.
private static String	readCodebaseFromLocator(URL url)
private String	removeDoubleSlash(String text) Method used to remove double slashes from properties that are being read by the parser above.
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.
void	store() This will store the wt.properties file according the the location which is set in the wt.codebase.location value.
void	store(String filename) Will store the current preferences to a filename with a header stating the properties are coming from WTProperties and a time stamp in the Server Locale.
void	store(String filename, String header) This method will store the Properties into the filename specified along with a header outlining the new properties.
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, save, setProperty, 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

RESOURCE

private static final String RESOURCE

See Also:

Constant Field Values

CLASSNAME

private static final String CLASSNAME

RESOURCE_NAME

public static final String RESOURCE_NAME

Name of the properties resource file.

See Also:

Constant Field Values

verbose

private static boolean verbose

SERVER_CODEBASE_PROPERTY

public static final String SERVER_CODEBASE_PROPERTY

Server codebase property name

See Also:

Constant Field Values

SERVER_CODEBASE_LOCATOR

public static final String SERVER_CODEBASE_LOCATOR

Server codebase locator property name

See Also:

Constant Field Values

localProps

private static WTProperties localProps

localPropsURL

private static URL localPropsURL

serverPropertiesKey

private static final Object serverPropertiesKey

codebaseMap

private static Hashtable codebaseMap

keyMap

private static Hashtable keyMap

lock

private static Object lock

localPropertiesOnly

private static boolean localPropertiesOnly

LINE_SEPARATOR

private static String LINE_SEPARATOR

key

private Object key

propClassLoader

private static ClassLoader propClassLoader

defaults

private Properties defaults

applet

private boolean applet

appletProperties

private WTProperties appletProperties

url

private URL url

valueCache

private Hashtable valueCache

writeLock

private static Object writeLock

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

WTProperties

private WTProperties()

Private constructor to allow for empty WTProperties creation.

Method Detail

keepOnlyPropertyChanges

private WTProperties keepOnlyPropertyChanges(BufferedReader in)
                                      throws IOException

This method will return a Properties object of ONLY the values that are NOT in the properties object.

Supported API: false

Parameters:

in - The reader to the properties stream

Returns:

A WTProperties object which contains just the key/value pairs that are different than the backing store.

Throws:

IOException

removeDoubleSlash

private String removeDoubleSlash(String text)

Method used to remove double slashes from properties that are being read by the parser above.

Supported API: false

Parameters:

text - The text to remove the slashes from

Returns:

The text without the multiple slashes,

store

public void store()
           throws IOException

This will store the wt.properties file according the the location which is set in the wt.codebase.location value. If the path is not valid, and exception is thrown.

Supported API: false

Throws:

IOException - If there is an error trying to locate wt.properties Or there is an error writing to wt.properties. In order to find wt.properties, the property wt.home must be set.

store

public void store(String filename)
           throws IOException

Will store the current preferences to a filename with a header stating the properties are coming from WTProperties and a time stamp in the Server Locale.

Supported API: false

Parameters:

filename - The filename of the file to update.

Throws:

IOException

store

public void store(String filename,
                  String header)
           throws IOException

This method will store the Properties into the filename specified along with a header outlining the new properties.

NOTE: This should only be called from the server or server side processes.

Supported API: false

Parameters:

filename - The filename to update

header - The header to write to the file.

Throws:

IOException

copyFile

protected static void copyFile(String file1,
                               String file2,
                               boolean override)
                        throws IOException

Will copy a file to another. If the override is false then if the second file exists, the copy will not proceed and an exception will be thrown.

Supported API: false

Parameters:

file1 - The first file

file2 - The second file

override - Whether to override and attempt a forced copy.

Throws:

IOException

appendPropertyToFile

public void appendPropertyToFile(String key,
                                 String value,
                                 String header)
                          throws IOException

This will open the current wt.properties file and append a key/value pair to the end of the file. The '\' will be escaped to be '\\' which is part of the properties file format.

Supported API: false

Parameters:

key - The key to append

value - The value to append

header - The header of who is editing the file.

Throws:

IOException - if the file could not be found or opened

appendPropertyToFile

public void appendPropertyToFile(String key,
                                 String value,
                                 String header,
                                 String filepath)
                          throws IOException

This will open the current wt.properties file and append a key/value pair to the end of the file. The '\' will be escaped to be '\\' which is part of the properties file format.

Supported API: false

Parameters:

key - The key to append

value - The value to append

filepath - The file to append to.

Throws:

IOException - if the file could not be found or opened

appendPropertiesToFile

private void appendPropertiesToFile(WTProperties prop,
                                    String header,
                                    String filepath)
                             throws IOException

This will open the specified wt.properties file and append a key/value pair to the end of the file. The '\' will be escaped to be '\\' which is part of the properties file format.

Supported API: false

Parameters:

prop - The properties map of properties to add to the file.

header - The header to append to the file before appending the properties

filepath - The file to append to.

Throws:

IOException - if the file could not be found or opened

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

readCodebaseFromLocator

private static String readCodebaseFromLocator(URL url)
                                       throws IOException

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

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.

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.

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

propertyNames

public Enumeration propertyNames()

Returns an enumeration of all the keys in this property list, including the keys in the default property list.

Returns:

an enumeration of all the keys in this property list, including the keys in the default property list.

See Also:

Enumeration, Properties.defaults

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