javax.speech.recognition
Interface Recognizer

All Superinterfaces:

Engine

public interface Recognizer
extends Engine

Provides access to speech recognition capabilities. The Recognizer interface extends the Engine interface and so inherits the basic Engine capabilities and provides additional specialized capabilities.

The primary capabilities provided are Recognizer control and Result handling. An application is responsible for providing a Recognizer with Grammars through the GrammarManager. A Grammar defines a set of words (technically known as tokens) and defines acceptable patterns in which the tokens may be spoken. When a Grammar is active, the Recognizer listens for speech in the incoming audio that matches the Grammar. When speech is detected, the Recognizer produces a Result. The Result object is passed to the application with information on which words were heard.

The types of Grammars, mechanisms for creating, modifying and managing Grammars, types of Results, Result handling and other Recognizer functions are described in more detail below.

Creating a Recognizer

A Recognizer is created by a call to the createEngine method of the EngineManager class. A Recognizer for the default SpeechLocale is created as follows:

 Recognizer rec = (Recognizer)
     EngineManager.createEngine(RecognizerMode.DEFAULT);
 

The recognition package overview contains a recognition example . Detailed descriptions of the procedures for locating, selecting, creating and initializing a Recognizer are provided in the documentation for the EngineManager.

Using Grammars

The GrammarManager provides the functionality to create and manipulate Grammars used by the Recognizer. The Recognizer must be provided with one or more Grammars that indicate what words and word sequences it should recognize. The basic process for dealing with a Grammar follows.

1. pause the Recognizer (if not already PAUSED)
2. As necessary, create or modify Grammars according to the application context.
3. Enable (default) and disable Grammars for recognition as needed.
4. Attach a ResultListener to either the Recognizer or Grammar to receive ResultEvents.
5. resume the Recognizer to atomically commit any Grammar changes.
6. Repeat steps 1 through 5 as required.
7. Delete application-created Grammars when they are no longer needed.

Efficiency

The processing of Grammars (particularly large Grammars) can be computationally expensive. Loading a new Grammar can take appreciable time. Updates to a Grammar may also be slow. Therefore, applications should take precautions to build Grammars in advance and to modify them only when necessary. Furthermore, an application should minimize the number of Grammars active at any point in time.

Recognizer States

A Recognizer inherits two pairs of substates from the ALLOCATED state from the Engine interface:

• FOCUSED and DEFOCUSED
• PAUSED and RESUMED

The initial states are DEFOCUSED and PAUSED. An application should call requestFocus and resume after loading Grammars.

The Recognizer interface adds two substates to the RESUMED state:

• LISTENING and PROCESSING

When RESUMED, the initial state is LISTENING while the Recognizer listens for speech. Once speech is found, the Recognizer remains in the PROCESSING state until it produces a Result.

See the Table of Diagrams for state transition diagrams.

Recognizer States: Focus Policy

A Recognizer uses a two state substate-system with FOCUSED and DEFOCUSED to indicate whether this instance of the Recognizer currently has the recognition focus. Focus is important in an environment with multiple applications because more than one application can share an underlying speech recognition engine, but the user gives recognition focus to only one application at a time. Since it is normal for an application to use only one Recognizer, recognition focus and application focus normally mean the same thing. (Applications with multiple Recognizers cannot make this assumption.)

Focus is not usually relevant in telephony applications or some embedded applications in which there is a single input audio stream to a single application.

The focus status is a key factor in determining the activation of Grammars and therefore in determining when Results will and will not be generated. The activation conditions for Grammars and the role of focus are described in the Grammar interface.

When focus is received, an ENGINE_FOCUSED event is issued to any RecognizerListeners attached to this Engine. When focus is released or otherwise lost, an ENGINE_DEFOCUSED event is issued to any RecognizerListeners attached to this Engine.

Applications can request focus for the Recognizer by calling the requestFocus method. This asynchronous method may return before focus is received. To determine when focus is on, applications can check for ENGINE_FOCUSED events or test the FOCUSED bit of Engine state.

Applications can release focus from the Recognizer by calling the releaseFocus method. This asynchronous method may return before focus is lost. To determine when focus is off, applications can check for ENGINE_DEFOCUSED events or test the DEFOCUSED bit of Engine state. In GUI-based environments, it is normal (but not required) for recognition focus to follow GUI focus. Therefore, for example, it is common for the requestFocus method to be called on AWT or Swing events such as FocusEvent and WindowEvent or in association with a MIDlet's startApp method.

A well-behaved application only requests focus when it knows that it has the focus of the user (the user is talking to it and not to other applications). A well-behaved application will also release focus as soon as it finishes with it.

Recognizer States: RESUMED - Typical Event Cycle

