javax.speech.recognition
Interface Result

All Known Subinterfaces:

FinalResult, FinalRuleResult

public interface Result

A Result is issued by a Recognizer as it recognizes an incoming utterance that matches an active Grammar. It is obtained by casting ResultEvent.getSource to a Result:

 Result result = (Result) resultEvent.getSource();
 

The Result interface provides the application with access to the following information about a recognized utterance:

• A sequence of finalized tokens (words) that have been recognized,
• A sequence of unfinalized tokens,
• The Grammar matched by the Result, and
• The Result state: UNFINALIZED, ACCEPTED or REJECTED.

Multiple Result Interfaces

Every Result from a Recognizer implements the FinalResult and FinalRuleResult interfaces. These multiple interfaces are designed to explicitly indicate

• what information is available at what times in the Result life-cycle and
• what information is available for different types of Results.

Appropriate casting of Results allows compile-time checking of Result-handling code and fewer bugs.

The FinalResult interface provides access to the additional information about a Result that is available once it has been finalized (once it becomes ACCEPTED or REJECTED). Calling any method of the FinalResult interface for a Result in the UNFINALIZED state causes a ResultStateException.

The FinalRuleResult interface provides access to the additional information about a finalized Result that matches a RuleGrammar. Calling any method of the FinalRuleResult interface for a non-finalized Result or a Result not from a RuleGrammar causes a ResultStateException.

Result States

The separate interfaces determine what information is available for a Result in the different stages of its life-cycle. The getResultState method returns one of the three possible states: UNFINALIZED, ACCEPTED and REJECTED.

A new Result starts in the UNFINALIZED state. When the Result is finalized it moves to either the ACCEPTED or REJECTED state. An ACCEPTED or REJECTED Result is termed a finalized Result. All values and information regarding a finalized Result are fixed (except that audio and training information may be released).

The descriptions for each state contain more information.

Recognizer States and Result States

The state system of a Recognizer is linked to the state of recognition of the current Result. The Recognizer interface documents the typical event cycle for a Recognizer and for Results. The following is an overview of the ways in which the two state systems are linked:

• The RESUMED state of a Recognizer has two substates. In the LISTENING substate, the Recognizer is listening to audio and no Result being produced. In the PROCESSING substate, the Recognizer has detected incoming audio that may match an active Grammar and produce a Result.
• The Recognizer moves from the LISTENING substate to the PROCESSING substate with a RECOGNIZER_PROCESSING event immediately prior to issuing a RESULT_CREATED event.
• The RESULT_UPDATED and GRAMMAR_FINALIZED events are produced while the Recognizer is in the PROCESSING substate.
• The Recognizer finalizes a Result with RESULT_ACCEPTED or RESULT_REJECTED event immediately after it transitions from the PROCESSING substate to the PAUSED state with an ENGINE_PAUSED event.
• Unless there is an additional call to pause, the Recognizer will resume with an ENGINE_RESUMED event after calling ResultListeners. This commits Grammar changes with a CHANGES_COMMITTED/ CHANGES_REJECTED event and starts the LISTENING cycle gain.
• The TRAINING_INFO_RELEASED and AUDIO_RELEASED events can occur in any state of an ALLOCATED Recognizer.

ACCEPTED and REJECTED Results

A REJECTED Result indicates that the Recognizer is not confident that it has accurately recognized what a user said. Rejection can be controlled through the RecognizerProperties interface with the setConfidenceThreshold method. Increasing the confidence level requires the Recognizer to have greater confidence to accept a Result, so more Results are likely to be REJECTED.

An ACCEPTED(vs. REJECTED) Result does not mean the Result is correct. Instead, it implies that the Recognizer has a sufficient level of confidence that the Result is correct.

It is difficult for Recognizers to reliably determine when they make mistakes. Applications need to determine the cost of incorrect recognition of any particular Results and take appropriate actions. For example, confirm with a user that they said "delete all contacts" before deleting anything.

Result Events

ResultEvents are issued when a new Result is created and when there is any change in the state or information content of a Result. The following describes the event sequence for an ACCEPTED Result. It provides the same information as above for Result states, but focuses on legal event sequences.

Before a new Result is created for incoming speech, a Recognizer issues a SPEECH_STARTED event.

A newly created Result is provided to the application through the RESULT_CREATED event by calling the ResultEvent.getSource method. The new Result may or may not have any finalized or unfinalized tokens.

At any time following the RESULT_CREATED event, an application may attach a ResultListener to an individual Result. That listener will receive all subsequent events associated with that Result.

