com.ptc.windchill.cadx.common.preference
Class UserParams

java.lang.Object
  com.ptc.windchill.cadx.common.preference.UserParams

public class UserParams

extends Object

This class provides a user preference system to Java applets or applications. This preference system serves up key-value pairs, directory locations or file locations. It is designed to be flexible enough to solve most user preference issues in that it is up to the implementation team as to which settings are policies and which can be modified by the users or overridden on the command line. It consists of six distinct areas which are searched for the desired objects:

A "site" directory as specified with -D option

A "site" directory from preference jar file if located in system classpath

The command line / applet parameters (key-value pairs only)

A "user" directory

A "default" directory as specified with -D option

A "default" directory from preference jar file if located in system classpath Each of these locations is searched (in this order for a given key in a given section in a given file (the command arguments being a slight exception). If key "top" in section "geometry" in file "infobrowser" is being looked up, the site dir is searched for that file, section and key. If the key is not found there, the search continues to the site located in a jar file specified in system's classpath then on the command line (looking for file.section.key=value), then in the user directory, then in the default directory, then in the default located in a jar file specified in system's classpath, and finally a program-supplied absolute fallback value is returned. The site directory is intended to reside in a central single point on the network. As such, the implementation team can designate the preference settings within this directory to be site policies, unable to be overridden by settings on the user's local system. The preference files follow the Windows 3.1 ini file structure; a file containing one or more sections each containing zero or more key value pairs. In addition, directories and / or files within the site, user and default directories can be located for the user by this preference system as well, again with the proper control available to the administrator.

It is intended that the site and default directories would ultimately reside on network disks, protected from user changes, giving the administrators the ability to force certain preferences to be policy rather than the typical arrangement of copying files to all workstations, only to have the users change the control files immediately after the transfers. By specifying those policy values and by providing basic defaults for all options in these two directories, the administrators get the control they need, yet the users can still tailor the application to suit their tastes.

A major difference between this implementation and most property retrieval routines is that the key is main unit being searched for, not the file. Just because an infobrowser.ini file is found in the site dir it does not mean that all preferences stored in infobrowser.ini must be found in that site dir based file. Each key is searched for independently of where any other key has been located.

For example, the infobrowser.ini file might have a geometry section containing top, left, width, and height as keys. The administrator may wish to force the infobrowser to always be top=0 and left=0, yet leave the width and height to the user. To do this, the site dir must contain an infobrowser.ini file with a geometry section and ONLY top=0 and left=0 as the keys in the section. As long as width and height are not specified in the site dir, the user may override them on the command line or in another infobrowser.ini file in the user dir that contains a geometry section and key-value pairs for width and height. To be sure there are first-use values for the width and height (the application will update the settings every time the size or position is changed, but would have no original setting), the administrator could also provide an infobrowser.ini file in the default dir and have default values of top=0, left=0, width=400, height=800.

It has three main access methods for finding objects:

getEpdParameter(key,file,section,default)

getEpdPreferenceUrl(directory)

getEpdPreferenceUrl(directory,file) It has the following methods for updating preferences:

setEpdParameter(key,file,section,value)

saveUserIni(file)

saveAllUserIni() When setEpdParameter is used, the preference cache is updated with the new setting. In order to make it persistent in the file system, the programmer must use one of the save forms. saveUserIni will only write back the single specified file. saveAllUserIni will write back any userDir based files. Only files in userDir can be updated. Only values originally read in from a userDir ini file or provided by a setEpdParameter call will be written back to the file. This it to prevent mixing policy and default values into the user area.

Note that there are older forms of the getEpdParameter method, each using less than four arguments. All these have been deprecated and should be eliminated from code as soon as possible.

IMPORTANT: in order to locate the preference files, the command arguments / parameters "siteDir", "userDir", and "defaultDir" are needed to fix the directory locations needed by the preference system. If none are specified, then all preference data must be supplied in the file.section.key=value format in the command arguments / parameters. These arguments cannot be found anywhere but on the command line since there is no way to locate the files to find these keys unless the keys were set on the command line. It is intended that eventually an LDAP server would supply these keys to the application based on the user, host and the platform type they are currently using.

Implementation note: If only one directory is going to be used, it would be best to use userDir, since without it, no "set" operations can occur. The next level is to add defaultDir with the site default values for the preferences. Finally, add siteDir when it becomes necessary to set site-wide policies.

Nested Class Summary

class

UserParams.DataSourceIni

Field Summary

private String	appendPath
private String	curDataSrc
private ParamPropReader	curDefIni
private ParamPropReader	curSiteIni
private ParamPropReader	curUserIni
private boolean	debug
private String	def
static String	DEFAULT_DIR_KEY_IN_WT_PROP
private static String	defaultCfgDirName
private static String	defaultDefaultDirName
private static String	defaultDirValue
private static String	defaultSiteDirName
private String	defUrl
private Hashtable	dsHash
private ParamPropReader	envIni
private String	envUrl
private String	extension
private boolean	init
private ParamPropReader	jarDefIni
private ParamPropReader	jarSiteIni
private Hashtable	keyHash
String	kvPairPrefix
private String	RESOURCE
private Properties	resourceList
private Hashtable	secHash
private String	site
static String	SITE_DIR_KEY_IN_WT_PROP
private static String	siteDirValue
private String	siteUrl
private Vector	srcIniList
private Hashtable	sysProps
private String[]	systemEnv
static String	USER_DIR_KEY
private String	userUrl
private static String	wtHome
private static String	wtTemp

Constructor Summary

UserParams()

Method Summary

private void	addKeysToCollection(Collection list, Enumeration enum)
private void	addKeysToList(Vector list, Enumeration enum)
String	adjustPath(String p, String dataSource)
private String	checkForDollarValue(String val)
private String	checkPath(String p)
private String	convertDSAndSectName2LowerCase(String key)
boolean	deleteEpdParameter(String key, String datasource, String section, String val) This method allows applications to delete values of parameters in the $userDir/datasource.ini file, in memory.
boolean	doesEpdParameterExist(String key, String dataSource, String section) Read a parameter for a specific datasource from within a specific Section in a specific Ini File.
private void	dump()
private UserParams.DataSourceIni	getDataSourceIni(String ds)
private String	getEpdParam(ParamPropReader refIni, String key)
private String	getEpdParam(ParamPropReader refIni, String key, String section)
String	getEpdParameter(String key) Deprecated. Use the getEpdParameter(key,file,section,default) signature instead.
String	getEpdParameter(String key, String defVal) Deprecated. Use getEpdParameter (key,file,section,default) instead
String	getEpdParameter(String key, String dataSource, String defVal) Deprecated. Use getEpdParameter (key,file,section,default) instead.
String	getEpdParameter(String key, String dataSource, String section, String defVal) Read a parameter for a specific datasource from within a specific Section in a specific Ini File.
Collection	getEpdParameterIgnoringCase(String key) Read a parameter for a specific datasource from within a specific Section in a specific Ini File ignoring case of "key" argument.
Collection	getEpdParameterIgnoringCase(String key, String defVal) Deprecated. Use getEpdParameterIgnoringCase (key,file,section,default) instead
Collection	getEpdParameterIgnoringCase(String key, String dataSource, String defVal) Deprecated. Use getEpdParameterIgnoringCase (key,file,section,default) instead
Collection	getEpdParameterIgnoringCase(String key, String dataSource, String section, String defVal) Read a parameter for a specific datasource from within a specific Section in a specific Ini File ignoring case of "key" argument.
String	getEpdPreferenceUrl(String dir) In this case, the resource path argument will be searched and returned, in the form of a URL encoded string.
String	getEpdPreferenceUrl(String dir, String file) Overloaded function that also returns the location of the "dir/file" as a preference file location
Collection	getKeysForSection(String dataSource, String section) Get a Collection of all the keys defined in the ".ini" files for a particular section, in a particular dataSource.
private String	getParameter(String k)
private String	getParameterIgnoreCase(String k)
private String	getParameterNoIgnoreCase(String k)
private String	getResourcePath(String loc, String k)
private String	getResourcePath(URL dir)
Collection	getSectionsForDatasource(String dataSource) Get a Collection of all the sections defined in the ".ini" files for a particular dataSource.
String[]	getSystemEnvironment() A method to return a listing of all the prop=val Strings from the systemEnv ini file
private String	getSystemResourcePath(String loc, String k)
private void	initialize() Initialization of UserParams class data
private String	internalGetEpdParameter(String key, String dataSource)
private String	internalGetEpdParamFromSection(String key, String dataSource, String section)
private Collection	internalGetEpdParamFromSectionIgnoringCase(String key, String dataSource, String section)
private Collection	internalGetEpdParamIgnoringCase(String key, String dataSource)
static void	main(String[] args)
private void	readEpdParams(String dataSource)
private void	readParamUrls()
private ParamPropReader	readPropertyFile(String loc, String dataSource)
private ParamPropReader	readPropertyFile(URL url)
private ParamPropReader	readSystemPropertyFile(String loc, String dataSource)
void	resetEpdParameters() reset EpdParameters to force them to be reread from a file
void	saveAllUserIni() Saves all userDir based settings.
boolean	saveUserIni(String datasource) This method allows the user to save the $userDir/datasource.ini file to disk, if the file/url permissions permit it.
boolean	setEpdParameter(String key, String datasource, String section, String val) This method allows applications to add/change values of parameters in the $userDir/datasource.ini file, in memory.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

debug

private boolean debug

srcIniList

private Vector srcIniList

curSiteIni

private ParamPropReader curSiteIni

jarSiteIni

private ParamPropReader jarSiteIni

curUserIni

private ParamPropReader curUserIni

curDefIni

private ParamPropReader curDefIni

jarDefIni

private ParamPropReader jarDefIni

envIni

private ParamPropReader envIni

systemEnv

private String[] systemEnv

curDataSrc

private String curDataSrc

siteUrl

private String siteUrl

userUrl

private String userUrl

defUrl

private String defUrl

envUrl

private String envUrl

init

private boolean init

appendPath

private final String appendPath

See Also:

Constant Field Values

extension

private final String extension

See Also:

Constant Field Values

sysProps

private Hashtable sysProps

secHash

private Hashtable secHash

keyHash

private Hashtable keyHash

dsHash

private Hashtable dsHash

site

private final String site

See Also:

Constant Field Values

def

private final String def

See Also:

Constant Field Values

kvPairPrefix

public final String kvPairPrefix

See Also:

Constant Field Values

RESOURCE

private final String RESOURCE

See Also:

Constant Field Values

resourceList

private Properties resourceList

SITE_DIR_KEY_IN_WT_PROP

public static final String SITE_DIR_KEY_IN_WT_PROP

See Also:

Constant Field Values

USER_DIR_KEY

public static final String USER_DIR_KEY

See Also:

Constant Field Values

DEFAULT_DIR_KEY_IN_WT_PROP

public static final String DEFAULT_DIR_KEY_IN_WT_PROP

See Also:

Constant Field Values

wtTemp

private static final String wtTemp

wtHome

private static final String wtHome

defaultCfgDirName

private static final String defaultCfgDirName

defaultSiteDirName

private static final String defaultSiteDirName

See Also:

Constant Field Values

defaultDefaultDirName

private static final String defaultDefaultDirName

See Also:

Constant Field Values

siteDirValue

private static String siteDirValue

defaultDirValue

private static String defaultDirValue

Constructor Detail

UserParams

public UserParams()

Method Detail

readEpdParams

private void readEpdParams(String dataSource)

initialize

private void initialize()

Initialization of UserParams class data

readParamUrls

private void readParamUrls()

getParameter

private String getParameter(String k)

getParameterIgnoreCase

private String getParameterIgnoreCase(String k)

getParameterNoIgnoreCase

private String getParameterNoIgnoreCase(String k)

convertDSAndSectName2LowerCase

private String convertDSAndSectName2LowerCase(String key)

readPropertyFile

private ParamPropReader readPropertyFile(String loc,
                                         String dataSource)

readSystemPropertyFile

private ParamPropReader readSystemPropertyFile(String loc,
                                               String dataSource)

readPropertyFile

private ParamPropReader readPropertyFile(URL url)

checkPath

private String checkPath(String p)

adjustPath

public String adjustPath(String p,
                         String dataSource)

internalGetEpdParameter

private String internalGetEpdParameter(String key,
                                       String dataSource)

getSystemEnvironment

public String[] getSystemEnvironment()

A method to return a listing of all the prop=val Strings from the systemEnv ini file

getEpdParameter

public String getEpdParameter(String key)

Deprecated. Use the getEpdParameter(key,file,section,default) signature instead.

Essentially a shortcut call for getEpdParameter(key,"infobrowser","general",null) [and not a very useful one at that]. It will also search for the key in any other "general" section of any other already read ini file. This makes this routine not specific enough in its searching behavior to be of any real use. Do not use this routine in any production code. This routine retains case sensitivity of key for searching the value.

Returns:

value of the parameter

See Also:

getEpdParameter(String, String, String, String)

getEpdParameter

public String getEpdParameter(String key,
                              String defVal)

Deprecated. Use getEpdParameter (key,file,section,default) instead

Same as getEpdParameter(key) except that is has a default value to be used if the key is not located. This routine retains case sensitivity of key for searching the value.

Returns:

value of the parameter or defVal if not found

See Also:

getEpdParameter(String, String)

getEpdParameter

public String getEpdParameter(String key,
                              String dataSource,
                              String defVal)

Deprecated. Use getEpdParameter (key,file,section,default) instead.

Essentially a shortcut to getEpdParameter(key, file, "general",default). It has been deprecated and should not be used. This routine retains case sensitivity of key for searching the value.

Returns:

value of the parameter or defVal if not found

See Also:

getEpdParameter(String, String, String, String)

internalGetEpdParamFromSection

private String internalGetEpdParamFromSection(String key,
                                              String dataSource,
                                              String section)

resetEpdParameters

public void resetEpdParameters()

reset EpdParameters to force them to be reread from a file

getEpdParameter

public String getEpdParameter(String key,
                              String dataSource,
                              String section,
                              String defVal)

Read a parameter for a specific datasource from within a specific Section in a specific Ini File. This routine retains case sensitivity of key for searching the value.

Returns:

value of the key in the section in the file (or default if not otherwise found)

doesEpdParameterExist

public boolean doesEpdParameterExist(String key,
                                     String dataSource,
                                     String section)

Read a parameter for a specific datasource from within a specific Section in a specific Ini File. This routine retains case sensitivity of key for searching the value.

Returns:

value true if the key is found in the section in the file (or false otherwise)

getEpdParameterIgnoringCase

public Collection getEpdParameterIgnoringCase(String key)

Read a parameter for a specific datasource from within a specific Section in a specific Ini File ignoring case of "key" argument. This routine ignores case of key for searching the value.

Returns:

Collection of values for the matching key in the section in the file (or default if not otherwise found)

getEpdParameterIgnoringCase

public Collection getEpdParameterIgnoringCase(String key,
                                              String defVal)

Deprecated. Use getEpdParameterIgnoringCase (key,file,section,default) instead

Same as getEpdParameterIgnoringCase (key) except that is has a default value to be used if the key is not located. This routine ignores case of key for searching the value.

Returns:

Collection of values or default if not otherwise found

See Also:

getEpdParameter(String, String)

getEpdParameterIgnoringCase

public Collection getEpdParameterIgnoringCase(String key,
                                              String dataSource,
                                              String defVal)

Deprecated. Use getEpdParameterIgnoringCase (key,file,section,default) instead

Essentially a shortcut to getEpdParameterIgnoringCase (key, file, "general",default). This routine ignores case of key for searching the value. It has been deprecated and should not be used.

Returns:

Collection of values or default if not otherwise found

See Also:

getEpdParameter(String, String, String, String)

getEpdParameterIgnoringCase

public Collection getEpdParameterIgnoringCase(String key,
                                              String dataSource,
                                              String section,
                                              String defVal)

Read a parameter for a specific datasource from within a specific Section in a specific Ini File ignoring case of "key" argument.

Returns:

Collection of values of the key in the section in the file (or default if not otherwise found)

internalGetEpdParamFromSectionIgnoringCase

private Collection internalGetEpdParamFromSectionIgnoringCase(String key,
                                                              String dataSource,
                                                              String section)

internalGetEpdParamIgnoringCase

private Collection internalGetEpdParamIgnoringCase(String key,
                                                   String dataSource)

getSectionsForDatasource

public Collection getSectionsForDatasource(String dataSource)

Get a Collection of all the sections defined in the ".ini" files for a particular dataSource. This lists all the sections in memory. Caveat: The section keys defined using -D parameters are ignored by this method.

Returns:

Collection of all the sections, null if there are any errors

getKeysForSection

public Collection getKeysForSection(String dataSource,
                                    String section)

Get a Collection of all the keys defined in the ".ini" files for a particular section, in a particular dataSource. This lists all the sections in memory. Caveat: The section keys defined using -D parameters are ignored by this method.

Returns:

Collection of all the keys, null if there are any errors

addKeysToCollection

private void addKeysToCollection(Collection list,
                                 Enumeration enum)

addKeysToList

private void addKeysToList(Vector list,
                           Enumeration enum)

getEpdPreferenceUrl

public String getEpdPreferenceUrl(String dir)

In this case, the resource path argument will be searched and returned, in the form of a URL encoded string. The physical path location is queried and the first found path is returned. As shown in getEpdParameter(String, String) the resource directories for each datasource shall be defined under the respective directories. Also note that the search here shall be case-sensitive with respect to the key

Returns:

String pointing to the URL of the requested resource

See Also:

#java.net.URL, getEpdParameter(String, String)

getEpdPreferenceUrl

public String getEpdPreferenceUrl(String dir,
                                  String file)

Overloaded function that also returns the location of the "dir/file" as a preference file location

See Also:

getEpdPreferenceUrl(String)

getSystemResourcePath

private String getSystemResourcePath(String loc,
                                     String k)

getResourcePath

private String getResourcePath(String loc,
                               String k)

getResourcePath

private String getResourcePath(URL dir)

getEpdParam

private String getEpdParam(ParamPropReader refIni,
                           String key)

getEpdParam

private String getEpdParam(ParamPropReader refIni,
                           String key,
                           String section)

checkForDollarValue

private String checkForDollarValue(String val)

getDataSourceIni

private UserParams.DataSourceIni getDataSourceIni(String ds)

setEpdParameter

public boolean setEpdParameter(String key,
                               String datasource,
                               String section,
                               String val)

This method allows applications to add/change values of parameters in the $userDir/datasource.ini file, in memory. If such a file doesnot exist only the memory structure is created and cached.

Returns:

true if it successfully adds/updates the parameter. If the $userDir is not defined it returns a false, indicating unsuccessful operation

deleteEpdParameter

public boolean deleteEpdParameter(String key,
                                  String datasource,
                                  String section,
                                  String val)

This method allows applications to delete values of parameters in the $userDir/datasource.ini file, in memory. If such a file doesnot exist in userDir it will return unsuccessfully.

Returns:

true if it successfully adds/updates the parameter. If the $userDir is not defined it returns a false, indicating unsuccessful operation

saveUserIni

public boolean saveUserIni(String datasource)

This method allows the user to save the $userDir/datasource.ini file to disk, if the file/url permissions permit it. For the save operation to be successful the following conditions are necessary: 1. $userDir is defined 2. ini file in memory for $userDir/datasource.ini exists (either read in by an access call to UserParams.getEpdParameter(..) or created afresh using setEpdParameter(key,file,section,value). 3. The user has write permissions in $userDir/ and to the file $userDir/datasource.ini (this is required to allow creation of a temp file $userDir/datasource.ini.tmp to recover the original inifile from any Exceptions during File-writing)

Returns:

true is write is successful.

saveAllUserIni

public void saveAllUserIni()

Saves all userDir based settings. All files specified in a setEpdParameter or found via a getEpdParameter method call will be re-written to the userDir area.

dump

private void dump()

main

public static void main(String[] args)