The typical state cycle for RESUMED follows. This assumes that Grammars have been defined as described above and committed with a call to resume. The call to resume transitions the Recognizer from the PAUSED state to the RESUMED state preceded by the events CHANGES_COMMITTED/CHANGES_REJECTED, ENGINE_RESUMED, and RECOGNIZER_LISTENING.

1. A Recognizer starts in the LISTENING state with a certain set of active Grammars. When incoming audio is detected that may match an active Grammar, the Recognizer transitions to the PROCESSING state with a RECOGNIZER_PROCESSING RecognizerEvent. The Recognizer then creates a new Result and issues a RESULT_CREATED ResultEvent to provide the Result to the application.
2. The Recognizer remains in the PROCESSING state until it completes recognition of the Result.
3. The Recognizer indicates completion of recognition by issuing an ENGINE_PAUSED EngineEvent to transition from the PROCESSING substate to the PAUSED state. Once in that state, it issues a Result finalization ResultEvent to ResultListeners (RESULT_ACCEPTED or RESULT_REJECTED).
4. The Recognizer remains in the PAUSED state until processing of the Result finalization ResultEvent is completed. Applications will usually make any necessary Grammar changes while the Recognizer is PAUSED. The Recognizer buffers incoming audio in this scenario. Buffering allows a user to continue speaking without loss of speech data. Once the Recognizer returns to the RESUMED state and LISTENING substate, any buffered audio is processed to give the user the perception of real-time processing.
5. The Recognizer commits all Grammar changes, issues CHANGES_COMMITTED/CHANGES_REJECTED and ENGINE_RESUMED events to any RecognizerListeners and returns to the RESUMED/LISTENING state/substate. It also issues GRAMMAR_CHANGES_COMMITTED/GRAMMAR_CHANGES_REJECTED GrammarEvents to GrammarListeners of changed Grammars. The Grammar commit applies all Grammar changes made at any point up to the end of Result finalization, typically including changes made in the Result finalization ResultEvents.
6. The Recognizer listens in the LISTENING state for speech that matches the updated Grammars.

In this state cycle, the RECOGNIZER_PROCESSING RecognizerEvent is triggered by user action: starting and stopping speaking. The ENGINE_PAUSED and ENGINE_RESUMED EngineEvents are triggered programmatically by the Recognizer after issuing events to application listeners during Result finalization.

Recognizer States: RESUMED - Non-Speech Events

For applications that deal only with spoken input, the state cycle above handles most normal speech interactions. For applications that handle other asynchronous input, additional state transitions are possible. Other types of asynchronous input include graphical user interface events, timer events, multi-threading events, socket events, etc.

When a non-speech event occurs that changes the application state or application data, it is often necessary to update the Recognizer's Grammars. Furthermore, it is typically necessary to do this as if the change occurred in real time - at exactly the point in time at which the event occurred.

The pause and resume methods of a Recognizer may be used to handle non-speech asynchronous events. The typical cycle for updating Grammars is as follows:

1. Assume that the Recognizer is in the LISTENING state (the user is not currently speaking). As soon as the non-speech event is received, the application calls pause(BUFFER_MODE) to indicate that it is about to change Grammars.
2. The recognizer issues a RECOGNIZER_PAUSED RecognizerEvent and transitions from the LISTENING substate to the PAUSED state.
3. The application makes all necessary changes to the Grammars.
4. Once all changes are completed, the application calls the resume method. The Recognizer commits the Grammar updates atomically, issues a CHANGES_COMMITTED/CHANGES_REJECTED RecognizerEvent to transition from the PAUSED state back to the RESUMED state and LISTENING substate, and issues GRAMMAR_CHANGES_COMMITTED/GRAMMAR_CHANGES_REJECTED GrammarEvents to all changed Grammars.
5. The Recognizer resumes recognition of any buffered audio and then live audio with the updated Grammars.

Because audio is buffered from the time of the asynchronous non-speech event to the time at which the CHANGES_COMMITTED/CHANGES_REJECTED RecognizerEvent occurs, the audio is processed as if the updated Grammars were applied exactly at the time of the asynchronous non-speech event. The user has the perception of real-time processing.

Although audio is buffered in the PAUSED state with pause(BUFFER_MODE), applications should makes changes and resume as quickly as possible. This minimizes the possibility of a buffer overrun (NOT_BUFFERING). It also reduces delays in recognizing speech and responding to the user.

Recognizer States: RESUMED - Mixing Speech and Non-Speech Events

There is no guarantee that speech and non-speech events will not be mixed. If a speech event occurs in the absence of non-speech events, the normal event cycle takes place. If a non-speech event occurs in the absence of any speech events, the non-speech event cycle takes place.

Consider the two cases in which speech and non-speech events interact:

1. A non-speech event occurs during processing of a speech event:
   Technically, this is the case in which a non-speech event is issued while the Recognizer is in either the PROCESSING substate or the PAUSED state. In both cases the event processing for the non-speech is no different than normal. The non-speech event handler calls pause(BUFFER_MODE) to indicate it is about to change Grammars, makes the Grammar changes, and then calls resume to apply the commit the changes atomically.

   The effect is that the CHANGES_COMMITTED/CHANGES_REJECTED RecognizerEvent that would occur in the normal event cycle may be delayed until the resume method is explicitly called and Result finalization completes. At that point, the Recognizer applies changes made in response to both the speech and non-speech events.

2. A speech event occurs during processing of a non-speech event:
   This case is simpler. If the user starts speaking while a non-speech event is being processed, then the Recognizer is in the PAUSED state, speech is buffered, and the speech event is actually delayed until the Recognizer returns to the LISTENING substate. Once the Recognizer returns to the LISTENING substate, the incoming speech is processed with the normal event cycle.

Conditions for Operation

Where noted, standard Conditions for Operation apply. This means that a method operates as defined only when the Engine is in the ALLOCATED state and not DEALLOCATING_RESOURCES. The call blocks if the Engine is in the ALLOCATING_RESOURCES state and completes when the Engine reaches the ALLOCATED state. Otherwise, an exception is thrown for an Engine in the DEALLOCATING_RESOURCES or DEALLOCATED states.

See Also:

EngineManager, createEngine, RecognizerEvent, RecognizerListener, Grammar, RuleGrammar, GrammarManager, Result, FinalResult

Field Summary

static int	BUFFER_MODE Flag used to indicate that audio buffering should continue while PAUSED.
static long	BUFFERING Bit of state that is set when an ALLOCATED Recognizer is buffering audio.
static long	LISTENING Bit of state that is set when an ALLOCATED Recognizer is listening to incoming audio for speech that may match an active Grammar.
static long	NOT_BUFFERING Bit of state that is set when an ALLOCATED Recognizer is not buffering audio.
static long	PROCESSING Bit of state that is set when an ALLOCATED Recognizer is producing a Result for incoming speech that may match an active Grammar.

Fields inherited from interface Engine

ALLOCATED, ALLOCATING_RESOURCES, ASYNCHRONOUS_MODE, DEALLOCATED, DEALLOCATING_RESOURCES, DEFOCUSED, ERROR_OCCURRED, FOCUSED, IMMEDIATE_MODE, PAUSED, RESUMED

Method Summary

void	addRecognizerListener(RecognizerListener listener) Requests notifications of RecognizerEvents related to this Recognizer.
void	addResultListener(ResultListener listener) Requests notifications of all ResultEvents for all Results produced by this Recognizer.
void	allocate() Allocates the resources required for this Engine and puts it into the ALLOCATED state.
void	allocate(int mode) Allocates the resources required for this Engine using the mode specified and puts it into the ALLOCATED state.
void	deallocate() Deallocates the resources acquired for this Engine and returns it to the DEALLOCATED state.
void	deallocate(int mode) Deallocates the resources acquired for this Engine using the mode specified and returns it to the DEALLOCATED state.
GrammarManager	getGrammarManager() Gets the GrammarManager for this Recognizer.
RecognizerProperties	getRecognizerProperties() Returns the properties for this Recognizer.
int	getResultMask() Gets the mask to filter ResultEvents for added ResultListeners.
SpeakerManager	getSpeakerManager() Returns the SpeakerManager for this Recognizer.
void	pause() Pauses the audio processing for this Engine and puts it into the PAUSED state.
void	pause(int mode) Pauses a Recognizer with additional options.
void	processGrammars() Informs this Recognizer that Grammars have changed.
void	releaseFocus() Releases the recognition focus from this Recognizer.
void	removeRecognizerListener(RecognizerListener listener) Removes a RecognizerListener from this Recognizer.
void	removeResultListener(ResultListener listener) Removes a ResultListener from this Recognizer.
void	requestFocus() Requests the recognition focus for this Recognizer.
boolean	resume() Resumes audio processing for this Engine by entering the RESUMED state.
void	setResultMask(int mask) Sets the mask to filter ResultEvents for added ResultListeners.

Methods inherited from interface Engine

getAudioManager, getEngineMask, getEngineMode, getEngineState, getSpeechEventExecutor, getVocabularyManager, setEngineMask, setSpeechEventExecutor, testEngineState, waitEngineState, waitEngineState

Field Detail

BUFFER_MODE

static final int BUFFER_MODE

Flag used to indicate that audio buffering should continue while PAUSED.

The description of the pause(int) method includes more detail.

See Also:

pause(int), PAUSED, Constant Field Values

LISTENING

static final long LISTENING

Bit of state that is set when an ALLOCATED Recognizer is listening to incoming audio for speech that may match an active Grammar.