A new Result is created in the UNFINALIZED state. In this state, zero or more RESULT_UPDATED events may be issued to each ResultListener attached to the Recognizer and attached to that Result. The RESULT_UPDATED indicates that one or more tokens have been finalized, or that the unfinalized tokens have changed, or both.

When the Recognizer determines which Grammar is the best match for incoming speech, it issues a GRAMMAR_FINALIZED event. This event is issued to each ResultListener attached to the Recognizer and attached to that Result.

The GRAMMAR_FINALIZED event is also issued to each ResultListener attached to the matched Grammar. This is the first ResultEvent received by ResultListeners attached to the Grammar. All subsequent ResultEvents are issued to all attached ResultListeners.

Zero or more RESULT_UPDATED events may be issued after the GRAMMAR_FINALIZED event but before the Result is finalized.

Once the Recognizer completes recognition of the Result that it chooses to accept, it finalizes the result with a RESULT_ACCEPTED event that is issued to all attached ResultListeners. This event may also indicate finalization of zero or more tokens, and/or the resetting of the unfinalized tokens to null. The Result finalization event occurs immediately after the Recognizer makes a transition from the PROCESSING substate to the PAUSED state with an ENGINE_PAUSED event.

A finalized Result may issue an AUDIO_RELEASED or TRAINING_INFO_RELEASED event. These events may be issued in response to relevant release methods of FinalResult or may be issued when the Recognizer independently decides to release audio or training information.

When a Result is REJECTED, some of the events described above may be skipped. At any time after a RESULT_CREATED event, a result may become REJECTED with the RESULT_REJECTED event. A Result may be REJECTED with or without any unfinalized or finalized tokens being created (no RESULT_UPDATED events), and with or without a GRAMMAR_FINALIZED event.

Start and End of Results

A new Result object is created when a Recognizer has detected possible incoming speech which may match an active Grammar.

To accept the Result (that is, to issue a RESULT_ACCEPTED event), the token sequence from the best Result must match the token patterns defined by the matched Grammar. For a RuleGrammar this implies that a call to the parse method of the matched RuleGrammar must return successfully.

The following conditions apply to all finalized Results:

• N-best alternatives available through the FinalResult interface cannot cross Result boundaries.
• Correction/training is only possible within a single Result object.

See Also:

FinalResult, FinalRuleResult, ResultEvent, ResultListener, ResultStateException, Grammar, RuleGrammar, RecognizerEvent, setConfidenceThreshold

Field Summary

static int	ACCEPTED A state indicating that recognition of the Result is completed and has been finalized by being accepted.
static int	REJECTED A state indicating that recognition of the Result is complete and has been finalized by being rejected.
static int	UNFINALIZED A state indicating that a Result is still being recognized.

Method Summary

void	addResultListener(ResultListener listener) Requests notifications of ResultEvents related to this Result.
ResultToken	getBestToken(int tokNum) Returns the Nth finalized token from the best Result alternative.
ResultToken[]	getBestTokens() Returns the finalized token sequence for the best Result alternative.
Grammar	getGrammar() Returns the Grammar matched by the finalized tokens of the best Result alternative or null if the Grammar is not known.
int	getNumTokens() Returns the number of finalized tokens in the best Result alternative.
int	getResultState() Returns the current state of the Result object.
ResultToken[]	getUnfinalizedTokens() Returns the current unfinalized tokens following the current finalized tokens.
void	removeResultListener(ResultListener listener) Removes a ResultListener from this Result.

Field Detail

UNFINALIZED

static final int UNFINALIZED

A state indicating that a Result is still being recognized. A Result is in the UNFINALIZED state when the RESULT_CREATED event is issued. getResultState returns UNFINALIZED while a Result is still being recognized. A Result remains in the UNFINALIZED state until it is finalized by either a RESULT_ACCEPTED or RESULT_REJECTED event.

In the UNFINALIZED state:

• Calls to the methods of the FinalResult and FinalRuleResult interfaces result in ResultStateExceptions.
• Zero or more RESULT_UPDATED events may be issued as
  • as tokens are finalized, or
  • as the unfinalized tokens change.
• One GRAMMAR_FINALIZED event must be issued in the UNFINALIZED state before Result finalization by a RESULT_ACCEPTED event. The GRAMMAR_FINALIZED event is optional if the Result is finalized by a RESULT_REJECTED event - it is not always possible for a Recognizer to identify a best-match Grammar for a REJECTED Result.
• getNumTokens returns the number of finalized tokens and this number may increase as RESULT_UPDATED events are issued.
• getUnfinalizedTokens may return zero or more tokens and these may change at any time when a RESULT_UPDATED event is issued.

