ca.utoronto.atrc.web4all.configuration
Class AbstractSetterLauncher

java.lang.Object
  ca.utoronto.atrc.web4all.configuration.AbstractSetterLauncher

All Implemented Interfaces:

SetterLauncher

public abstract class AbstractSetterLauncher

extends java.lang.Object

implements SetterLauncher

Class that provides the base structure of a SetterLauncher without actually implementing the methods of the interface. It also provides a number of utility methods that a specific SetterLauncher might want to use.

Constructor Summary

AbstractSetterLauncher()
Initialize the SetterLauncher with all of its internal data initially set to "null", and then perform the initialization proper via a call to init().

Method Summary

protected void	addArgToArray(java.lang.String inParameter, java.lang.String inValue) Add the given parameter's value to the command line argument array.
protected void	clearParamsWritten(java.lang.String inTechType) Utility for setting parameters' written state array to false.
protected void	closeOutput() Flush and close the current output file.
protected java.lang.String[]	createArgsArray(int inNumArgs) Create an empty String array to hold a set of command line arguments.
protected java.io.PrintWriter	createOutput(java.lang.String inFullPath) Create the output file from a full path to the file.
protected java.io.PrintWriter	createOutput(java.lang.String inFullPath, boolean inAppend) Create the output file from a full path to the file.
protected java.io.PrintWriter	createOutput(java.lang.String inHomeDir, java.lang.String inFileName) Create the output file, given a relative path to a directory, and a file name.
protected java.io.PrintWriter	createOutput(java.lang.String inHomeDir, java.lang.String inFileName, boolean useSubDir) Create the output file, given a relative or absolute path to a directory, a file name, and whether the directory is a sub-directory.
protected void	createReadProcessIStreams() Allocate the ReadProcessIStreams object, if desired.
protected abstract void	doWriteSetting(java.lang.String inParameter, java.lang.String inValue) Abstract method for "writing" the setting.
ParameterState	findParameter(java.lang.String inTechType, java.lang.String inAccLipPrefName) Given a type of technology and a preference name from the ACCLIP, determine if it is a parameter this plug-in handles.
ParameterState	findParameter(java.lang.String inTechType, java.lang.String inAccLipPrefName, boolean isGeneric) Given a type of technology and a preference name from the ACCLIP document, determine if it is a parameter this technology handles.
java.lang.String	getAppID() Retrieve the application ID for the SetterLauncher.
org.w3c.dom.Element	getAppSettings() Retrieve the root of the ACCLIP DOM for the current technology that this SetterLauncher is processing.
protected java.lang.String[]	getArgsArray() Retrieve the array of strings that represent a set of command line arguments.
protected java.util.ResourceBundle	getArgsIndexMap() Retrieve the argument index map for a command line argument string.
ControlHub	getControlHub() Get the Control Hub property.
protected java.lang.String	getLocalProperty(java.lang.String inPropName) Retrieve one of the plug-in's local properties.
protected java.lang.Process	getProcess() Retrieve the process launched by this SetterLauncher.
java.lang.String	getValueValue(org.w3c.dom.Element inPref) Given a prefs element, find its Web4AllConstansts.VAL_ATT attribute and return the value of that attribute.
protected void	handlePref(java.lang.String inTechType, org.w3c.dom.Element inPref) Given a technology type and a preference for that type, determine if it is one that this SetterLauncher handles.
protected void	handlePref(java.lang.String inTechType, org.w3c.dom.Element inPref, boolean isGeneric) Given a technology type and a preference for that type, determine if it is one that this SetterLauncher handles.
protected void	handleProcessIStreams(java.lang.Process inProcess) Activate the ReadProcessIStreams object.
protected void	handleProcessIStreams(java.lang.Process inProcess, boolean logFlag) Activate the ReadProcessIStreams object.
protected void	handleUnwrittenParams(java.lang.String inTechType) Write out default values for those preferences that were not in the ACCLIP document.
protected abstract void	init() Class specific initialization -- must be overridden.
boolean	initLocalProps() Basic implementation for acquiring the local properties of the plug-in.
void	kill() Basic implementation of the SetterLauncher kill method.
float	linearCalcTechVal(java.lang.String inAccLipVal, float inSlope, float inIntercept) Utility to convert a floating point ACCLIP preference value to a parameter value.
protected void	loopThru3rdPartyPrefs(java.lang.String inTechType, org.w3c.dom.Element in3rdPartyPrefs) Loop thru the specific preferences for the given type of technology.
protected void	loopThruGenerics(java.lang.String inTechType, org.w3c.dom.Element inGenericContainer) Loop through the generic preferences from the ACCLIP for the given type of technology.
protected java.lang.String	mapValue(java.lang.String inParam, java.lang.String inValue) Map the value retrieved from the preferences document to the parameter's value.
protected void	setAppID(org.w3c.dom.Element in3rdPartyPrefs) Set the application ID for this SetterLauncher based on an application preferences element from the ACCLIP.
void	setAppID(java.lang.String inAppID) Set the application ID for the SetterLauncher.
void	setAppSettings(org.w3c.dom.Element inAppSettings) Set the root of the ACCLIP document for the current technology that the SetterLauncher is processing.
protected void	setArgsArray(java.lang.String[] ioArgsArray) Use the given String array for the command line arguments.
protected void	setArgsIndexMap(java.util.ResourceBundle inArgsIndexMap) Set the argument index map for a command line argument array.
void	setControlHub(ControlHub inControlHub) Set the Control Hub property.
protected void	setProcess(java.lang.Process inProcess) Set the process launched by this SetterLauncher.
protected void	setUpParameters(SettingsBundle[] inParams, java.util.ResourceBundle inValueMapChooser) Initialize the technology specific parameters of interest and the value map chooser.
protected void	writeSetting(java.lang.String inParameter, int inValue) Write the given paramater and its value.
protected void	writeSetting(java.lang.String inParameter, java.lang.Number inValue) Write the given paramater and its value.
protected void	writeSetting(java.lang.String inParameter, java.lang.String inValue) Write the given paramater and its value.