A RECOGNIZER_LISTENING event is issued to indicate a transition into the LISTENING substate of the RESUMED state.

A RECOGNIZER_PROCESSING event is issued to indicate a transition out of the LISTENING substate and into the PROCESSING substate.

An ENGINE_PAUSED event is issued to indicate a transition out of the LISTENING substate and into the PAUSED state.

See Also:

ALLOCATED, RESUMED, PROCESSING, PAUSED, pause, RECOGNIZER_LISTENING, RECOGNIZER_PROCESSING, ENGINE_PAUSED, getEngineState, waitEngineState, Constant Field Values

PROCESSING

static final long PROCESSING

Bit of state that is set when an ALLOCATED Recognizer is producing a Result for incoming speech that may match an active Grammar.

A RECOGNIZER_PROCESSING event is issued to indicate a transition into the PROCESSING substate from the LISTENING substate when the start of a new Result is detected.

An ENGINE_PAUSED event is issued to indicate a transition out of the PROCESSING substate and into the PAUSED state when recognition of a Result is completed.

See Also:

ALLOCATED, LISTENING, Engine.PAUSED, pause, RECOGNIZER_PROCESSING, ENGINE_PAUSED, getEngineState, waitEngineState, Result, Constant Field Values

BUFFERING

static final long BUFFERING

Bit of state that is set when an ALLOCATED Recognizer is buffering audio. It is normal for a Recognizer to buffer a limited amount of audio so that it can later process the audio without missing speech.

A Recognizer is first allocated in the NOT_BUFFERING state. A call to resume results in a transition from the NOT_BUFFERING to the BUFFERING state if not already there.

A Recognizer will leave the BUFFERING state if buffer overflow occurs. Recovery is described in the three states PAUSED, LISTENING, and PROCESSING.

An application can also leave the BUFFERING state by calling pause(). In this case, buffering resumes by calling resume.

A RECOGNIZER_BUFFERING event is issued to indicate a transition into the BUFFERING state from the NOT_BUFFERING state.

See Also:

ALLOCATED, NOT_BUFFERING, PAUSED, LISTENING, PROCESSING, pause, resume, RECOGNIZER_BUFFERING, getEngineState, waitEngineState, Constant Field Values

NOT_BUFFERING

static final long NOT_BUFFERING

Bit of state that is set when an ALLOCATED Recognizer is not buffering audio. It is normal for a Recognizer to buffer a limited amount of audio so that it can later process the audio without missing speech.

A Recognizer is first allocated in the NOT_BUFFERING state. A call to resume results in a transition from the NOT_BUFFERING to the BUFFERING state if not already there.

A Recognizer will enter the NOT_BUFFERING state if buffer overflow occurs. Recovery is described in the three states PAUSED, LISTENING, and PROCESSING.

An application can also enter the NOT_BUFFERING state by calling pause. In this case, buffering resumes by calling resume.

A RECOGNIZER_NOT_BUFFERING event is issued to indicate a transition into the NOT_BUFFERING state from the BUFFERING state.

See Also:

ALLOCATED, BUFFERING, PAUSED, LISTENING, PROCESSING, pause, resume, RECOGNIZER_NOT_BUFFERING, getEngineState, waitEngineState, Constant Field Values

Method Detail

addRecognizerListener

void addRecognizerListener(RecognizerListener listener)

Requests notifications of RecognizerEvents related to this Recognizer. An application can attach multiple RecognizerListeners to this Recognizer. A single RecognizerListener can be attached to multiple Recognizers. A RecognizerListener is removed with the removeRecognizerListener method.

A RecognizerListener can be attached or removed in any Recognizer state. Individual RecognizerEvents may be filtered with setEngineMask.

Parameters:

listener - the RecognizerListener to attach to this Recognizer

See Also:

RecognizerEvent, RecognizerListener, removeRecognizerListener, setEngineMask

addResultListener

void addResultListener(ResultListener listener)

Requests notifications of all ResultEvents for all Results produced by this Recognizer.

An application can attach multiple ResultListeners to this Recognizer. A single ResultListener can be attached to multiple Recognizers. A ResultListener is removed with the removeResultListener method.

ResultListeners attached to a Recognizer are the only ResultListeners to receive the RESULT_CREATED event in addition to all subsequent ResultEvents.

ResultListener objects can also be attached to any Grammar or to any Result. The addResultListener methods for the respective classes describe ResultEvents received.

A ResultListener can be attached or removed in any Recognizer state. Individual ResultEvents may be filtered with setResultMask.

Parameters:

listener - the ResultListener to attach to this Recognizer

See Also:

Grammar, Result, Grammar.addResultListener, Result.addResultListener, removeResultListener, ResultEvent, RESULT_CREATED, setResultMask

getResultMask

int getResultMask()

Gets the mask to filter ResultEvents for added ResultListeners.

