Class javax.speech.recognition.ResultEvent


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

Class javax.speech.recognition.ResultEvent

java.lang.Object
  |
  +--java.util.EventObject
        |
        +--javax.speech.SpeechEvent
              |
              +--javax.speech.recognition.ResultEvent

public class ResultEvent
extends SpeechEvent

A ResultEvent is issued by a Result object to indicate changes in the recognized tokens and changes in state. An event is issued to all appropriate ResultListener objects. ResultListeners can be attached in three places:

A ResultListener attached to the Recognizer receives all events for all results produced by the recognizer.
A ResultListener attached to a Grammar receives all events for all results that have been finalized for that Grammar: the GRAMMAR_FINALIZED event and following events. (Note: it never receives a RESULT_CREATED event because that event always precedes GRAMMAR_FINALIZED).
A ResultListener attached to a Result receives all events for that result starting from the time at which the listener is attached. (Note: it never receives a RESULT_CREATED event because a listener can only be attached to a Result once a RESULT_CREATED event has already been issued.)

In all three forms of listener attachment, one listener can be attached to multiple objects, and multiple listeners can be attached to a single object.

The three states of a recognition result are described in the documentation for the Result interface and can be tested by the getResultState method of that interface. The RESULT_CREATED, RESULT_ACCEPTED and RESULT_REJECTED events indicate result state changes.

In brief, the three states are:

UNFINALIZED state: initial state of result indicating that recognition is still taking place. A new result is created in the UNFINALIZED state with a RESULT_CREATED event.
ACCEPTED state: the result is finalized and the recognizer is confident it has recognized the result correctly. The RESULT_ACCEPTED event indicates a state change from the UNFINALIZED state to the ACCEPTED state.
REJECTED state: the result is finalized but the recognizer is not confident it has recognized the result correctly. The RESULT_REJECTED event indicates a state change from the UNFINALIZED state to the REJECTED state.

The sequence of ResultEvents associated with a recognition result are described in the documentation for the Result interface.

In brief, the events that occur depend upon the Result state:

A RESULT_CREATED event creates a Result object. A new result is starts in the UNFINALIZED state.
UNFINALIZED state: RESULT_UPDATED events indicate a change in finalized and/or unfinalized tokens; a GRAMMAR_FINALIZED event indicates that the Grammar matched by this result has been identified.
The RESULT_ACCEPTED event finalizes a result by indicating a change in state from UNFINALIZED to ACCEPTED.
The RESULT_REJECTED event finalizes a result by indicating a change in state from UNFINALIZED to REJECTED.
In the finalized states - ACCEPTED and REJECTED - the AUDIO_RELEASED and TRAINING_INFO_RELEASED may be issued.

See Also:: Recognizer, Result, ResultListener, FinalResult, FinalRuleResult, FinalDictationResult, Serialized Form

Field Summary
static int	AUDIO_RELEASED `AUDIO_RELEASED` event is issued when the audio information associated with a `FinalResult` object is released.
static int	GRAMMAR_FINALIZED `GRAMMAR_FINALIZED` is issued when the `Grammar` matched by a `Result` is identified and finalized.
static int	RESULT_ACCEPTED `RESULT_ACCEPTED` event is issued when a `Result` is successfully finalized and indicates a state change from `UNFINALIZED` to `ACCEPTED`.
static int	RESULT_CREATED `RESULT_CREATED` is issued when a new `Result` is created.
static int	RESULT_REJECTED `RESULT_REJECTED` event is issued when a `Result` is unsuccessfully finalized and indicates a change from the `UNFINALIZED` state to the `REJECTED` state.
static int	RESULT_UPDATED `RESULT_UPDATED` is issued when one or more tokens of a `Result` are finalized or when the unfinalized tokens of a result are changed.
boolean	tokenFinalized True if the `ResultEvent` indicates that one or more tokens have been finalized.
static int	TRAINING_INFO_RELEASED `TRAINING_INFO_RELEASED` event is issued when the training information for a finaliized result is released.
boolean	unfinalizedTokensChanged True if the `ResultEvent` indicates that the unfinalized tokens have changed.

Fields inherited from class javax.speech.SpeechEvent
id

Fields inherited from class java.util.EventObject
source

Constructor Summary
ResultEvent(Result source, int id, boolean isTokenFinalized, boolean isUnfinalizedTokensChanged) Constructs a `ResultEvent` for a specified source `Result` and result event id.
ResultEvent(Result source, int id) Constructs a `ResultEvent` with an event type identifier.