See Also:

getResultState, RESULT_CREATED, RESULT_UPDATED, RESULT_ACCEPTED, RESULT_REJECTED, GRAMMAR_FINALIZED, FinalResult, FinalRuleResult, getNumTokens, getUnfinalizedTokens, Constant Field Values

ACCEPTED

static final int ACCEPTED

A state indicating that recognition of the Result is completed and has been finalized by being accepted. When a Result changes to the ACCEPTED state, a RESULT_ACCEPTED event is issued.

In the ACCEPTED state:

• Recognition of the Result is complete and the Recognizer is confident it has the correct Result (not a REJECTED Result). The ACCEPTED state is not a guarantee of a correct Result - only sufficient confidence that the Result is correct.
• AUDIO_RELEASED and TRAINING_INFO_RELEASED events may optionally occur optionally.
• getNumTokens will return 1 or greater (there must be at least one finalized token) and the number of finalized tokens will not change.
• Each token within the best finalized token sequence is available through getBestToken. These tokens are guaranteed not to change through the remaining life of the Result.
• getUnfinalizedTokens returns a zero-length array.
• getGrammar returns the Grammar matched by this Result.
• The methods of FinalResult and FinalRuleResult (for a RuleGrammar) may be used.

See Also:

getResultState, RESULT_ACCEPTED, AUDIO_RELEASED, TRAINING_INFO_RELEASED, getNumTokens, getBestToken, getUnfinalizedTokens, getGrammar, FinalResult, FinalRuleResult, Constant Field Values

REJECTED

static final int REJECTED

A state indicating that recognition of the Result is complete and has been finalized by being rejected. When a Result changes to the REJECTED state, a RESULT_REJECTED event is issued.

In the REJECTED state

• The Results are most likely incorrect.
• AUDIO_RELEASED and TRAINING_INFO_RELEASED events may optionally occur.
• getNumTokens will return 0 or greater and the number of finalized tokens will not change.
• Each token within the best finalized token sequence is available through getBestToken. These tokens are guaranteed not to change through the remaining life of the Result.
• getUnfinalizedTokens method returns a zero-length array.
• If GRAMMAR_FINALIZED was issued, getGrammar returns the Grammar matched by this Result. If available, the Grammar is most likely not the correct one.
• The methods of FinalResult may be used.
• If the Grammar is known and it is a RuleGrammar, the FinalRuleResult methods may be used, but the information is unlikely to be reliable.

See Also:

getResultState, RESULT_REJECTED, AUDIO_RELEASED, TRAINING_INFO_RELEASED, getNumTokens, getBestToken, getUnfinalizedTokens, getGrammar, FinalResult, FinalRuleResult, Constant Field Values

Method Detail

addResultListener

void addResultListener(ResultListener listener)

Requests notifications of ResultEvents related to this Result. An application can attach multiple ResultListeners to a Result. A listener can be removed with the removeResultListener method.

ResultListener objects can also be attached to a Recognizer and to any Grammar. A listener attached to a Recognizer receives all events for all Results produced by that Recognizer. A listener attached to a Grammar receives all events for all results that have been finalized for that Grammar (all events starting with and including the GRAMMAR_FINALIZED event).

A ResultListener attached to a Result only receives events following the point in time at which the listener is attached. Because the listener can only be attached during or after the RESULT_CREATED event, it will not receive the RESULT_CREATED event. Only ResultListeners attached to the Recognizer receive RESULT_CREATED events.

Parameters:

listener - a ResultListener

See Also:

ResultEvent, removeResultListener, addResultListener, addResultListener, GRAMMAR_FINALIZED, RESULT_CREATED

getBestToken

ResultToken getBestToken(int tokNum)
                         throws IllegalArgumentException

Returns the Nth finalized token from the best Result alternative. tokNum must be in the range 0 to getNumTokens()-1.

If the Result has no tokens (possible in both the UNFINALIZED and REJECTED states) an exception is thrown.

If the Result is in the REJECTED state, then the returned tokens are likely to be incorrect. In the ACCEPTED state, the Recognizer is confident that the tokens are correct but applications should consider the possibility that the tokens are incorrect.

The FinalResult interface provides a getAlternativeTokens method that returns alternative token sequences for finalized Results.

Parameters:

tokNum - index for the desired token.

Returns:

the Nth token from the best Result alternative

Throws:

IllegalArgumentException - if tokNum is out of range

See Also:

getNumTokens, getUnfinalizedTokens, getBestTokens, getAlternativeTokens, UNFINALIZED, ACCEPTED, REJECTED