See setResultMask for details.

The event mask can be set and retrieved in any Recognizer state.

Returns:

the current mask for ResultEvents

See Also:

ResultEvent, ResultListener, setResultMask

setResultMask

void setResultMask(int mask)

Sets the mask to filter ResultEvents for added ResultListeners.

It can improve efficiency to mask events that are not used. Events of interest can be seen by using the logical OR of the event constants defined in the ResultEvent class. ResultEvent.DEFAULT_MASK is the initial value.

The event mask can be set and retrieved in any Recognizer state. This method affects filtering of all attached ResultListeners.

Parameters:

mask - the mask for ResultEvents

See Also:

ResultEvent, ResultEvent.DEFAULT_MASK, ResultListener, getResultMask

getGrammarManager

GrammarManager getGrammarManager()

Gets the GrammarManager for this Recognizer. This method never returns null. It may be called in any state of a Recognizer.

Returns:

the GrammarManager

See Also:

Grammar, RuleGrammar

getRecognizerProperties

RecognizerProperties getRecognizerProperties()

Returns the properties for this Recognizer.

The RecognizerProperties are available in any state of this Recognizer. However, changes only take effect once a Recognizer reaches the ALLOCATED state.

Returns:

the RecognizerProperties object for this Recognizer

getSpeakerManager

SpeakerManager getSpeakerManager()
                                 throws SecurityException

Returns the SpeakerManager for this Recognizer. This method may return null if this Recognizer does not store speaker data as indicated as indicated by getSpeakerProfiles. A speaker-independent Recognizer, for example, handles all speakers the same.

This method may be called in any state of a Recognizer.

The SpeakerManager methods listKnownSpeakers and setCurrentSpeaker operate in any Recognizer state but only take effect in the ALLOCATED state. This allows an application to set the initial SpeakerProfile prior to calling allocate for this Recognizer.

Returns:

the SpeakerManager for this Recognizer

Throws:

SecurityException - if the application does not have permission

See Also:

allocate, SpeakerManager, listKnownSpeakers, setCurrentSpeaker, SpeakerProfile, getSpeakerProfiles

Required permission:

javax.speech.recognition.SpeakerManager

processGrammars

void processGrammars()
                     throws EngineStateException

Informs this Recognizer that Grammars have changed. The GrammarManager describes ways in which Grammars may change.

Calling this method is not required. Any Grammar updates are atomically committed with resume.

This method may be helpful for applications that call pause and anticipate some time between the time Grammars are ready and the next call to resume. Any problems with Grammars are reported with resume.

Calling this method does not result in any state changes or events.

It is not an error to call processGrammars when no Grammars have been changed. It is not an error to call processGrammars multiple times.

The processGrammars method operates as defined when the Recognizer is in the ALLOCATED and PAUSED states.

Throws:

EngineStateException - if this Recognizer is not ALLOCATED and PAUSED

See Also:

Grammar, GrammarManager, Engine.ALLOCATED, Engine.PAUSED, pause, resume

releaseFocus

void releaseFocus()
                  throws EngineStateException

Releases the recognition focus from this Recognizer. This request is made asynchronously. An ENGINE_DEFOCUSED event is issued to attached RecognizerListeners once the focus is released and the Recognizer state changes from FOCUSED to DEFOCUSED.

Since focus is a key factor in the activation policy for Grammars, an ENGINE_DEFOCUSED event is followed by a GRAMMAR_DEACTIVATED event to the GrammarListeners of each Grammar that loses activation. The Grammar interface details the role of focus and Grammar activation conditions.

Since only one application may have recognition focus at any time, applications should release focus whenever it is not required. Focus is discussed in more detail with Recognizer focus states.

It is not an error for an application to release focus for a Recognizer that does not have focus.

Focus is implicitly released after calling deallocate.

This method operates as defined when the standard Conditions for Operation apply.

Throws:

EngineStateException - when not in the standard Conditions for Operation

See Also:

requestFocus, deallocate, FOCUSED, DEFOCUSED, ENGINE_DEFOCUSED, getEngineState, GRAMMAR_DEACTIVATED, Grammar

removeRecognizerListener

void removeRecognizerListener(RecognizerListener listener)

Removes a RecognizerListener from this Recognizer.

A RecognizerListener can be removed in any state of a Recognizer.

Parameters:

listener - the RecognizerListener to be removed

See Also:

addRecognizerListener

removeResultListener

void removeResultListener(ResultListener listener)

Removes a ResultListener from this Recognizer.

A ResultListener can be attached or removed in any state of a Recognizer.

Parameters:

listener - the ResultListener to be removed

See Also:

addResultListener

requestFocus

void requestFocus()
                  throws EngineStateException