Method Summary
boolean	isTokenFinalized() For `RESULT_CREATED`, `RESULT_UPDATED`, `RESULT_ACCEPTED` and `RESULT_REJECTED` events returns `true` if any tokens were finalized.
boolean	isUnfinalizedTokensChanged() For `RESULT_CREATED`, `RESULT_UPDATED`, `RESULT_ACCEPTED` and `RESULT_REJECTED` events returns `true` if the unfinalized tokens changed.
String	paramString() Returns a parameter string identifying this event.

Methods inherited from class javax.speech.SpeechEvent
getId, paramString, toString

Methods inherited from class java.util.EventObject
getSource, toString

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notifyAll, notify, toString, wait, wait, wait

Field Detail

RESULT_CREATED

public static final int RESULT_CREATED

RESULT_CREATED is issued when a new Result is created. The event is received by each ResultListener attached to the Recognizer.

When a result is created, it is in the UNFINALIZED state. When created the result may have zero or more finalized tokens and zero or more unfinalized tokens. The presence of finalized and unfinalized tokens is indicated by the isTokenFinalized and isUnfinalizedTokensChanged flags.

The RESULT_CREATED event follows the RECOGNIZER_PROCESSING event which transitions the Recognizer from the LISTENING state to the PROCESSING state.

See Also:: resultCreated, UNFINALIZED, PROCESSING, RECOGNIZER_PROCESSING, isTokenFinalized, isUnfinalizedTokensChanged

RESULT_UPDATED

public static final int RESULT_UPDATED

RESULT_UPDATED is issued when one or more tokens of a Result are finalized or when the unfinalized tokens of a result are changed. The isTokenFinalized and isUnfinalizedTokensChanged flags are set appropriately.

The RESULT_UPDATED event only occurs when a Result is in the UNFINALIZED state.

See Also:: isTokenFinalized, isUnfinalizedTokensChanged, UNFINALIZED, resultUpdated

GRAMMAR_FINALIZED

public static final int GRAMMAR_FINALIZED

GRAMMAR_FINALIZED is issued when the Grammar matched by a Result is identified and finalized. Before this event the getGrammar method of a Result returns null. Following the event it is guaranteed to return non-null and the grammar is guaranteed not to change.

The GRAMMAR_FINALIZED event only occurs for a Result is in the UNFINALIZED state.

A GRAMMAR_FINALIZED event does not affect finalized or unfinalized tokens.

See Also:: isTokenFinalized, isUnfinalizedTokensChanged, UNFINALIZED, grammarFinalized

RESULT_ACCEPTED

public static final int RESULT_ACCEPTED

RESULT_ACCEPTED event is issued when a Result is successfully finalized and indicates a state change from UNFINALIZED to ACCEPTED.

In the finalization transition, zero or more tokens may be finalized and the unfinalized tokens are set to null. The isTokenFinalized and isUnfinalizedTokensChanged flags are set appropriately.

Since the Result is finalized (accepted), the methods of FinalResult and either FinalRuleResult or FinalDictationResult can be used. (Use the getGrammar method of Result to determine the type of grammar matched.) Applications should use type casting to ensure that only the appropriate interfaces and method are used.

The RESULT_ACCEPTED event is issued after the Recognizer issues a RECOGNIZER_SUSPENDED event to transition from the PROCESSING state to the SUSPENDED state. Any changes made to grammars or the enabled state of grammars during the processing of the RESULT_ACCEPTED event are automatically committed once the RESULT_ACCEPTED event has been processed by all ResultListeners. Once those changes have been committed, the Recognizer returns to the LISTENING state with a CHANGES_COMMITTED event. A call to commitChanges is not required. (Except, if there is a call to suspend without a subsequent call to commitChanges, the Recognizer defers the commit until the commitChanges call is received.)

See Also:: resultAccepted, isTokenFinalized, isUnfinalizedTokensChanged, getResultState, getGrammar, SUSPENDED, RECOGNIZER_SUSPENDED

RESULT_REJECTED

public static final int RESULT_REJECTED

RESULT_REJECTED event is issued when a Result is unsuccessfully finalized and indicates a change from the UNFINALIZED state to the REJECTED state.

In the state transition, zero or more tokens may be finalized and the unfinalized tokens are set to null. The isTokenFinalized and isUnfinalizedTokensChanged flags are set appropriately. However, because the result is rejected, the tokens are quite likely to be incorrect.