getBestTokens

ResultToken[] getBestTokens()

Returns the finalized token sequence for the best Result alternative. If the Result has no finalized tokens, the return value is a zero-length array.

The number of finalized tokens can change in the UNFINALIZED state and upon entering the ACCEPTED and REJECTED states.

Returns:

the current finalized token sequence for the best Result alternative

See Also:

getBestToken, getUnfinalizedTokens, getAlternativeTokens, UNFINALIZED, ACCEPTED, REJECTED

getGrammar

Grammar getGrammar()

Returns the Grammar matched by the finalized tokens of the best Result alternative or null if the Grammar is not known. The return value is null before a GRAMMAR_FINALIZED event and non-null afterward.

The Grammar is guaranteed to be non-null for an ACCEPTED Result. The Grammar may be null or non-null for a REJECTED Result, depending upon whether a GRAMMAR_FINALIZED event was issued prior to finalization.

For a finalized Result, an application should determine the type of matched Grammar with an instanceof test. For a Result that matches a RuleGrammar, the methods of FinalRuleResult can be used. The methods of FinalResult can be used for a Result matching any kind of Grammar.

Example of testing the Grammar for the Result type:

 Result result;
 if (result.getGrammar() instanceof RuleGrammar)
     FinalRuleResult frr = (FinalRuleResult) result;
     ...
 }
 

Returns:

the Grammar matched by the finalized tokens of the best Result or null

See Also:

ACCEPTED, REJECTED, getResultState, GRAMMAR_FINALIZED, FinalResult, FinalRuleResult

getResultState

int getResultState()

Returns the current state of the Result object. The set of possible states are UNFINALIZED, ACCEPTED or REJECTED. The details of a Result in each state are described in the documentation for each state.

Returns:

the current state of this object

See Also:

UNFINALIZED, ACCEPTED, REJECTED

getUnfinalizedTokens

ResultToken[] getUnfinalizedTokens()

Returns the current unfinalized tokens following the current finalized tokens. Unfinalized tokens provide an indication of what a Recognizer is considering as possible recognition tokens for speech following the finalized tokens.

Unfinalized tokens can provide users with feedback on the recognition process. The array may be any length (zero or more tokens), the length may change at any time, and successive calls to getUnfinalizedTokens may return different tokens or even different numbers of tokens. When the unfinalized tokens are changed, a RESULT_UPDATED event is issued to the ResultListener. The RESULT_ACCEPTED and RESULT_REJECTED events finalize a Result and always guarantee that the return value is a zero-length array. A new Result created with a RESULT_CREATED event may contain zero or more tokens.

The returned array has length zero if there are currently no unfinalized tokens, if the Recognizer does not support unfinalized tokens, or after a Result is finalized (in the ACCEPTED or REJECTED state rather than the UNFINALIZED state).

Returns:

current unfinalized tokens following the finalized tokens

See Also:

isUnfinalizedChanged, ResultListener, RESULT_UPDATED, RESULT_ACCEPTED, RESULT_REJECTED, ACCEPTED, REJECTED, UNFINALIZED

getNumTokens

int getNumTokens()

Returns the number of finalized tokens in the best Result alternative. Tokens are numbered from 0 to getNumTokens()-1 and are obtained through the getBestToken and getBestTokens methods of this interface and the getAlternativeTokens method of the FinalResult interface for a finalized Result.

Starting from the RESULT_CREATED event and while the Result remains in the UNFINALIZED state, the number of finalized tokens may be zero or more and can increase as tokens are finalized. When one or more tokens are finalized in the UNFINALIZED state, a RESULT_UPDATED ResultEvent is issued where its isFinalizedChanged method returns true. The RESULT_ACCEPTED and RESULT_REJECTED events which finalize a Result can also indicate that one or more tokens have been finalized.

In the ACCEPTED and REJECTED states, getNumTokens indicates the total number of tokens that were finalized. The number of finalized tokens never changes in these states. An ACCEPTED result must have one or more finalized tokens. A REJECTED result may have zero or more tokens.

Returns:

the current number of finalized tokens in this Result

See Also:

RESULT_CREATED, RESULT_UPDATED, RESULT_ACCEPTED, RESULT_REJECTED, isFinalizedChanged, UNFINALIZED, ACCEPTED, REJECTED, getBestToken, getBestTokens, getAlternativeTokens

removeResultListener

void removeResultListener(ResultListener listener)

Removes a ResultListener from this Result.

Parameters:

listener - a ResultListener to remove

See Also:

addResultListener, removeResultListener, removeResultListener