Requests the recognition focus for this Recognizer. This request is made asynchronously. When the focus is received, an ENGINE_FOCUSED event is issued to attached RecognizerListeners and the Recognizer changes state from DEFOCUSED to FOCUSED.

Since focus is a key factor in the activation policy for Grammars, an ENGINE_FOCUSED event is followed by a GRAMMAR_ACTIVATED event to the GrammarListeners of each Grammar that is activated. The Grammar interface details the role of focus and Grammar activation conditions.

Since only one application may have recognition focus at any time, applications should only request focus when confident that the user is speaking to that application. Focus is discussed in more detail with Recognizer focus states.

It is not an error for an application to request focus for a Recognizer that already has focus.

Focus is implicitly released after calling deallocate.

This method operates as defined when the standard Conditions for Operation apply.

Throws:

EngineStateException - when not in the standard Conditions for Operation

See Also:

releaseFocus, deallocate(), FOCUSED, ENGINE_FOCUSED, getEngineState, GRAMMAR_ACTIVATED, Grammar

allocate

void allocate()
              throws AudioException,
                     EngineException,
                     EngineStateException,
                     SecurityException

Allocates the resources required for this Engine and puts it into the ALLOCATED state. When this method returns successfully the ALLOCATED bit of Engine state is set, and the testEngineState(Engine.ALLOCATED) method returns true. During the processing of the method, the Engine is temporarily in the ALLOCATING_RESOURCES state.

While this method is being processed, events are issued to any EngineListeners attached to the Engine to indicate state changes (see setEngineMask for event filtering). First, as the Engine changes from the DEALLOCATED to the ALLOCATING_RESOURCES state, an ENGINE_ALLOCATING_RESOURCES event is issued. As the allocation process completes, the Engine moves from the ALLOCATING_RESOURCES state to the ALLOCATED state and an ENGINE_ALLOCATED event is issued.

The allocate method should be called for an Engine in the DEALLOCATED state. The method has no effect for an Engine in either the ALLOCATING_RESOURCES or ALLOCATED states. The method throws an exception in the DEALLOCATING_RESOURCES state.

If any problems are encountered during the allocation process so that the Engine cannot be allocated, the Engine returns to the DEALLOCATED state (with an ENGINE_DEALLOCATED event), and an EngineException is thrown.

Allocating the resources for an Engine may be fast (less than a second) or slow (several 10s of seconds) depending upon a range of factors. Since the allocate method does not return until allocation is completed, applications may use allocate(int) with a flag for asynchronous operation

When the Engine reaches the ALLOCATED state, other Engine substates are determined according to the type of Engine. Each Engine subclass provides more detail.

Recognizers throw SecurityException if the application does not have permission.

Specified by:

allocate in interface Engine

Throws:

AudioException - if any audio request fails

EngineException - if an allocation error occurred or the Engine is not operational.

EngineStateException - if called for an Engine in the DEALLOCATING_RESOURCES state

SecurityException - if the application does not have permission for this Engine

See Also:

allocate(int), deallocate(), getEngineState, ALLOCATED, ALLOCATING_RESOURCES, DEALLOCATED, EngineEvent, ENGINE_ALLOCATED, ENGINE_DEALLOCATED, setEngineMask

Required permission:

javax.speech.recognition.Recognizer.allocate

allocate

void allocate(int mode)
              throws IllegalArgumentException,
                     AudioException,
                     EngineException,
                     EngineStateException,
                     SecurityException

Allocates the resources required for this Engine using the mode specified and puts it into the ALLOCATED state.

When the mode is ASYNCHRONOUS_MODE, this method asynchronously allocates an Engine. In this case, the Engine transitions to ALLOCATING_RESOURCES before this method returns.

When mode is 0, this method operates the same as allocate().

waitEngineState may be used to wait for the ALLOCATED state.

 Engine engine;

 engine = EngineManager.createEngine(RecognizerMode.DEFAULT);
 engine.allocate(Engine.ASYNCHRONOUS_MODE);
 // Do other stuff while allocation takes place
 ...
 // Now wait until allocation is complete
 engine.waitEngineState(Engine.ALLOCATED);
 

Recognizers throw SecurityException if the application does not have permission.

Specified by:

allocate in interface Engine

Parameters:

mode - flag indicating the operational mode

Throws:

IllegalArgumentException - if called with an unexpected mode value

AudioException - if any audio access fails

EngineException - if an allocation error occurred or the Engine is not operational.

EngineStateException - if called for an Engine in the DEALLOCATING_RESOURCES state

SecurityException - if the application does not have permission for this Engine

See Also:

ASYNCHRONOUS_MODE, allocate(), deallocate(), getEngineState, ALLOCATED, ALLOCATING_RESOURCES, DEALLOCATED, EngineEvent, ENGINE_ALLOCATED, ENGINE_DEALLOCATED, setEngineMask, waitEngineState

