ProxyToolRegistry package

This package provides PowerLinks developers with the ability to save and retrieve named values in a database. The values are associated with a particular proxy tool, instance and/or user and allow data for a user to persist between accesses. The data may be stored in any database accessible as a WebLogic data source or via a JDBC connection string.

The ProxyToolRegistry package can be used by PowerLinks written for WebCT Vista 4.2 (or higher) and WebCT Campus Edition 6.2 (or higher). It is dependent on the following Java packages:

• org.apache.commons.dbcp
• org.apache.commons.pool
• org.oscelot.webct.dao (2.3 or higher)

This package is designed for use with PowerLinks and may be installed either by copying the jar file into the same directory as the PowerLink itself, or placed in the common directory so that it can be shared by more than one PowerLink. The same choice applies to the jar files for each of the dependent Java packages.

The package uses a single database table for storing the settings values. The table may be created in any database for which there is a Java JDBC database driver available. By default it is assumed to use a data source defined on the same Weblogic server as used by WebCT. The database table should have the following definition:

All setting values are stored and retrieved as strings but may be converted to other data types as required. The maximum size of any individual setting value is 4,000 characters but this can be increased as required subject to any database limitations (for example, Oracle 8.1 and above limit the size of varchar fields to 4,000 bytes). Use the addLongSetting() and getLongSetting() methods to save and retrieve settings which may have values which are too long to be saved in a single record. The following SQL statements illustrate how table specified above might be created (the table name may be changed to suit). For Microsoft SQL Server:

For Oracle:

Note that Oracle users should also set the empty property (see below) as the database does not support empty strings.

An optional properties file may be placed in the same directory as the package file. This file should have the same file name as the package but be given an extension of .properties. For example, if the package is named ProxyToolRegistry.jar it will look for a properties file named ProxyToolRegistry.properties. The properties file may contain one or more of the following settings:

Using a WebLogic data source

Since WebCT is run using WebLogic the easiest way of adding this database is as a data source within the WebLogic Server Administration Console in a similar way to the data sources used to connect to the WebCT databases. Further details on creating WebLogic data sources can be found on their documentation website. When using a data source (or multi data source) name other than the default of ProxyToolRegistry include the following lines in the properties file:

where:

• xxx is the name of the data source
• yyy is the name of a database user with read/write access to the data source
• zzz is the password for the database user

Using a JDBC connection

It is also possible to define a standard JDBC connection string to connect to the database table. This may be specified by including the following line in the properties file:

where:

• jdbc:bea:sqlserver is the name of the driver to use
• db.server.com:port is the location of the database server
• db_name is the name of the database

A connection to an Oracle database can be specified like this:

JDBC drivers for other databases are also available; check your database documentation for details.

Class methods

This package is comprised of a single class which is fully described in the JavaDocs documentation. The main methods supported are as follows:

• ProxyToolRegistry - constructor
• addSetting - add a setting value
• addSettings - add a list of settings
• addLongSetting - add a setting value which will be split across multiple records if too large
• getSetting - get a setting value
• getSettings - get all settings
• getLongSetting - get a setting value which may have been split across multiple records
• updateSetting - update an existing setting value
• updateSettings - update a list of existing settings
• deleteSetting - delete a setting value
• deleteSettings - delete all settings
• deleteLongSetting - delete a setting value which may have been split across multiple records
• setAutoAdd - set the AutoAdd setting
• setAutoUpdate - set the AutoUpdate setting
• setSaveEmptyValues - set the SaveEmptyValues setting
• getUserSummary - gets a map of details for each user
• isInstitutionAdmin - check if the user is an Institution Administrator
• close - close the class instance

Each setting comprises a simple name and value pair. However, there are four different types of setting which are supported as specified by the values of the global and anonymous parameters.

Note the term global is used to refer to all proxy tool instances within the same institution and not for all instituons on the server. Some illustrations of common uses of these methods follow.

Creating an instance

An instance of this utility can be created by calling its constructor method. The SaveEmptyValues property determines whether, or not, a setting should be saved when its value is empty. The default value is true which means that settings may have empty values. However, when this value is set to false new settings will not be created with empty values and updating an existing setting to an empty value will cause it to be deleted. This saves wasting database space as the value of a non-existent setting will be empty anyway.

Accessing a single setting

The following examples illustrate how to access a setting for each of the four categories identified above. They assume that a instance of this proxy tool registry has been created with a name of ptReg

1. User-specific data for a proxy tool instance

These settings apply to a single proxy tool instance and to a single user; for example, this could be used to save data entered by a user.

Note: the alternate form of each of the above methods may be used instead by specifying a value of false for both the global and anonymous parameters. That is,

is equivalent to

2. General settings for a proxy tool instance

These settings apply to all users for a single proxy tool instance; for example, this could be used to save configuration settings made by a section designer or instructor.

3. User-specific data for all instances of a proxy tool

These settings apply to all instances of a proxy tool for the same user; for example, this could be used to save general configuration settings for a user.

4. General settings for all instances of a proxy tool

These settings apply to all users and all instances of a proxy tool within an institution; for example, this could be used to save institution-wide configuration settings for the tool.

Note: only users who have the institution administrator role are able to add, update and delete settings in this category.

Processing multiple settings

Methods are also provided to process a list of settings at the same time. The getSettings method will return all the settings in the specified category as a Map. It is also possible to limit the list returned to only those settings with names beginning with a specified prefix.

The addSettings, updateSettings and deleteSettings methods all process a list of settings supplied as a Map.

Handling long setting values

If the size of the SettingValue field is not sufficient for the data to be stored, then the long settings facility can be used to automatically split larger values across multiple records.

Add/update a long setting

A long setting is added in the same way as a normal setting, except that if a setting of the same name already exists it will always be updated irrespective of the AutoUpdate setting and no record will remain in the database when a setting has an empty values irrespective of the SaveEmptyValues setting.

If, for the sake of this example, the length of the SettingValue field in the database is only 40 characters (not a length which is recommended for a real system!), then the above description value will be stored in two records:

The separator between the name of the setting specified in the code ("Description") and the record sequence number (1, 2) defaults to a semicolon but can be changed via the properties file (see above). (The names of any long settings already in the database will need to be updated manually if this property is changed.) The sequence numbers used will always have the same length to preserve their natural sort order (e.g. 01, 02, ..., 10, 11). The setting name should be short enough to allow the separator and the sequence number to be appended without exceeding the size of the SettingName field (which is 256 characters by default).

Accessing the value of a long setting

Using the normal getSetting method will normally return an empty string for a long setting because no record exists with that name; the name for a long setting has a separator and sequence number appended to it. Thus, to retrieve the value for a long setting the getLongSetting method should be used so that the relevant sequence of records can be concatenated. There are two main versions of this method, one which accesses the database to retrieve the relevant records, and one which extracts these from a map of settings which has already been retrieved:

Deleting a long setting

A long setting should be deleted by using the deleteLongSetting method. This is equivalent to adding a long setting with no value.

Deleting an instance

The resources associated with an instance of the Proxy Tool Registry may be released by calling the close method; for example:

This work is written by Stephen Vickers and is released under a Creative Commons GNU General Public Licence. The ProxyToolRegistry package is downloadable from OSCELOT where it is also possible to report bugs and submit feature requests.