Methods inherited from class java.lang.Object

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

Methods inherited from interface ca.utoronto.atrc.web4all.configuration.SetterLauncher

doLaunch, doSettings

Constructor Detail

AbstractSetterLauncher

public AbstractSetterLauncher()

Initialize the SetterLauncher with all of its internal data initially set to "null", and then perform the initialization proper via a call to init().

See Also:

init()

Method Detail

init

protected abstract void init()

Class specific initialization -- must be overridden.

See Also:

setUpParameters(SettingsBundle[],ResourceBundle), createOutput(String,String)., createOutput(String,String,boolean)., createOutput(String)., createArgsArray(int), setArgsArray(String[]), getArgsArray(), setArgsIndexMap(ResourceBundle), getArgsIndexMap()

setUpParameters

protected void setUpParameters(SettingsBundle[] inParams,
                               java.util.ResourceBundle inValueMapChooser)

Initialize the technology specific parameters of interest and the value map chooser. This should be called only once during initialization.

Parameters:

inParams - An array of SettingsBundle for the technology specific settings handled by this SetterLauncher. There is one bundle for each type of technology.

inValueMapChooser - A ResourceBundle that, given a parameter name, chooses a value map that associates an ACCLIP preference value with a technology parameter value.

See Also:

init(), clearParamsWritten(String)

clearParamsWritten

protected void clearParamsWritten(java.lang.String inTechType)

Utility for setting parameters' written state array to false. The relevant parameters are determined by the given technology type, and only their written state is cleared. The given type of technology is expressed in the vocabulary of the ACCLIP.

Parameters:

inTechType - The type of technology whose parameters written state are to be cleared.

See Also:

setUpParameters(SettingsBundle[],ResourceBundle)

createOutput

protected java.io.PrintWriter createOutput(java.lang.String inHomeDir,
                                           java.lang.String inFileName)

Create the output file, given a relative path to a directory, and a file name. The directory referenced by th path is assumed to be a sub-directory of Web-4-All's home directory.

Parameters:

inHomeDir - Path to the directory relative to Web-4-All's home directory.

inFileName - The name of the file to create.

Returns:

A FileWriter, or null if an I/O error occurred.

See Also:

init(), ControlHub.getHomeDirectory(), createOutput(String,String,boolean), createOutput(String)

createOutput

protected java.io.PrintWriter createOutput(java.lang.String inHomeDir,
                                           java.lang.String inFileName,
                                           boolean useSubDir)