Required permission:

javax.speech.recognition.Recognizer.allocate

deallocate

void deallocate()
                throws AudioException,
                       EngineException,
                       EngineStateException

Deallocates the resources acquired for this Engine and returns it to the DEALLOCATED state. When this method returns the DEALLOCATED bit of Engine state is set so the testEngineState(Engine.DEALLOCATED) method returns true. During the processing of the method, the Engine is temporarily in the DEALLOCATING_RESOURCES state.

A DEALLOCATED Engine can be restarted with a subsequent call to allocate.

Engines should normally clean up current activities before becoming DEALLOCATED. If needed, deallocate will wait for pending operations to complete appropriate for the type of Engine. The deallocate(int) method includes a flag to stop pending operations immediately.

Deallocating resources for an Engine is not always immediate. Use the deallocate(int) method with a flag for asynchronous operation. The documentation for the allocate(int) method shows an example of asynchronous operation

While this method is being processed, events are issued to any EngineListeners attached to the Engine to indicate state changes. First, as the Engine changes from the ALLOCATED to the DEALLOCATING_RESOURCES state, an ENGINE_DEALLOCATING_RESOURCES event is issued. As the deallocation process completes, the Engine moves from the DEALLOCATING_RESOURCES state to the DEALLOCATED state and an ENGINE_DEALLOCATED event is issued.

The deallocate method should only be called for an Engine in the ALLOCATED state. The method has no effect for an Engine in either the DEALLOCATING_RESOURCES or DEALLOCATED states. The method throws an exception in the ALLOCATING_RESOURCES state.

Specified by:

deallocate in interface Engine

Throws:

AudioException - if any audio request fails

EngineException - if a deallocation error occurs

EngineStateException - if called for an Engine in the ALLOCATING_RESOURCES state

See Also:

deallocate(int), allocate(), allocate(int), ASYNCHRONOUS_MODE, IMMEDIATE_MODE, DEALLOCATED, DEALLOCATING_RESOURCES, EngineEvent, ENGINE_DEALLOCATING_RESOURCES, ENGINE_DEALLOCATED

deallocate

void deallocate(int mode)
                throws IllegalArgumentException,
                       AudioException,
                       EngineException,
                       EngineStateException

Deallocates the resources acquired for this Engine using the mode specified and returns it to the DEALLOCATED state.

When using ASYNCHRONOUS_MODE, this method asynchronously deallocates an Engine. In this case, the Engine transitions to DEALLOCATING_RESOURCES before this method returns.

When using IMMEDIATE_MODE, this method causes the Engine to stop pending operations immediately before beginning the deallocation process.

The mode values may be combined. Calling deallocate(ASYNCHRONOUS_MODE | IMMEDIATE_MODE) combines the behavior of both modes.

When mode is 0, this method operates the same as deallocate().

Specified by:

deallocate in interface Engine

Parameters:

mode - flag indicating the operational mode

Throws:

IllegalArgumentException - if called with an unexpected mode value

AudioException - if any audio request fails

EngineException - if a deallocation error occurs

EngineStateException - if called for an Engine in the ALLOCATING_RESOURCES state

See Also:

deallocate(), allocate(), ASYNCHRONOUS_MODE, IMMEDIATE_MODE, DEALLOCATED, DEALLOCATING_RESOURCES, EngineEvent, ENGINE_DEALLOCATING_RESOURCES, ENGINE_DEALLOCATED, waitEngineState

pause

void pause()
           throws EngineStateException

Pauses the audio processing for this Engine and puts it into the PAUSED state. Pausing an Engine pauses the Engine instance and does not affect other Engine instances in the current application or other applications, even though they may use the same underlying resources.

Applications may pause an Engine indefinitely. When an Engine moves from the RESUMED state to the PAUSED state, an ENGINE_PAUSED event is issued to each EngineListener attached to the Engine. The PAUSED bit of the Engine state is set to true when paused, and can be tested by the getEngineState method and other Engine state methods.

The PAUSED state is a substate of the ALLOCATED state. An ALLOCATED Engine is always in either the PAUSED or the RESUMED state.

It is not an exception to pause an Engine that is already PAUSED.

The pause method does not always return immediately. Some applications may want to execute pause in a separate Thread.

Note that calls to pause and resume nest, so that there must be a resume for each pause in order for resume to operate as described.

This method operates as defined when the standard Conditions for Operation apply.

Operational detail depends on the particular Engine subinterface. For Engines that produce audio, pausing is analogous to pressing the "pause" button on a tape or CD player - audio output is paused and any unplayed audio is heard after resume. For Engines that consume audio, pausing is analogous to pressing a "mute" button on a microphone - by default, audio input is ignored and permanently lost. Audio processing does not begin again until after resume.

