How to Write a Configuration Plug-in

Table of Contents

• Introduction
• Plug-in Declaration
  
• Plug-in Information
• Core Properties
• Local Properities
• Configuration Plug-in API
• public interface SetterLauncher
• public class AccLipInfoPackage
• Multi-type Adaptive Technology
• Location of Code and Data
• Summary
  
• Appendix A: Technology Types
  

Introduction

This document describes how the Configuration Manager locates, loads, and activates a configuration plug-in.  In addition, it describes how to implement the configuration plug-in itself in terms of the information passed to it, where the plug-in can acquire other relevant information, and how it is to function.

Three sources provide the information necessary for a configuration plug-in to perform its job.  They include a file declaring the properties of the plug-in, the plug-in code itself, and information about the preferences passed to the plug-in.

Plug-in Declaration

A two-stage process is used to load and invoke a configuration plug-in.  In the first stage, the Control Hub loads information about all the available plug-ins.  The second stage occurs when the Configuration Manager processes the AccLIP, and attempts to match user's preferences to the appropriate plug-in.  This section describes the mechanisms used by the Control Hub and the Configuration Manager to accomplish these tasks.

Plug-in Information

The Control Hub determines the available plug-ins when the Web-4-All system first starts up.  This one-time registration process detects and records all available plug-ins for later use.

Information about individual plug-ins is stored in a java.util.PropertyResourceBundle instance.  The resource bundle is created from a ".properties" file on disk.  There are two sets of properties within the file: a core set and a local set.  The former is a standard obligatory set of properties used by the Configuration Manager.  The latter is a set of properties that the third party vendor may wish to declare and use within their plug-in.  There is no restriction on the format of the local set of properites.  They are completely optional.  The next section describes the structure of the core properties using an example based on a fictitious adaptive technology called "EpiScreen".

back to top

Core Properties

The first property declared in the file is an identifier that uniquely identifies the third party technology associated with the plug-in.  The name of the property is "appID".  One constraint on the appID value is that it must match an associated identifier given in the AccLIP.  Specifically, the AccLIP defines an element named <application> that has an name attribute.  That name is used by the Configuration Manager to match the <application> element to the configuration plug-in, via its "appID" property.  Consider, for example,  this fragment of an AccLIP, in which the user has declared their screen reader preferences, and selected "EpiScreen" as their screen reader:

...
<screenReader>
    <screenReaderGeneric>
        ...			<!-- Generic preferences here -->
    </screenReaderGeneric>
    <application name="EpiScreen" priority="1"/>
</screenReader>
...

The Configuration Manager matches the user's preferences with the appropriate third party software (in this instance, the EpiScreen application) using the plug-in's "appID" property.  It must be set to the same name in the "Episcreen.properties" file:

appID=EpiScreen

The "appID" property acts as a key that the Configuration Manager can use to ask the Control Hub for information about that technology.

The next property, "appType", declares the type of adaptive technology.  The technology classification is taken from the AccLIP and includes types such as screen readers, onscreen keyboards, voice recognition, and so on.  Any given technology could, in theory, be described as multiple types of technology.  For example the GNOME screen reader "Gnopernicus" is both a screen reader and a screen magnifier.  To handle the possibility of multi-type technologies, the "appType" property is written as a comma separated list of technology types.  If the technology is properly described as just a single type, then only that type is entered:

appType=screen.reader   		# means: EpiScreen is just a screen reader.

vs.

appType=screen.reader,screen.enhance    # means: EpiScreen is a screen reader and a screen enhancer.

In addition to declaring an application as a specific type of adaptive technology, the "appType" property can be used as a key to discover if a particular technology type is available on a workstation.  The Control Hub stores the information in the properties files in such a way that, given an "appType", it will provide a list of all "appID"s matching that technology type.  Thus, if there is more that one screen reader available, by asking for all the technologies of "appType" screen.reader, the ControlHub will respond with a list of all matching appIDs.  That list could consist of "EpiScreen", "HomePageReader", "JAWS", and/or "Gnopernicus", depending on what has been installed on the workstation.  

The legal values for the "appType" property are defined by the AccLIP, and are given in the ca.utoronto.atrc.web4all.Web4AllConstants  java interface.  They are repeated in Appendix A of this document.

The remaining core properties are all prefixed with the value of the "appID" property; in the current example, the string "EpiScreen" is used.  There are two properties that name the JavaTM classes to use for the preferences wizard plug-in and configuration plug-in.  They are named "prefs" and "config", respectively.  The first of these is optional, while the latter is mandatory.  In both cases, the name is the fully qualified JavaTM class name.  For the EpiScreen example, assume that there is no preferences wizard plug-in.  Then, these properties would appear in the "EpiScreen.properties" file like so:

Episcreen.prefs=
Episcreen.config=com.epicorp.episcreen.EpiScreenSettings

This declares that the EpiScreen screen reader/screen enhancer has no preferences wizard plug-in, and that its configuration plug-in is the class com.epicorp.episcreen.EpiScreenSettings.

Note: with respect to the core properties, "optional" means that the property must be declared, but need not have a value.  For example:

Episcreen.prefs=		# no value specified for 'Episcreen.prefs'.

The Web-4-All system needs to determine if the third party software is actually present on the workstation.  For example, the Preferences Wizard Manager will announce, in one of its dialogs, whether the technology is present and the Configuration Manager will ignore plug-ins for all third party technologies that are not available.  The availability of the technology is determined via the "exec" property, which defines a path to an executable. For example:

Episcreen.exec=C:\\Program Files\\EpiCorp\\Episcreen.exe

The path can be a full path, as in the example above, or a relative path.  If relative, then it must be relative to the directory from which the Web-4-All system was launched.  This is a property of the Control Hub and can be acquired via its getHomeDirectory() method. 

Applications frequently consult an initialization file that contains all of their settings.  On Windows, these take the form of a text file with the extension ".ini".  There is an optional core property for plug-ins that specifies the location of the relevant initialization file.  Like the "exec" property, the location is given as either a full path to the file, or a path relative to the home directory of the Web-4-All system.  For example:

Episcreen.ini=3rd_party\\EpiScreen\\EpiScreen.ini

The above says that EpiScreen's initialization file is found in the directory tree rooted at the "3rd_party" directory, which is immediately inside Web-4-All's home directory.  The "ini" property is optional, since not all technologies use such a file for their settings.

The final core property is for use within the user interface.  The "product.name" property is the name of the product that users would recognize.  It is a required property:

Episcreen.product.name=EpiScreen Reader-Enhancer

To summarize, the core properties that must be declared for a plug-in are:

• a unique ID that matches the application name from the AccLIP (required).
• a description of the type of adaptive technology (required).
• the fully qualified Java class name of the object to use as the preferences plug-in (optional).
• the fully qualified Java class name of the object to use as the configuration plug-in (required).
• the full or relative path to the executable (required).
• the full or relative path to the ".ini" or similar file to write settings into (optional).
• a user friendly string that names the product (required).
  

Here is the example core properties for the EpiScreen application in its entirety:

# Core properties

appID=Episcreen
appType=screen.reader,screen.enchance
Episcreen.prefs=
Episcreen.config=com.epicorp.episcreen.EpiScreenSettings
Episcreen.exec=C:\\Program Files\\EpiCorp\\Episcreen.exe
Episcreen.ini=3rd_party\\EpiScreen\\EpiScreen.ini
Episcreen.product.name=EpiScreen Reader-Enhancer

back to top

Local Properties

The core properties are what are needed by the Web-4-All system to configure the workstation for a third party technology.  However, the plug-in for that technology may need access to more information than is provided by the core.  There is provision within the system to allow any number of other properties to be declared and stored in the plug-in's property file.  These are termed "local" properties.  There is no restriction on them, other than they must follow the constraints of a JavaTM properties file, and can be loaded into a java.util.PropertiesResourceBundle.

The local properties could declare other other types of variables, values for those variables, other executables that the plug-in may wish to execute, or even the location of images and sounds.  For example, Episcreen may use some of the values from its ".ini" file to set some Windows registry settings.  The following three example properties declare registry keys for some ".ini" entries and the path to a command line executable that will set the proper registry settings:

# Local properties

registrykey.int=[Software\\EpiCorp\\EpiScreen\\Settings\\INT]
registrykey.string=[Software\\EpiCorp\\EpiScreen\\Settings\\STRING]
registry.exec=3rd_party\\RegistryConsole\\RegistryConsole.exe

Because someone familiar with the application has implemented it, the Episcreen configuration plug-in can use this information to correctly set relevant registry entries.

Note:  the command line executable "RegistryConsole.exe" is included in the Web-4-All package for any plug-in to use.  It is documented in the "Windows Command Line Exectuables" document.

Access to these local properties is provided through the Control Hub, and the configuration plug-in itself.  The latter is accomplished by implementing the configuration plug-in API.  Having described how properties of the plug-in are declared, the next section describes the plug-in API itself and explains what is involved in implementing a plug-in that configures and launches a third party technology.

back to top

Configuration Plug-in API

public interface SetterLauncher

Configuration plug-ins must implement a common API in order to qualify as a plug-in.  The API is made up of a number of JavaTM  interfaces and classes.  The central API is the  interface ca.utoronto.atrc.web4all.configuration.SetterLauncher.  This section declares the methods of SetterLauncher and describes their intent.  The first three methods of SetterLauncher are described in the order that the Configuration Manager calls them; in brief, the technique employed by the Configuration Manager is:

1. Apply the AccLIP preferences the user has chosen.
2. Launch the adaptive technology.
3. Reset the adaptive technology, and exit it.

doSettings()

public boolean doSettings (Vector inAccLipInfoPackages, ControlHub inControlHub);

This method is called to do whatever is necessary to take the settings in the AccLIP document, and apply them to the adaptive technology. This includes, for example, writing a ".ini" file, or setting registry values. Argument meanings are as follows:

Vector inAccLipInfoPackages

