javax.speech.recognition
Class ResultEvent

Object
  SpeechEvent
      ResultEvent

public class ResultEvent
extends SpeechEvent

Event issued to indicate changes in the Result state and recognized tokens. A ResultEvent is issued to all appropriate ResultListener objects. ResultListeners may be attached as described in the ResultListener documentation.

The three states of a recognition Result are UNFINALIZED, ACCEPTED, and REJECTED. They are described in the documentation for the Result interface. The RESULT_CREATED, RESULT_ACCEPTED and RESULT_REJECTED events indicate corresponding Result state changes.

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 marks creation a Result object. A new Result starts in the UNFINALIZED state.
• While in the 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 events may be issued.

See Also:

Recognizer, Result, UNFINALIZED, ACCEPTED, REJECTED, ResultListener, FinalResult, FinalRuleResult

Field Summary

static int	AUDIO_RELEASED Event issued when the audio information associated with a FinalResult object is released.
static int	DEFAULT_MASK The default mask for events in this class.
static int	GRAMMAR_FINALIZED Event issued when the Grammar matched by a Result is identified and finalized.
static int	RESULT_ACCEPTED Event issued when a Result is successfully finalized and indicates a state change from UNFINALIZED to ACCEPTED.
static int	RESULT_CREATED Event issued when a new Result is created.
static int	RESULT_REJECTED Event issued when a Result is unsuccessfully finalized and indicates a state change from UNFINALIZED to REJECTED.
static int	RESULT_UPDATED Event issued when one or more tokens of a Result are finalized or when the unfinalized tokens of a Result are changed.
static int	TRAINING_INFO_RELEASED Event issued when the training information associated with a FinalResult object is released.

Fields inherited from class SpeechEvent

DISABLE_ALL, ENABLE_ALL

Constructor Summary

ResultEvent(Result source, int id)
Constructs a basic ResultEvent.

ResultEvent(Result source, int id, boolean tokensFinalized, boolean unfinalizedTokensChanged)
Constructs a ResultEvent with flags to indicate changes in token status and value.

Method Summary

boolean	isFinalizedChanged() Returns true if any tokens were finalized.
boolean	isUnfinalizedChanged() Returns true if any unfinalized tokens have changed.
String	paramString() Returns a parameter String that contains the event identifier in text form.
String	toString() Returns a printable String.

Methods inherited from class SpeechEvent

getId, getSource

Methods inherited from class Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

RESULT_CREATED

public static final int RESULT_CREATED

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

When a Result is created, it is in the UNFINALIZED state and may have zero or more finalized tokens and zero or more unfinalized tokens. Changes in finalized and unfinalized tokens are indicated by the isFinalizedChanged and isUnfinalizedChanged methods.

This event follows the RECOGNIZER_PROCESSING event which transitions the Recognizer from the LISTENING substate to the PROCESSING substate.

See Also:

resultUpdate, Result, Result.UNFINALIZED, RecognizerEvent.RECOGNIZER_PROCESSING, Recognizer.LISTENING, Recognizer.PROCESSING, isFinalizedChanged, isUnfinalizedChanged, setResultMask, Constant Field Values

RESULT_UPDATED

public static final int RESULT_UPDATED

Event issued when one or more tokens of a Result are finalized or when the unfinalized tokens of a Result are changed.

Changes in finalized and unfinalized tokens are indicated by the isFinalizedChanged and isUnfinalizedChanged methods.

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

This event is not enabled by default. It may be enabled with setResultMask.

See Also:

resultUpdate, isFinalizedChanged, isUnfinalizedChanged, Result.UNFINALIZED, setResultMask, Constant Field Values

GRAMMAR_FINALIZED

public static final int GRAMMAR_FINALIZED

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

This event only occurs for a Result in the UNFINALIZED state.

This event does not affect finalized or unfinalized tokens as reflected by the isFinalizedChanged and isUnfinalizedChanged methods.

This event is not enabled by default. It may be enabled with setResultMask.

See Also:

Grammar, getGrammar, resultUpdate, isFinalizedChanged, isUnfinalizedChanged, Result.UNFINALIZED, setResultMask, Constant Field Values

RESULT_ACCEPTED

public static final int RESULT_ACCEPTED

Event 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. Changes in finalized and unfinalized tokens are indicated by the isFinalizedChanged and isUnfinalizedChanged methods.

Since the Result is finalized (ACCEPTED), the methods of FinalResult and FinalRuleResult may be used. The getGrammar method of Result may be used to determine the type of Grammar matched. Applications should use type casting to ensure that only the appropriate interfaces and methods are used. The following example illustrates proper casting of Results:

 void resultUpdate(ResultEvent e) {
   Result result = (Result) e.getSource(); // can always do this
   if (e.getId() == RESULT_ACCEPTED) {

     // always safe with RESULT_ACCEPTED
     FinalResult fr = (FinalResult) result;
     ...

     // note getGrammar() may return null for RESULT_REJECTED
     if (result.getGrammar() instanceof RuleGrammar) {
       FinalRuleResult frr = (FinalRuleResult) result;
       ...
     }
   }
 }
 

This event is issued after the Recognizer issues an ENGINE_PAUSED event to transition from the PROCESSING substate to the PAUSED state. Any changes made to Grammars or the activatable property 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 RESUMED state and LISTENING substate with a CHANGES_COMMITTED event. In this case, a call to resume is not required unless a call to pause is made. Calls to resume must balance calls to pause and the Recognizer defers committing Grammar changes until this balance is achieved.

See Also:

resultUpdate, Result.UNFINALIZED, Result.ACCEPTED, isFinalizedChanged, isUnfinalizedChanged, Result, FinalResult, FinalRuleResult, getGrammar, pause, resume, PAUSED, RESUMED, Recognizer.PROCESSING, Recognizer.LISTENING, RecognizerEvent.CHANGES_COMMITTED, Constant Field Values

RESULT_REJECTED

public static final int RESULT_REJECTED

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

In the state transition, zero or more tokens may be finalized and the unfinalized tokens are set to null. Changes in finalized and unfinalized tokens are indicated by the isFinalizedChanged and isUnfinalizedChanged methods. 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 as described in the RESULT_ACCEPTED event. If the Grammar is known (GRAMMAR_FINALIZED event was issued and the getGrammar method returns non-null), then the FinalRuleResult interface can also be used.

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

See Also:

resultUpdate, Result.UNFINALIZED, Result.REJECTED, isFinalizedChanged, isUnfinalizedChanged, getGrammar, GRAMMAR_FINALIZED, RESULT_ACCEPTED, Constant Field Values

AUDIO_RELEASED

public static final int AUDIO_RELEASED

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

This event is only issued for Results in a finalized state (ACCEPTED or REJECTED).

See Also:

resultUpdate, FinalResult, releaseAudio, isAudioAvailable, getResultState, Result.ACCEPTED, Result.REJECTED, Constant Field Values

TRAINING_INFO_RELEASED

public static final int TRAINING_INFO_RELEASED

Event issued when the training information associated with a FinalResult object 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 returns false after this event.

This event is only issued for Results in a finalized state (ACCEPTED or REJECTED).

See Also:

resultUpdate, FinalResult, releaseTrainingInfo, isTrainingInfoAvailable, getResultState, Result.ACCEPTED, Result.REJECTED, Constant Field Values

DEFAULT_MASK

public static final int DEFAULT_MASK

The default mask for events in this class.

The following events are delivered by default: RESULT_CREATED, RESULT_ACCEPTED, RESULT_REJECTED, GRAMMAR_FINALIZED, AUDIO_RELEASED, TRAINING_INFO_RELEASED.

Other events may be enabled with setResultMask if desired.

See Also:

RESULT_CREATED, RESULT_UPDATED, RESULT_ACCEPTED, RESULT_REJECTED, AUDIO_RELEASED, TRAINING_INFO_RELEASED, GRAMMAR_FINALIZED, setResultMask, Constant Field Values

Constructor Detail

ResultEvent

public ResultEvent(Result source,
                   int id)
            throws IllegalArgumentException

Constructs a basic ResultEvent. This constructor applies to the AUDIO_RELEASED, GRAMMAR_FINALIZED and TRAINING_INFO_RELEASED event identifiers.

Parameters:

source - the Result object that issued the event

id - the event identifier

Throws:

IllegalArgumentException - if called with an inappropriate event ID

See Also:

getSource, getId, AUDIO_RELEASED, GRAMMAR_FINALIZED, TRAINING_INFO_RELEASED, ResultEvent(Result, int, boolean, boolean), isFinalizedChanged, isUnfinalizedChanged

ResultEvent

public ResultEvent(Result source,
                   int id,
                   boolean tokensFinalized,
                   boolean unfinalizedTokensChanged)
            throws IllegalArgumentException

Constructs a ResultEvent with flags to indicate changes in token status and value. This constructor applies to the RESULT_CREATED, RESULT_UPDATED, RESULT_ACCEPTED and RESULT_REJECTED event identifiers.

Parameters:

source - the Result object that issued the event

id - the event identifier

tokensFinalized - true if any tokens are finalized with this event

unfinalizedTokensChanged - true if any unfinalized tokens have changed with this event

Throws:

IllegalArgumentException - if called with an inappropriate event ID

See Also:

getSource, getId, isFinalizedChanged, isUnfinalizedChanged, RESULT_CREATED, RESULT_UPDATED, RESULT_ACCEPTED, RESULT_REJECTED

Method Detail

isFinalizedChanged

public boolean isFinalizedChanged()

Returns true if any tokens were finalized. This can occur for RESULT_CREATED, RESULT_UPDATED, RESULT_ACCEPTED and RESULT_REJECTED events. For other events, this method returns false.

If true, the number of tokens returned by getNumTokens and getBestTokens has increased.

Returns:

flag indicating finalized tokens have changed

See Also:

getNumTokens, getBestTokens, isUnfinalizedChanged, RESULT_CREATED, RESULT_UPDATED, RESULT_ACCEPTED, RESULT_REJECTED

isUnfinalizedChanged

public boolean isUnfinalizedChanged()

Returns true if any unfinalized tokens have changed. This can occur for RESULT_CREATED, RESULT_UPDATED, RESULT_ACCEPTED and RESULT_REJECTED events. For other events, this method returns false. If true, the value returned by getUnfinalizedTokens has changed.

Note that there are no unfinalized tokens for both the RESULT_ACCEPTED and RESULT_REJECTED events. For these events, this method returns true only if there were unfinalized tokens prior to finalization.

Returns:

flag indicating unfinalized tokens have changed

See Also:

getUnfinalizedTokens, isFinalizedChanged, RESULT_CREATED, RESULT_UPDATED, RESULT_ACCEPTED, RESULT_REJECTED

paramString

public String paramString()

Returns a parameter String that contains the event identifier in text form.

The method toString may provide more detail. This method is useful for event-logging and for debugging.

Specified by:

paramString in class SpeechEvent

Returns:

a String that contains the event identifier in text form.

See Also:

toString

toString

public String toString()

Returns a printable String. Useful for event-logging and debugging.

The method paramString also provides printable information.

Specified by:

toString in class SpeechEvent

Returns:

A printable string.

See Also:

paramString