For a Recognizer, pausing stops processing of the audio input stream as close as possible to the time of the call to pause. By default, anything a user says while the Recognizer is PAUSED will not be heard by the Recognizer.

The pause(int) method provides more detail and options. This method is equivalent to pause(0).

Specified by:

pause in interface Engine

Throws:

EngineStateException - when not in the standard Conditions for Operation

See Also:

pause(int), resume, PAUSED, RESUMED, getEngineState, ENGINE_PAUSED

pause

void pause(int mode)
           throws IllegalArgumentException,
                  EngineStateException

Pauses a Recognizer with additional options. The pause() method describes the basic functionality.

For a Recognizer, pausing stops processing of the audio input stream as close as possible to the time of the call to pause. Pausing a Recognizer allows an application to modify Grammars and update activation.

By default (BUFFER_MODE not set), anything a user says while the Recognizer is paused will not be heard by the Recognizer. The BUFFER_MODE flag indicates that the Recognizer should buffer audio while PAUSED so that no audio will be lost once it returns to the LISTENING substate.

Pausing a Recognizer during the middle of user speech forces the Recognizer to finalize processing of that incoming speech - a recognition Result cannot cross a pause/resume boundary. Most Recognizers have some amount of internal audio buffering. This means that some Recognizer processing may continue after the call to pause. For example, Results can be created and finalized. The IMMEDIATE_MODE flag indicates that pending recognition buffers should be cleared instead of processed.

A Recognizer returns to the RESUMED state (and LISTENING substate) with a call to resume. However, calls to pause and resume nest, so that there must be a resume for each pause. This avoids Grammar update issues for multithreaded applications.

This method operates as defined when the standard Conditions for Operation apply.

Parameters:

mode - modifier flags to use with this method

Throws:

IllegalArgumentException - when called with an unexpected mode value

EngineStateException - when not in the standard Conditions for Operation

See Also:

pause(), BUFFER_MODE, IMMEDIATE_MODE, resume, PAUSED, RESUMED, LISTENING, getEngineState, ENGINE_PAUSED

resume

boolean resume()
               throws EngineStateException

Resumes audio processing for this Engine by entering the RESUMED state. Resuming an Engine instance does not affect other Engine instances that share the same underlying resources.

The pause method describes how to pause an Engine.

Note that calls to pause and resume nest, so that there must be a resume for each pause in order for this method to operate as described.

When an Engine moves from the PAUSED state to the RESUMED state, an ENGINE_RESUMED event is issued to each EngineListener attached to the Engine. The RESUMED bit of the Engine state is set when the Engine resumes, and can be tested by the getEngineState method and other Engine state methods.

The RESUMED state is a substate of the ALLOCATED state. An ALLOCATED Engine is always in either the PAUSED or the RESUMED state.

It is not an exception to resume an Engine that is already in the RESUMED state.

The resume method does not always return immediately. Some applications may want to execute resume in a separate Thread. The documentation for the Thread class shows examples of this.

This method operates as defined when the standard Conditions for Operation apply.

For a Recognizer, this method resumes processing the audio input stream as close as possible to the time of the call to resume. Recognition can only occur after calling resume.

When this method causes the Recognizer to enter the RESUMED state, any Grammar updates are atomically committed (see Committing Changes). It checks that all the loaded Grammars are ready to use. Any problems with the current definition of any RuleGrammar result in a CHANGES_REJECTED event. Problems might include an undefined RuleReference, illegal recursion and so on (see the SRGS definition for details).

Grammar updates are committed asynchronously (the changes have not necessarily been committed when the call returns). When the changes have been committed, a CHANGES_COMMITTED or CHANGES_REJECTED event is issued to all RecognizerListeners attached to this Recognizer. Corresponding to these events, GrammarListeners for any changed Grammars receive either a GRAMMAR_CHANGES_COMMITTED or GRAMMAR_CHANGES_REJECTED event.

Note that calling pause before resume is important to avoid Grammar update issues that can occur with ResultEvents and in multithreaded applications.

After any Grammar updates, the Recognizer enters the RESUMED state. It waits in the LISTENING substate until speech is found.

Specified by:

resume in interface Engine

Returns:

true if the Engine is in or is about to enter the RESUMED state; or false if it will remain PAUSED due to nested calls to pause.

Throws:

EngineStateException - when not in the standard Conditions for Operation

See Also:

pause, PAUSED, RESUMED, LISTENING, PROCESSING, getEngineState, ENGINE_RESUMED, CHANGES_COMMITTED, CHANGES_REJECTED, GRAMMAR_CHANGES_COMMITTED, GRAMMAR_CHANGES_REJECTED, RuleGrammar, RecognizerListener, GrammarListener, ResultEvent

Required Features:

getSupportsLetterToSound when the vocabulary specified is not known, results in a CHANGES_REJECTED event otherwise