A Vector of ca.utoronto.atrc.web4all.configuration.AccLipInfoPackage instances. Each member of the Vector references a specific type of technology (e.g., a screen reader) and that technology's generic and specific container elements. The methods of AccLipInfoPackage are described more fully in the next section, "public class AccLipInfoPackage".

inControlHub

The Control Hub: it provides access to information such as the location of a relevant ".ini" file, or the path to the application.

Return value:

A boolean to indicate whether the plug-in intends to launch a Web browser. For example, the SetterLauncher for Home Page Reader should return true since Home Page Reader is a browser.  However, the SetterLauncher for configuring the keyboard (e.g., sticky keys) does not, in fact, launch a browser. The Configuration Manager needs to know if one of its SetterLauncher's does launch a browser.  If none do, it must launch one.  This is because Web-4-All requires that at least one Web browser to be launched once the workstation is configured.

doLaunch()

public void doLaunch();

This method is called to launch the adaptive technology.  By the time this is called, all the configuration information should have been properly extracted from the user preferences and "installed" -- see doSettings() above.

kill()

public void kill();

This method is called to shut down the process launched by doLaunch().  In addition, this should undo any configuration done by doSettings() ensuring that the third party technology is left in a standard, default state.

initLocalProps()

public boolean initLocalProps();

This method is called to acquire the set of local properties as given in the plug-in ".properties" file as described above in the "Local Properties" section.   The return value is a boolean that indicates whether the properties were found.  It is the responsibility of the plug-in to define when this is called, since the Configuration Manager does not call it directly.  Typically, a plug-in runs initLocalProps() as part of its initialization to ensure it has a copy of its local properties before its doSettings() is called.

back to top

class AccLipInfoPackage

Instances of the AccLipInfoPackage class are created by the Configuration Manager based on the information it finds in the plug-in properties files.  When the Configuration Manager finds a match between the AccLIP preferences and a plug-in, it instantiates the plug-in, and passes it the relevant parts of the AccLIP.  The technique for passing the AccLIP information is via an AccLipInfoPackage instance.  The following describes the methods of class AccLipInfoPackage.

getAppType()

public String getAppType()

This method returns the application type as a String.  This is one of the types defined in the AccLIP schema.

getGenericPrefs()

public Element getGenericPrefs()

Retrieve the Element, from the AccLIP document, that represents the generic preferences for the technology.  The return value is of type org.w3c.dom.Element.

getSpecificPrefs()

public Element getSpecificPrefs()

Retrieve the Element, from the AccLIP document, that represents the third party application specific preferences.  The return value is of type org.w3c.dom.Element, which is the <application> element itself.  It may or may not contain a set of <param>elements that define the technology-specific preferences.

Multi-type Adaptive Technology

A warning about how plug-ins should be implemented:  The plug-in should configure its associated third party technology only for the type indicated by the corresponding AccLipInfoPackage.  For example, EpiScreen is declared in its properties file as both a screen reader and a screen enhancer.  However, if its configuration plug-in is given only an AccLipInfoPackage instance whose application type is "screenEnhancer", then the plug-in should configure only the screen enhancement aspect of EpiScreen.  The reason for this is because the user may have chosen another technology to use as their screen reader, and if both EpiScreen and that other screen reader are launched as screen readers, the user experience may be confusing.  Worse, the two competing speech synthesizers could lead to system crash.

This raises the question of how the system behaves when the user has chosen EpiScreen for both its screen reader and screen enhancing capabilities.  Recall that the doSettings() method of the plug-in is passed a list of AccLipInfoPackages.  If the user has chosen EpiScreen for both of its functions, then there will be two instances of  AccLipInfoPackage - one whose application type is screen reader, and the other, screen enhancement.   EpiScreen's plug-in should check the entire list to see if both application types are desired of EpiScreen.

back to top

Location of Code and Data

Given that a developer has implemented the plug-in API, and defined the plug-in's properties, the question arises as to where this data and code should be located.  Web-4-All assumes a specific directory structure, namely, that there is a sub-directory named "3rd_party" in the same location as the Web-4-All exectuable. The Control Hub expects a plug-in properties file to be located in this sub-directory.  The plug-in loader requires that the plug-ins be in the class path; however, Web-4-All searches the "3rd_party" folder for ".jar" files.  As such, implementors can avoid class path issues by placing their plug-in code in a jar, and then put that jar in the "3rd_party" directory.

Summary

This document has described the essentials of creating a configuration plug-in for the Web-4-All system.  If the properties file and SetterLauncher are implemented and located properly within the file system, then the Configuration Manager will find the plug-in and call upon it to configure the relevant third party technology.

There are a number of tasks that are common among SetterLaunchers.  In recognition of this, the configuration package that ships with Web-4-All includes utility classes and code designed to simplify the task of implementing a plug-in.  The document "Configuration Plug-in Utilities" describes these utilities and suggests ways that they could be used.

back to top

Appendix A: Technology Types

The interface ca.utoronto.atrc.web4all.Web4AllConstants lists the legitimate values of the "appType" plug-in property:

back to top

Copyright © 2003-2006 Adaptive Technology Resource Centre, University of Toronto.
All rights reserved.
Last modified: Feb 20 2006, Joseph Scheuhammer.