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.FinalDictationResult

public abstract interface FinalDictationResult

extends FinalResult

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

The FinalDictationResult interface extends the Result and FinalResult interfaces with a single method. The getAlternativeTokens method provides access to alternative guesses for tokens in a dictation result.

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

See Also:

ACCEPTED, REJECTED, getResultState, DictationGrammar, Result, FinalResult, FinalRuleResult, ResultStateError

Method Summary

ResultToken[][]

getAlternativeTokens(ResultToken fromToken, ResultToken toToken, int max) Return a set of alternative token guesses for a single known token or sequence of tokens.

Method Detail

getAlternativeTokens

public ResultToken[][] getAlternativeTokens(ResultToken fromToken,
                                            ResultToken toToken,
                                            int max)
                                                             throws ResultStateError,
                                                                    IllegalArgumentException

Return a set of alternative token guesses for a single known token or sequence of tokens. In a dictation application the alternative guesses are typically provided to a user to facilitate efficient correction of dictated text. The assumption is that if a recognizer does not correctly hear a user (a mis-recognition) the correct tokens are likely to be amongst the top alternatives guesses.

Typically when a user selects one of the alternative guesses as the correct token sequence, the tokenCorrection method of the FinalResult interface is called with those tokens. That call allows the Recognizer to learn from recognition errors and can improve future recognition accuarcy.

The fromToken and toToken parameters define an inclusive set of tokens for which alternatives are required. fromToken and toToken are typically included in the set of alternative guesses. If toToken is null or if fromToken and toToken are the same, then alternatives are provided for the single toToken token.

The tokens passed to this method must be ResultToken objects provided by this result through previous calls to getAlternativeTokens or the getBestToken and getBestTokens methods of the Result interface.

Returned Array Structure

The return value is a ragged two-dimension array with indices being altTokens[guessNumber][tokenNumber]. The guesses are ordered by from best guess to least likely (determined by the recognizer): altTokens[0] is the best guess for the span of fromToken to toToken, altTokens[1] is the first alternative guess and so on.

The number of tokens may be different in each alternative guess. This means that the length of altTokens[0] may be different from the length of altTokens[1] and so on. The length is never zero or less. (This point is illustrated in the example below.)

The max parameter indicates the maximum number of alternative guesses to be returned. The number of guesses returned may be less than or equal to max. The number of alternatives returned is also less than or equal to the NumResultAlternatives property set in the RecognizerProperties at the time of recognition.

The number of alternative guesses and the number of tokens in each guess can vary between results. The numbers can vary for different values of fromToken and toToken for the calls to the same result.

The returned alternative guess is always an array of length one or greater. If there is only one guess, it may be the sequence of fromToken to toToken tokens. Each guess always contains one or more tokens. If the result is ACCEPTED then the recognizer is confident that all the alternatives guesses are reasonable guesses of what the user said.

Example

Assume the user says "You can recognize speech" and that the recognizer accepts a result and hears the utterance correctly. The result will have four tokens (Result.numTokens() == 4) and the best guess tokens returned by the Result.getBestTokens() method returns and array with {"you", "can", "recognize", "speech"}. (The Result.getBestToken(int index) method will return the tokens one at a time.)

Let's take the second and last tokens ("can" and "speech") and request five alternative guesses for the sequence including those tokens:

      FinalDictationResult result;
      ResultToken secondToken = result.getBestToken(1);
      ResultToken lastToken = result.getBestToken(result.numTokens());
      ResultToken[][] altTokens = result.getAlternativeTokens(secondToken, lastToken, 5);
 

The return value might look like the following (representing each token by its written-form string):

   altTokens = { {"can", "recognize", "speech"},
                 {"can", "wreck", "a", "nice", "beach"},
                 {"in", "recognize", "beach"},
                 {"recognize", "speech"} }
 

Some observations from this example which illustrate the points described above.

• Only 4 guesses are returned, less than 5 guesses requested in the getAlternativeTokens call.
• The first token sequence is the same as the best guess as returned by the getBestTokens method. (As we expected, "can recognize speech" is the recognizer's best guess for that segment of incoming speech.)
• The number of tokens is different between guesses: 3, 5, 3, 2 tokens in each.

Throws:

ResultStateError - if called before a result is finalized or if the matched grammar is not a DictationGrammar

IllegalArgumentException - if passed a ResultToken not obtained from this result

See Also:

Result, numTokens, getBestToken, getBestTokens, tokenCorrection, setNumResultAlternatives