Create the output file, given a relative or absolute path to a directory, a file name, and whether the directory is a sub-directory. If the first argument is an absolute path, then the flag should be false. If it is true the path is assumed to be relative, and relative to Web-4-All's home directory.

Parameters:

inHomeDir - Path to a directory relative to Web-4-All's home directory, "or", the full path to the directory containing the file (see argument useSubDir below).

inFileName - The name of the file.

useSubDir - A flag that indicates whether inHomeDir is a sub-folder or a full path to some other directory.

Returns:

A FileWriter, or null if there was an I/O error.

See Also:

init(), ControlHub.getHomeDirectory(), createOutput(String,String), createOutput(String)

createOutput

protected java.io.PrintWriter createOutput(java.lang.String inFullPath)

Create the output file from a full path to the file.

Parameters:

inFullPath - A String that is the full path to the file.

Returns:

A FileWriter, or null if there was an I/O error.

See Also:

init(), createOutput(String,String), createOutput(String,String,boolean)

createOutput

protected java.io.PrintWriter createOutput(java.lang.String inFullPath,
                                           boolean inAppend)

Create the output file from a full path to the file.

Parameters:

inFullPath - A String that is the full path to the file.

inAppend - A boolean indicating whether or not to append the output.

Returns:

A FileWriter, or null if there was an I/O error.

See Also:

init(), createOutput(String,String), createOutput(String,String,boolean)

closeOutput

protected void closeOutput()

Flush and close the current output file. The connection to the output file is lost.

See Also:

createOutput(String,String), createOutput(String,String,boolean), createOutput(String)

createArgsArray

protected java.lang.String[] createArgsArray(int inNumArgs)

Create an empty String array to hold a set of command line arguments. Also, the array is retained internally as if set by setArgsArray().

Parameters:

inNumArgs - The number of arguments in the array.

Returns:

A String array.

See Also:

setArgsArray(String[]), getArgsArray(), setArgsIndexMap(ResourceBundle), getArgsIndexMap()

setArgsArray

protected void setArgsArray(java.lang.String[] ioArgsArray)

Use the given String array for the command line arguments.

Parameters:

ioArgsArray - Array to use for the arguments.

See Also:

createArgsArray(int), getArgsArray(), setArgsIndexMap(ResourceBundle), getArgsIndexMap()

getArgsArray

protected java.lang.String[] getArgsArray()

Retrieve the array of strings that represent a set of command line arguments.

Returns:

The array of command line arguments.

See Also:

createArgsArray(int), setArgsArray(String[]), setArgsIndexMap(ResourceBundle), getArgsIndexMap()

setArgsIndexMap

protected void setArgsIndexMap(java.util.ResourceBundle inArgsIndexMap)

Set the argument index map for a command line argument array. This is needed when the meaning of each command line argument is determined by its position within the command line.

Parameters:

inArgsIndexMap - Mapping between setting names and their index, or position, in a command line.

See Also:

getArgsIndexMap(), createArgsArray(int), setArgsArray(String[]), getArgsArray()

getArgsIndexMap

protected java.util.ResourceBundle getArgsIndexMap()

Retrieve the argument index map for a command line argument string. This is needed when the meaning of each command line argument is determined by its position within the command line.

Returns:

The ResourceBundle that define the mapping between parameter names and their index, or position, in the command line.

See Also:

setArgsIndexMap(ResourceBundle), createArgsArray(int), setArgsArray(String[]), getArgsArray()

setAppSettings

public void setAppSettings(org.w3c.dom.Element inAppSettings)

Set the root of the ACCLIP document for the current technology that the SetterLauncher is processing. This root contains both the generic and application specific preferences for one type of technology (e.g., the "screenReader" root). The root element can change as the SetterLauncher processes preferences for different types of technology.

Parameters:

inAppSettings - The subtree of the settings that contain the generic and application specific preferences.

See Also:

getAppSettings()

getAppSettings

public org.w3c.dom.Element getAppSettings()

Retrieve the root of the ACCLIP DOM for the current technology that this SetterLauncher is processing. This root contains both the generic and application specific preferences for one type of technology (e.g., the "screenReader" root). The root element can change as the SetterLauncher processes preferences for different types of technology.

Returns:

The subtree of the preferences document as an org.w3c.dom.Element.

See Also:

setAppSettings(Element)

setControlHub

public void setControlHub(ControlHub inControlHub)

Set the Control Hub property. The Control Hub is used to retrieve properties of the plug-in.

Parameters:

inControlHub - The ControlHub instance that is controlling the system.

See Also:

getControlHub()

getControlHub

public ControlHub getControlHub()

Get the Control Hub property. The Control Hub is used to retrieve properties of the plug-in.

Returns:

The ControlHub instance that is controlling the system. Note that this can be null if setControlHub() was not called.

See Also:

setControlHub(ControlHub)

setAppID

public void setAppID(java.lang.String inAppID)

Set the application ID for the SetterLauncher. Typicially, this is acquired from the ACCLIP specific settings container element.

Parameters:

inAppID - The application ID.

See Also:

setAppID(Element), getAppID()

getAppID

public java.lang.String getAppID()

Retrieve the application ID for the SetterLauncher.

Returns:

The application ID as a String. Note that this can be null if the property was not set by setAppID().

See Also:

setAppID(String), setAppID(Element)

setAppID

protected void setAppID(org.w3c.dom.Element in3rdPartyPrefs)

Set the application ID for this SetterLauncher based on an application preferences element from the ACCLIP.

Parameters:

in3rdPartyPrefs - An application preferences Element; its name attribute is used to set the application ID.

See Also:

setAppID(String), getAppID()

setProcess

protected void setProcess(java.lang.Process inProcess)

Set the process launched by this SetterLauncher. Typically, the process is created as a result of doLaunch().

Parameters:

inProcess - The Process.

See Also:

SetterLauncher.doLaunch(), getProcess()

getProcess

protected java.lang.Process getProcess()

Retrieve the process launched by this SetterLauncher. Typically, the process is created as a result of doLaunch().

Returns:

The Process.

See Also:

SetterLauncher.doLaunch(), setProcess(Process).

loopThruGenerics

protected void loopThruGenerics(java.lang.String inTechType,
                                org.w3c.dom.Element inGenericContainer)

Loop through the generic preferences from the ACCLIP for the given type of technology. As the preference elements are encountered, handle them via a call to handlePref(). Sub-classes that wish to handle the generics differently should either not call this method, override it to do something else, or override handlePref() to handle them differently.

Parameters:

inTechType - The type of technology the given generic preferences are for expressed in the ACCLIP's vocabulary (e.g. "screenReader").

inGenericContainer - The parent generic Element, (e.g. "screenReaderGeneric").

See Also:

handlePref(String,Element,boolean)

loopThru3rdPartyPrefs

protected void loopThru3rdPartyPrefs(java.lang.String inTechType,
                                     org.w3c.dom.Element in3rdPartyPrefs)

Loop thru the specific preferences for the given type of technology. As each is encountered, it calls handlePref(), passing the child element, and indicating it is not a generic preference.

Parameters:

inTechType - The type of technology the application specific preferences are for, as taken from the ACCLIP (e.g. "screenReader").

in3rdPartyPrefs - The <application> container element for specific preferences.

See Also:

handlePref(String,Element,boolean)

handlePref

protected void handlePref(java.lang.String inTechType,
                          org.w3c.dom.Element inPref)

Given a technology type and a preference for that type, determine if it is one that this SetterLauncher handles. If so, write out its technology specific value. This simply calls the other version of handlePref() with false (this preference is not a generic preference).

Parameters:

inTechType - The type of technology this preference is for, as taken from the ACCLIP (e.g. "screenReader").

inPref - The preference Element from the preferences that represents a single setting.

See Also:

handlePref(String,Element,boolean)

handlePref

protected void handlePref(java.lang.String inTechType,
                          org.w3c.dom.Element inPref,
                          boolean isGeneric)

Given a technology type and a preference for that type, determine if it is one that this SetterLauncher handles. If so, write out its technology specific value via a call to doWriteSetting(). This also sets the parameter's written state to true.

This method is useful for the simple case of a straight match between the ACCLIP preference and the technology's parameter value (i.e. no hierarchical nesting of preferences, nor exclusive-or with respect to a containing Element).

Parameters:

inTechType - The type of technology these generic preferences are for, as taken from the ACCLIP (e.g. "screenReader").

inPref - The pref Element from the preferences that represents a single setting.

