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

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

public class EpdParams

extends Object

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 command line parameter needs to be prefixed by string "KEY". ie -DKEYand.key.value.pair.of.parameter

A "user" directory. User directory is windchill users' personal cabinet.

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)

getEpdParameterIgnoringCase(key,file,section,default) It has the following methods for updating preferences:

setEpdParameter(key,file,section,value)

deleteEpdParameter(key,file,section,value)

saveUserIni(file)

saveAllUserIni() It has following method to reload preferences:

reload() 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.

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. This preference system keeps one UserParams object per user.

Field Summary

static String	CADXHTMLUI_DATA_SOURCE
static String	NEWWORKSPACE_SECTION
static String	PARTCENTRIC_DEFAULT_VALUE
static String	PARTCENTRIC_KEY
private static HashMap	userPrefMap

Constructor Summary

EpdParams()

Method Summary

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.
static 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.
static 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.
static 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.
private static UserParams	getUserParam()
void	reload() reset EpdParameters to force them to be reread from a file
static void	saveAllUserIni() Saves all userDir based settings.
static 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.
static 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

CADXHTMLUI_DATA_SOURCE

public static final String CADXHTMLUI_DATA_SOURCE

See Also:

Constant Field Values

NEWWORKSPACE_SECTION

public static final String NEWWORKSPACE_SECTION

See Also:

Constant Field Values

PARTCENTRIC_KEY

public static final String PARTCENTRIC_KEY

See Also:

Constant Field Values

PARTCENTRIC_DEFAULT_VALUE

public static final String PARTCENTRIC_DEFAULT_VALUE

See Also:

Constant Field Values

userPrefMap

private static HashMap userPrefMap

Constructor Detail

EpdParams

public EpdParams()

Method Detail

getUserParam

private static UserParams getUserParam()

getEpdParameter

public static 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 static 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 if not found)

getEpdParameterIgnoringCase

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

setEpdParameter

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

reload

public void reload()

reset EpdParameters to force them to be reread from a file