Since the Result is finalized (rejected), the methods of FinalResult can be used. If the grammar is known (GRAMMAR_FINALIZED event was issued and the getGrammar methods returns non-null) then the FinalRuleResult or FinalDictationResult interface can also be used depending upon whether the matched grammar was a RuleGrammar or DictationGrammar.

Other state transition behavior for RESULT_REJECTED is the same as for the RESULT_ACCEPTED event.

See Also:: isTokenFinalized, isUnfinalizedTokensChanged, getResultState, getGrammar, resultRejected

AUDIO_RELEASED

public static final int AUDIO_RELEASED

AUDIO_RELEASED event is issued when the audio information associated with a FinalResult object is released. The release may have been requested by an application call to releaseAudio in the FinalResult interface or may be initiated by the recognizer to reclaim memory. The FinalResult.isAudioAvailable method returns false after this event.

The AUDIO_RELEASED event is only issued for results in a finalized state (getResultState returns either ACCEPTED or REJECTED).

See Also:: releaseAudio, isAudioAvailable, getResultState, audioReleased

TRAINING_INFO_RELEASED

public static final int TRAINING_INFO_RELEASED

TRAINING_INFO_RELEASED event is issued when the training information for a finaliized result is released. The release may have been requested by an application call to the releaseTrainingInfo method in the FinalResult interface or may be initiated by the recognizer to reclaim memory. The isTrainingInfoAvailable method of FinalResult returns false after this event.

The TRAINING_INFO_RELEASED event is only issued for results in a finalized state (getResultState returns either ACCEPTED or REJECTED).

See Also:: releaseTrainingInfo, isTrainingInfoAvailable, getResultState, trainingInfoReleased

tokenFinalized

protected boolean tokenFinalized

True if the ResultEvent indicates that one or more tokens have been finalized. Tokens may be finalized with any of the following result events: RESULT_CREATED, RESULT_UPDATED, RESULT_ACCEPTED, RESULT_REJECTED.

See Also:: isTokenFinalized

unfinalizedTokensChanged

protected boolean unfinalizedTokensChanged

True if the ResultEvent indicates that the unfinalized tokens have changed. The unfinalized tokens may change with the following result events: RESULT_CREATED, RESULT_UPDATED, RESULT_ACCEPTED, RESULT_REJECTED.

See Also:: isUnfinalizedTokensChanged

Constructor Detail

ResultEvent

public ResultEvent(Result source,
                   int id,
                   boolean isTokenFinalized,
                   boolean isUnfinalizedTokensChanged)

Constructs a ResultEvent for a specified source Result and result event id. The two boolean flags indicating change in tokens should be set appropriately for RESULT_CREATED, RESULT_UPDATED, RESULT_ACCEPTED and RESULT_REJECTED events. (For other event types these flags should be false).

Parameters:: source - the Result object that issued the event; id - the identifier for the event type; isTokenFinalized - true if any token is finalized with this event; isUnfinalizedTokensChanged - true if the unfinalized text is changed with this event
See Also:: RESULT_CREATED, GRAMMAR_FINALIZED, RESULT_UPDATED, RESULT_ACCEPTED, RESULT_REJECTED, AUDIO_RELEASED, TRAINING_INFO_RELEASED

ResultEvent

public ResultEvent(Result source,
                   int id)

Constructs a ResultEvent with an event type identifier. The isTokenFinalized and isUnfinalizedTokensChanged flags are set to false.

Parameters:: source - the object that issued the event; id - the identifier for the event type

Method Detail

isTokenFinalized

public boolean isTokenFinalized()

For RESULT_CREATED, RESULT_UPDATED, RESULT_ACCEPTED and RESULT_REJECTED events returns true if any tokens were finalized. For other events, return false. If true, the number of tokens returned by numTokens and getBestTokens has increased.

See Also:: numTokens, getBestTokens

isUnfinalizedTokensChanged

public boolean isUnfinalizedTokensChanged()

For RESULT_CREATED, RESULT_UPDATED, RESULT_ACCEPTED and RESULT_REJECTED events returns true if the unfinalized tokens changed. For other events, return false. If true, the value returned by getUnfinalizedTokens has changed.

Note that both RESULT_ACCEPTED and RESULT_REJECTED events implicitly set the unfinalized text to null. The isUnfinalizedTokensChanged method should return true only if the unfinalized text was non-null prior to finalization.

See Also:: getUnfinalizedTokens

paramString

public String paramString()

Returns a parameter string identifying this event. This method is useful for event-logging and for debugging.

Returns:: a string identifying the event
Overrides:: paramString in class SpeechEvent


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


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


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