javax.speech.recognition
Interface FinalRuleResult

All Superinterfaces:

FinalResult, Result

public interface FinalRuleResult
extends FinalResult

Provides information on a finalized Result for an utterance that matches a RuleGrammar.

A finalized Result is a Result that has received a RESULT_ACCEPTED or RESULT_REJECTED event that puts it in either the ACCEPTED or REJECTED state as indicated by the getResultState method.

The methods this interface should only be called on a finalized Result object if the Result.getGrammar method returns a RuleGrammar. Otherwise, a ResultStateException is thrown.

Application Example

Say we have two RuleGrammars loaded and active for recognition. The first is "grammar:numbers" with a root Rule "digits" that matches spoken digit sequences (for example, "1 2 3 4"). The second is "grammar:food" with the root Rule "whoAteWhat" that matches statements about eating (for example, "he ate mine").

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

 FinalRuleResult result = ...;
 result.getNumberAlternatives() -> 3
 
 result.getAlternativeTokens(0) -> {"two", "eight", "nine"}
 result.getRuleReference(0) -> new RuleReference("grammar:numbers", "digits")
 
 result.getAlternativeTokens(1) -> {"you", "ate", "mine"}
 result.getRuleName(1) -> new RuleReference("grammar:food", "whoAteWhat")
 
 result.getAlternativeTokens(2) -> {"two", "eight", "five"}
 result.getRuleName(2) -> new RuleReference("grammar:numbers", "digits")
 

See Also:

RuleGrammar, ACCEPTED, REJECTED, getResultState, getGrammar, RESULT_ACCEPTED, RESULT_REJECTED

Field Summary

Fields inherited from interface FinalResult

DONT_KNOW, MISRECOGNITION, USER_CHANGE

Fields inherited from interface Result

ACCEPTED, REJECTED, UNFINALIZED

Method Summary

RuleReference	getRuleReference(int nBest) Returns the RuleReference matched by the Nth-best alternative.
Object[]	getTags(int nBest) Returns the list of tags matched by the token sequence for the Nth-best alternative.
RuleParse	parse(int nBest) Returns the RuleParse corresponding to the Nth-best alternative.

Methods inherited from interface FinalResult

getAlternativeTokens, getAudio, getAudio, getConfidenceLevel, getConfidenceLevel, getGrammar, getNumberAlternatives, isAudioAvailable, isTrainingInfoAvailable, releaseAudio, releaseTrainingInfo, tokenCorrection

Methods inherited from interface Result

addResultListener, getBestToken, getBestTokens, getGrammar, getNumTokens, getResultState, getUnfinalizedTokens, removeResultListener

Method Detail

getRuleReference

RuleReference getRuleReference(int nBest)
                               throws ResultStateException,
                                      IllegalArgumentException,
                                      IllegalStateException

Returns the RuleReference matched by the Nth-best alternative.

The range for nBest is 0 to (getNumberAlternatives()-1), inclusive, where 0 represents the best alternative.

A REJECTED Result is not guaranteed to return a RuleReference and null may be returned instead.

This method uses Grammars committed with the last call to resume before Result finalization and throws an IllegalStateException if Grammar changes are subsequently committed by resume.

Parameters:

nBest - the Nth-Best index

Returns:

the RuleReference matched by the nBest alternative

Throws:

ResultStateException - if called before this Result is finalized

IllegalArgumentException - if nBest is not in range

IllegalStateException - if Grammar changes are subsequently committed by resume

See Also:

getNumberAlternatives, getAlternativeTokens, getGrammar, REJECTED, resume

getTags

Object[] getTags(int nBest)
                 throws ResultStateException,
                        IllegalArgumentException,
                        IllegalStateException

Returns the list of tags matched by the token sequence for the Nth-best alternative. Returns the empty list if no tags correspond to this alternative.

The range for nBest is 0 to (getNumberAlternatives()-1), inclusive, where 0 represents the best alternative.

A REJECTED Result is not guaranteed to return tags and an empty list may be returned instead.

This method uses Grammars committed with the last call to resume before Result finalization and throws an IllegalStateException if Grammar changes are subsequently committed by resume.

For a FinalRuleResult, the tags in the array are listed in the order in which they are encountered in the RuleGrammar.

For example, if the RuleGrammar contains the following root rule:

 <rule id='actionRule'>
   <one-of>
     <item> open <tag>ACT_OPEN</tag> </item>
     <item> close <tag>ACT_CLOSE</tag> </item>
   </one-of>
   <item repeat='0-1'>  <!-- optional -->
     <item> 
       it <tag>WHAT</tag> now <tag>NOW</tag>
     </item>
   </item>
 </rule>
 

and the user says "close it now", then getTags returns an array containing {"ACT_CLOSE", "WHAT", "NOW"}.

Tags in RuleGrammars created from markup text will always be Strings, but tags created with RuleTag can be any Object.

getTags does not indicate which tokens occur near which tags. Use the parse method to obtain this information.

This method behaves the same as parse(nBest).getTags(), but may be more efficient.

Specified by:

getTags in interface FinalResult

Parameters:

nBest - the Nth-Best index

Returns:

tags matched by the token sequence for the nBest alternative

Throws:

ResultStateException - if called before this Result is finalized

IllegalArgumentException - if nBest is not in range

IllegalStateException - if Grammar changes are subsequently committed by resume

See Also:

getNumberAlternatives, getBestTokens, parse, RuleParse.getTags, REJECTED, resume

parse

RuleParse parse(int nBest)
                throws ResultStateException,
                       IllegalArgumentException,
                       IllegalStateException

Returns the RuleParse corresponding to the Nth-best alternative.

The range for nBest is 0 to (getNumberAlternatives()-1), inclusive, where 0 represents the best alternative.

A REJECTED Result is not guaranteed to return a RuleParse and null may be returned instead.

This method is essentially the same as the RuleGrammar.parse method given the same nBest tokens and starting rule name. However, this method uses Grammars committed with the last call to resume before Result finalization and throws an IllegalStateException if subsequent Grammar changes are committed by resume.

Parameters:

nBest - the Nth-Best index

Returns:

a RuleParse corresponding to the nBest alternative or possibly null for a REJECTED Result.

Throws:

ResultStateException - if called before this Result is finalized

IllegalArgumentException - if nBest is not in range

IllegalStateException - if Grammar changes are subsequently committed by resume

See Also:

getNumberAlternatives, RuleGrammar.parse(String[],String), getAlternativeTokens, getRuleReference, REJECTED, resume