isGeneric - Did the preference come from the generic container in the ACCLIP? This is passed to findParameter().

See Also:

handlePref(String,Element), findParameter(String,String,boolean), doWriteSetting(String,String)

findParameter

public ParameterState findParameter(java.lang.String inTechType,
                                    java.lang.String inAccLipPrefName)

Given a type of technology and a preference name from the ACCLIP, determine if it is a parameter this plug-in handles. If so, return that preference's ParameterState instance. Otherwise, return null. This method is a convenience for calling the full version of findParameter() -- this passes false to indicate that the preference is not a generic preference.

Parameters:

inTechType - The type of technology this preference are for, as taken from the ACCLIP (e.g. "screenReader").

inAccLipPrefName - String representing the preference found in the ACCLIP.

Returns:

A ParameterState instance for this preference, or null if this technology does not handle this preference.

See Also:

ParameterState, findParameter(String,String,boolean)

findParameter

public ParameterState findParameter(java.lang.String inTechType,
                                    java.lang.String inAccLipPrefName,
                                    boolean isGeneric)

Given a type of technology and a preference name from the ACCLIP document, determine if it is a parameter this technology handles. If so, return that preference's ParameterState instance. Otherwise, return null. Note that this method only handles generic preferences at this level in the derivation hierarchy. Sub-classes should override to handle specfic preferences.

Parameters:

inTechType - The type of technology this preference are for, as taken from taken from the ACCLIP (e.g. "screenReader").

inAccLipPrefName - String representing the preference found in the ACCLIP.

isGeneric - Did the preference come from the generic container in the ACCLIP? This is ignored.

Returns:

A ParameterState instance for this preference, or null if this technology does not handle this preference.

See Also:

ParameterState, findParameter(String,String)

getValueValue

public java.lang.String getValueValue(org.w3c.dom.Element inPref)

Given a prefs element, find its Web4AllConstansts.VAL_ATT attribute and return the value of that attribute.

Parameters:

inPref - The preference Element whose value attribute is sought.

Returns:

The attribute value as a String, or null if none is found.

See Also:

Web4AllConstants.VAL_ATT

mapValue

protected java.lang.String mapValue(java.lang.String inParam,
                                    java.lang.String inValue)

Map the value retrieved from the preferences document to the parameter's value.

Parameters:

inParam - The parameter of interest. This is expressed using the technology's vocabulary.

inValue - The value from the ACCLIP.

Returns:

The value to of the parameter, as a String.

See Also:

linearCalcTechVal(String,float,float)

linearCalcTechVal

public float linearCalcTechVal(java.lang.String inAccLipVal,
                               float inSlope,
                               float inIntercept)

Utility to convert a floating point ACCLIP preference value to a parameter value. This performs a linear transformation.

Parameters:

inAccLipVal - Floating point value from the ACCLIP.

inSlope - A float that represents the slope of the line.

inIntercept - A float that represents the y-intercept of the line.

Returns:

A float that represents the parameter's value.

See Also:

mapValue(String,String)

handleUnwrittenParams

protected void handleUnwrittenParams(java.lang.String inTechType)

Write out default values for those preferences that were not in the ACCLIP document. This is done only if:

• there are parameters to write,
• the specific technology requires that those parameters be set,
• they have default values.

Parameters:

inTechType - The type of technology that this is configuring, expressed using the ACCLIP vocabulary.

doWriteSetting

protected abstract void doWriteSetting(java.lang.String inParameter,
                                       java.lang.String inValue)

Abstract method for "writing" the setting. This could be writing the setting to a file, or adding it as a command line arugment. Sub-classes must override to have this do what they require.

Parameters:

inParameter - The parameter to "write".

inValue - The value of the parameter.

See Also:

writeSetting(String,String), writeSetting(String,int), writeSetting(String,Number), addArgToArray(String,String)

writeSetting

protected void writeSetting(java.lang.String inParameter,
                            java.lang.String inValue)

Write the given paramater and its value. It is assumed that the output is valid; that is, that createOutputFile() was called at some point prior to this method.

Parameters:

inParameter - String representing the parameter to write.

inValue - String representing the value of inParameter.

See Also:

createOutput(String,String), createOutput(String,String,boolean), createOutput(String), doWriteSetting(String,String), writeSetting(String,int), writeSetting(String,Number)

