javax.speech.recognition
Class RuleAlternatives

Object
  RuleComponent
      RuleAlternatives

public class RuleAlternatives
extends RuleComponent

Represents a RuleComponent composed of a set of alternative RuleComponents. RuleAlternatives are used to construct RuleGrammar objects. A RuleAlternatives object is spoken by saying one, and only one, of its alternative RuleComponents.

A RuleAlternatives object contains a set of zero or more RuleComponent objects. A set of zero alternatives is equivalent to VOID (no matches). This accommodates the case where a Rule might contain "call" followed by a list of names, but the list of names is empty. With no valid alternatives following "call", the Rule as a whole will not match.

Weights may be (optionally) assigned to each alternative RuleComponent. The weights indicate the relative chance of each RuleComponent being spoken. If no weights are defined, then all alternatives are considered equally likely.

Traditional floating point weights may be converted to integer weights as follows: multiply by NORM_WEIGHT and then apply a ceiling of MAX_WEIGHT.

See Also:

VOID, NORM_WEIGHT, MAX_WEIGHT

Field Summary

static int	MAX_WEIGHT The maximum weight for a RuleComponent.
static int	MIN_WEIGHT A value for the weight corresponding to 0.0.
static int	NORM_WEIGHT A value for the weight corresponding to 1.0.

Constructor Summary

RuleAlternatives(RuleComponent[] ruleComponents)
Constructs a RuleAlternatives object from an array of alternative RuleComponents.

RuleAlternatives(RuleComponent[] ruleComponents, int[] weights)
Constructs a RuleAlternatives object with an array of alternative ruleComponents and a corresponding array of weights.

RuleAlternatives(String[] tokens)
Constructs a phrase list from an array of String objects.

Method Summary

RuleComponent[]	getRuleComponents() Returns the array of alternative RuleComponents.
int[]	getWeights() Returns weights for the corresponding alternative RuleComponents.
String	toString() Returns a String representing this RuleComponent as grammar text.

Methods inherited from class Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

MAX_WEIGHT

public static final int MAX_WEIGHT

The maximum weight for a RuleComponent.

See Also:

RuleAlternatives(RuleComponent[], int[]), Constant Field Values

MIN_WEIGHT

public static final int MIN_WEIGHT

A value for the weight corresponding to 0.0.

See Also:

RuleAlternatives(RuleComponent[], int[]), Constant Field Values

NORM_WEIGHT

public static final int NORM_WEIGHT

A value for the weight corresponding to 1.0.

See Also:

RuleAlternatives(RuleComponent[], int[]), Constant Field Values

Constructor Detail

RuleAlternatives

public RuleAlternatives(String[] tokens)

Constructs a phrase list from an array of String objects. Each String is used to create a single RuleToken object as an alternative.

A String containing multiple words (e.g. "San Francisco") is treated as a single token in a RuleToken. If appropriate, an application should parse a phrase alternative into separate RuleTokens to create a corresponding RuleSequence alternative.

All alternatives have equal weight. A zero-length tokens list results in a zero-length array of alternative RuleComponents that is equivalent to VOID (no matches).

Parameters:

tokens - a set of alternative tokens

Throws:

IllegalArgumentException - if null tokens

See Also:

RuleToken, RuleSequence, VOID, getRuleComponents, getWeights

RuleAlternatives

public RuleAlternatives(RuleComponent[] ruleComponents)
                 throws IllegalArgumentException

Constructs a RuleAlternatives object from an array of alternative RuleComponents. All alternative have equal weight. A zero-length set of alternatives is equivalent to VOID (no matches).

Parameters:

ruleComponents - the set of alternative RuleComponents

Throws:

IllegalArgumentException - if null ruleComponents

See Also:

VOID, getRuleComponents, getWeights

RuleAlternatives

public RuleAlternatives(RuleComponent[] ruleComponents,
                        int[] weights)
                 throws IllegalArgumentException

Constructs a RuleAlternatives object with an array of alternative ruleComponents and a corresponding array of weights. The ruleComponents array must not be null. A zero-length set of alternatives is equivalent to VOID (no matches).

If the weights array is non-null, it must have identical length to the ruleComponents array. If the weights array is null, all alternative ruleComponents have equal weight.

Weights specified must all be greater than or equal to MIN_WEIGHT and less than or equal to MAX_WEIGHT. At least one must be non-zero.

Parameters:

ruleComponents - the set of alternative RuleComponents

weights - the weight of each RuleComponent or null

Throws:

IllegalArgumentException - if null ruleComponents, mismatched array lengths, or bad weight values

See Also:

MIN_WEIGHT, NORM_WEIGHT, MAX_WEIGHT, VOID, getRuleComponents, getWeights

Method Detail

getRuleComponents

public RuleComponent[] getRuleComponents()

Returns the array of alternative RuleComponents.

A zero-length array is treated the same as VOID (no matches).

Returns:

the array of alternative RuleComponents.

See Also:

getWeights, VOID

getWeights

public int[] getWeights()

Returns weights for the corresponding alternative RuleComponents.

A null value is returned if the weights were not originally specified. This represents alternatives with equal weight. Otherwise, the length of the weights array is guaranteed to be the same length as the array of RuleComponents.

Returns:

an array of weights or null if not specified

See Also:

getRuleComponents

toString

public String toString()

Returns a String representing this RuleComponent as grammar text. The String represents a portion of a grammar that could appear on the right hand side of a Rule definition.

Note that an empty alternative list is represented as VOID.

Overrides:

toString in class RuleComponent

Returns:

printable String representing grammar text.

See Also:

VOID, RuleComponent, Rule