uk.ac.starlink.ttools.join

Class MatchEngineParameter

java.lang.Object

uk.ac.starlink.task.Parameter<MatchEngine>

uk.ac.starlink.ttools.join.MatchEngineParameter

All Implemented Interfaces:

ExtraParameter

public class MatchEngineParameter
extends Parameter<MatchEngine>
implements ExtraParameter

Parameter for acquiring a MatchEngine.

Since:

2 Sep 2005

Author:

Mark Taylor

Field Summary

Fields inherited from class uk.ac.starlink.task.Parameter

BY_NAME

Constructor Summary

Constructors

Constructor and Description
MatchEngineParameter(String name)

Method Summary

Modifier and Type	Method and Description
static void	configureTupleParameter(WordsParameter<String> tupleParam, MatchEngine matcher) Configures a tuple parameter for use with a given MatchEngine.
MatchEngine	createEngine(String name) Returns a new, unconfigured match engine given a short naming string.
WordsParameter<String>	createMatchTupleParameter(String numLabel) Creates a new parameter for specifying value tuples for a table, suitable for use with this one.
String	getConfigUsage(MatchEngine engine, Parameter<String[]> wordsParam, DescribedValue[] configs) Returns a string giving the usage for a parameter with configuration subparameters.
static String[]	getExampleValues() Returns strings naming a set of example match engine parameter values.
String	getExtraUsage(TableEnvironment env) Returns an extended usage message.
static String	getInfoUsage(ValueInfo info) Returns a usage fragment appropriate to specifying a value on the command line in accordance with the metadata given in a ValueInfo object.
Parameter<String[]>	getMatchParametersParameter() Returns the associated parameter which is used for specifying the fixed value parameters for the engine supplied by this parameter.
ValueInfo	getScoreInfo(Environment env) Returns the match score metadata associated with this parameter.
Parameter<String>	getScoreParameter() Returns the associated parameter which is used for specifying the match score column metadata.
Parameter<String[]>	getTuningParametersParameter() Returns the associated parameter which is used for specifying optional tuning parameters for the engine supplied by this parameter.
String	getValuesUsage(MatchEngine engine, int startLeng) Returns a string giving the usage for the values parameter part of the matching command line.
MatchEngine	matchEngineValue(Environment env) Returns the value of this parameter as a MatchEngine.
MatchEngine	stringToObject(Environment env, String stringVal) Takes a non-blank string, as supplied by the execution environment, and turns it into a typed value for this parameter.

Methods inherited from class uk.ac.starlink.task.Parameter

clearValue, getDescription, getName, getPosition, getPreferExplicit, getPrompt, getStringDefault, getUsage, getValueClass, isNullPermitted, objectToString, objectValue, setDescription, setDescription, setName, setNullPermitted, setPosition, setPreferExplicit, setPrompt, setStringDefault, setUsage, setValue, setValueFromObject, setValueFromString, stringValue, toArray, toString

Methods inherited from class java.lang.Object

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

Constructor Detail

MatchEngineParameter

public MatchEngineParameter(String name)

Method Detail

getExtraUsage

public String getExtraUsage(TableEnvironment env)

Description copied from interface: ExtraParameter

Returns an extended usage message. This should not repeat the content of the normal usage message. It should be preformatted, that is it should contain newlines to keep the line length down to less than 80 characters.

Specified by:

getExtraUsage in interface ExtraParameter

Parameters:

env - execution envrionment

Returns:

extended usage message

getMatchParametersParameter

public Parameter<String[]> getMatchParametersParameter()

Returns the associated parameter which is used for specifying the fixed value parameters for the engine supplied by this parameter.

Returns:

params parameter

getTuningParametersParameter

public Parameter<String[]> getTuningParametersParameter()

Returns the associated parameter which is used for specifying optional tuning parameters for the engine supplied by this parameter.

Returns:

tuning parameter

getScoreParameter

public Parameter<String> getScoreParameter()

Returns the associated parameter which is used for specifying the match score column metadata. Do not interrogate this parameter directly - use getScoreInfo(uk.ac.starlink.task.Environment).

Returns:

match score parameter

getScoreInfo

public ValueInfo getScoreInfo(Environment env)
                       throws TaskException

Returns the match score metadata associated with this parameter.

Parameters:

env - execution environment

Returns:

match score metadata; may be null

Throws:

TaskException

createMatchTupleParameter

public WordsParameter<String> createMatchTupleParameter(String numLabel)

Creates a new parameter for specifying value tuples for a table, suitable for use with this one.

The supplied numLabel parameter distinguishes the parameter name if there are several; it is usually "1", "2", ... or "N" for a generic number or "" if there is only one. The autogenerated documentation will be adjusted accordingly.

Parameters:

numLabel - identifier for the new parameter

configureTupleParameter

public static void configureTupleParameter(WordsParameter<String> tupleParam,
                                           MatchEngine matcher)

Configures a tuple parameter for use with a given MatchEngine. Amongst other things, the required word count will be set, so that its WordsParameter.wordsValue(uk.ac.starlink.task.Environment) will return an array of the correct size for the match engine.

Parameters:

tupleParam - tuple parameter to interrogate, probably generated earlier by createMatchTupleParameter(java.lang.String)

matcher - match engine which will be used

matchEngineValue

public MatchEngine matchEngineValue(Environment env)
                             throws TaskException

Returns the value of this parameter as a MatchEngine.

Parameters:

env - execution environment

Returns:

match engine

Throws:

TaskException

stringToObject

public MatchEngine stringToObject(Environment env,
                                  String stringVal)
                           throws TaskException

Description copied from class: Parameter

Takes a non-blank string, as supplied by the execution environment, and turns it into a typed value for this parameter. This method also performs validation, so if the string value is unacceptable in any way, a ParameterValueException should be thrown.

It is an error to supply a null or empty string value.

If this method fails (throws a ParameterValueException) and if allowClassnameValue is set, then a subsequent attempt will be made to interpret the stringVal as the classname of a suitable class with a no-arg constructor.

Specified by:

stringToObject in class Parameter<MatchEngine>

Parameters:

env - execution environment; in most cases this is not required but for some purposes environment-specific characteristics may influence the result

stringVal - non-null, non-empty string value

Returns:

typed value

Throws:

TaskException

createEngine

public MatchEngine createEngine(String name)
                         throws UsageException

Returns a new, unconfigured match engine given a short naming string. Names may be separated by a '+', in which case a combined engine is returned.

Parameters:

name - label to select match engine type

Returns:

new match engine

Throws:

UsageException

getValuesUsage

public String getValuesUsage(MatchEngine engine,
                             int startLeng)

Returns a string giving the usage for the values parameter part of the matching command line.

Parameters:

engine - match engine

startLeng - running line length at which the values part begins on the output

Returns:

values usage - possibly empty, not null

getConfigUsage

public String getConfigUsage(MatchEngine engine,
                             Parameter<String[]> wordsParam,
                             DescribedValue[] configs)

Returns a string giving the usage for a parameter with configuration subparameters.

Parameters:

engine - match engine

wordsParam - parameter providing values for the subparameters

configs - modifiable subparameters

Returns:

params usage - possibly empty, not null

getInfoUsage

public static String getInfoUsage(ValueInfo info)

Returns a usage fragment appropriate to specifying a value on the command line in accordance with the metadata given in a ValueInfo object.

Parameters:

info - value metadata specification

Returns:

usage fragment

getExampleValues

public static String[] getExampleValues()

Returns strings naming a set of example match engine parameter values. These are used in the documentation.