writeSetting

protected void writeSetting(java.lang.String inParameter,
                            int inValue)

Write the given paramater and its value. It is assumed that the output is valid; that is, that createOutputFile() was called at some point prior to this method.

Parameters:

inParameter - String representing the parameter to write.

inValue - An int representing the value of inParameter.

See Also:

createOutput(String,String), createOutput(String,String,boolean), createOutput(String), doWriteSetting(String,String), writeSetting(String,String), writeSetting(String,Number)

writeSetting

protected void writeSetting(java.lang.String inParameter,
                            java.lang.Number inValue)

Write the given paramater and its value. It is assumed that the output is valid; that is, that createOutputFile() was called at some point prior to this method.

Parameters:

inParameter - String representing the parameter to write.

inValue - Number representing the value of inParameter.

See Also:

createOutput(String,String), createOutput(String,String,boolean), createOutput(String), doWriteSetting(String,String), writeSetting(String,String), writeSetting(String,int)

addArgToArray

protected void addArgToArray(java.lang.String inParameter,
                             java.lang.String inValue)

Add the given parameter's value to the command line argument array. Note that this assumes the argument array and argument index map are valid; that is, that either createArgsArray() or setArgsArray(), and setArgsIndexMap() were used to initialize the command line argument arrays.

Parameters:

inParameter - The parameter to write.

inValue - The value of inParameter.

See Also:

createArgsArray(int), setArgsArray(String[]), setArgsIndexMap(ResourceBundle)

createReadProcessIStreams

protected void createReadProcessIStreams()

Allocate the ReadProcessIStreams object, if desired. The ReadProcessIStreams captures and a Process's input stream(s) content. Sub-classes can make use of this as needed.

See Also:

ReadProcessIStreams, handleProcessIStreams(Process), handleProcessIStreams(Process,boolean)

handleProcessIStreams

protected void handleProcessIStreams(java.lang.Process inProcess)

Activate the ReadProcessIStreams object. In this case, the ReadProcessIStreams is configured to capture and dispose of a Process's input stream(s) content. Sub-classes can make use of this as needed.

Parameters:

inProcess - The Process whose InputStreams are to read.

See Also:

ReadProcessIStreams, createReadProcessIStreams(), handleProcessIStreams(Process,boolean)

handleProcessIStreams

protected void handleProcessIStreams(java.lang.Process inProcess,
                                     boolean logFlag)

Activate the ReadProcessIStreams object. In this case, the ReadProcessIStreams is configured to capture and log a Process's input stream(s) content. Sub-classes can make use of this as needed.

Parameters:

inProcess - The Process whose InputStreams are to read.

logFlag - If true the contents of the InputStreams are written to the ConfigManager's log file.

See Also:

ReadProcessIStreams, createReadProcessIStreams(), handleProcessIStreams(Process)

getLocalProperty

protected java.lang.String getLocalProperty(java.lang.String inPropName)
                                     throws java.util.MissingResourceException

Retrieve one of the plug-in's local properties. Use only after initializing the local properties via initLocalProps() -- this checks to see if the local properties have been initialized, and, if not, throws a MissingResourceException. If they have been initialized, then the desired property is retrieved. If the property does not exist, a MissingResourceException is thrown.

Parameters:

inPropName - Name of the property to be retrieved.

Returns:

The property value.

Throws:

java.util.MissingResourceException - Occurs if the local properties have not been initialized, or the given property is not known.

See Also:

initLocalProps()

kill

public void kill()

Basic implementation of the SetterLauncher kill method. If there is a valid Process, then it is destroyed; otherwise do nothing. Sub-classes should override to first reset the technology's settings to some default state before actually killing the Process.

Specified by:

kill in interface SetterLauncher

See Also:

SetterLauncher.doLaunch()

initLocalProps

public boolean initLocalProps()

Basic implementation for acquiring the local properties of the plug-in. The properties are assumed to be held by the Control Hub, which is acquired via getControlHub(). The properties are stored as a java.util.ResourceBundle. If such a bundle does not exist, this will fail.

Specified by:

initLocalProps in interface SetterLauncher

Returns:

A flag to indicate success/failure in acquiring the local properties.

See Also:

getControlHub(), getLocalProperty(String), ControlHub.get3rdPartyProperties(String)