Overview | Package | Class | Tree | Index | Help
PREV CLASS | NEXT CLASS	FRAMES | NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD	DETAIL: FIELD | CONSTR | METHOD

Interface javax.speech.recognition.FinalRuleResult

public abstract interface FinalRuleResult

extends FinalResult

Provides information on a finalized result for an utterance that matches a RuleGrammar. A finalized result is one that is in either the ACCEPTED or REJECTED state (tested by the getResultState method of the Result interface).

This interface provides the following information for a finalized result for a RuleGrammar (in addition to the information provided through the Result and FinalResult interfaces):

• N-best alternatives for the entire result. For each alternative guess the interface provides the token sequence and the names of the grammar and rule matched by the tokens.
• Tags for the best-guess result.

Every Result object provided by a Recognizer implements the FinalRuleResult and the FinalDictationResult interfaces (and by inheritence the FinalResult and Result interfaces). However, the methods of FinalRuleResult should only be called if the Result.getGrammar method returns a RuleGrammar and once the Result has been finalized with either an RESULT_ACCEPTED or RESULT_REJECTED event. Inappropriate calls will cause a ResultStateError.

See Also:

RuleGrammar, Result, FinalResult, FinalDictationResult, getResultState, getGrammar

Method Summary

ResultToken[]	getAlternativeTokens(int nBest) Get the N-best token sequence for this result.
int	getNumberGuesses() Return the number of guesses for this result.
RuleGrammar	getRuleGrammar(int nBest) Return the RuleGrammar matched by the nth guess.
String	getRuleName(int nBest) Return the RuleName matched by the nth guess.
String[]	getTags() Return the list of tags matched by the best-guess token sequence.

Method Detail

getNumberGuesses

public int getNumberGuesses()
                    throws ResultStateError

Return the number of guesses for this result. The guesses are numbered from 0 up. The 0th guess is the best guess for the result and provides the same tokens as the getBestTokens method of the Result interface.

If only the best guess is available (no alternatives) the return value is 1. If the result is was rejected (REJECTED state), the return value may be 0 if no tokens are available. If a best guess plus alternatives are available, the return value is greater than 1.

The integer parameter to the getAlternativeTokens, getRuleGrammar and getRuleName methods are indexed from 0 to (getNumberGuesses()-1).

Throws:

ResultStateError - if called before a result is finalized

See Also:

getBestTokens, REJECTED, getAlternativeTokens, getRuleGrammar, getRuleName

getAlternativeTokens

public ResultToken[] getAlternativeTokens(int nBest)
                                                           throws ResultStateError

Get the N-best token sequence for this result. The nBest value should be in the range of 0 to (getNumberGuesses()-1) inclusive. For out-of-range values, the method returns null.

If nBest==0, the method returns the best-guess sequence of tokens - identical to the token sequence returned by the getBestTokens method of the Result interface for the same object.

If nBest==1 (or 2, 3...) the method returns the 1st (2nd, 3rd...) alternative to the best guess.

The number of tokens for the best guess and the alternatives do not need to be the same.

The getRuleGrammar(int) and getRuleName(int) methods indicate which RuleGrammar and ruleName are matched by each alternative result sequence.

If the Result is in the ACCEPTED state (not rejected), then the best guess and all the alternatives are accepted. Moreover, each alternative set of tokens must be a legal match of the RuleGrammar and RuleName returned by the getRuleGrammar and getRuleName methods.

If the Result is in the REJECTED state (not accepted), the recognizer is not confident that the best guess or any of the alternatives are what the user said. Rejected guesses do not need to match the corresponding RuleGrammar and rule name.

Example

Say we have two simple grammars loaded and active for recognition. The first is grammar.numbers with a public rule digits that matches spoken digit sequences (e.g. "1 2 3 4"). The grammar is grammar.food with the rule whoAteWhat which matches statements about eating (e.g. "he ate mine"). [Yes, this is artificial!]

The user says "two eight nine" and the recognizer correctly recognizes the speech, but also provides 2 alternatives. The

  FinalRuleResult result = ...;
  result.getNumberGuesses() -> 3

  result.getAlternativeTokens(0) -> two eight nine // array of tokens
  result.getRuleGrammar(0) -> [reference to grammar.numbers]
  result.getRuleName(0) -> "digits"

  result.getAlternativeTokens(1) -> you ate mine
  result.getRuleGrammar(1) -> [reference to grammar.food]
  result.getRuleName(1) -> "whoAteWhat"

  result.getAlternativeTokens(2) -> two eight five
  result.getRuleGrammar(2) -> [reference to grammar.numbers]
  result.getRuleName(2) -> "digits"
 

Throws:

ResultStateError - if called before a result is finalized

See Also:

getRuleGrammar, getRuleName

getRuleGrammar

public RuleGrammar getRuleGrammar(int nBest)
                                                   throws ResultStateError

Return the RuleGrammar matched by the nth guess. Return null if nBest is out-of-range.

getRuleName returns the rule matched in the RuleGrammar. See the documentation for getAlternativeTokens for a description of how tokens, grammars and rules correspond.

An application can use the parse method of the matched grammar to analyse a result. e.g.

   int nBest = 2;
   FinalRuleResult res;
   RuleParse parse = res.getRuleGrammar(nbest).parse(
                              res.getAlternativeTokens(nBest), 
                              res.getRuleName(nBest));
 

Throws:

ResultStateError - if called before a result is finalized

See Also:

parse, getNumberGuesses, getAlternativeTokens, getRuleName

getRuleName

public String getRuleName(int nBest)
                            throws ResultStateError

Return the RuleName matched by the nth guess. Return null if nBest is out-of-range. Typically used in combination with getAlternativeTokens and getRuleGrammar which return the corresponding tokens and grammar.

The documentation for getAlternativeTokens shows and example result with alternatives.

Throws:

ResultStateError - if called before a result is finalized

See Also:

parse, getAlternativeTokens, getRuleGrammar

getTags

public String[] getTags()
                          throws ResultStateError

Return the list of tags matched by the best-guess token sequence. The tags in the array are ordered strictly in the left to right order in which they would appear in JSGF.

For example, if the following simple Java Speech Grammar Format (JSGF) rule is active:

   public  = (open {ACT_OPEN} | close {ACT_CLOSE}) [(it{WHAT} now) {NOW}];
 

and the user says "close it now", then getTags returns an array containing {"ACT_CLOSE", "WHAT", "NOW"}. Note how both the {WHAT} and {NOW} tags are attached starting from the word "it" but that {TAG} appears first in the array. In effect, when tags start at the same token, they are listed "bottom-up".

getTags does not indicate which tokens are matched by which tags. To obtain this information use the parse method of the RuleGrammar. Also, getTags only provides tags for the best guess. To get tags for the alternative guesses using parsing through the RuleGrammar.

The string array returned by the getTags method of the RuleParse object returned by parsing the best-guess token sequence will be the same as returned by this method.

Throws:

ResultStateError - if called before a result is finalized

See Also:

parse, getTags