javax.speech
Interface Engine

All Known Subinterfaces:

Recognizer, Synthesizer

public interface Engine

Parent interface for all speech Engines. A speech Engine is a generic entity that either processes speech input or produces speech output. Engine instances derive the following functionality from the Engine interface:

• allocate and deallocate methods.
• pause and resume methods.
• Access to an AudioManager and a VocabularyManager.
• Access to the Engine's EngineMode.
• Methods to add and remove EngineListener objects.

Engines are located, selected and created through methods of the EngineManager class.

Engine States

Each type of speech Engine has a well-defined set of states of operation, and well-defined behavior for moving between states. These states are defined by constants defined in the respective Engine interfaces.

The Engine interface defines three methods for viewing and monitoring states: getEngineState, waitEngineState and testEngineState. An EngineEvent is issued to EngineListeners each time an Engine changes state.

If at any point during normal operation an Engine runs out of memory, the ENGINE_ERROR event is thrown and the ERROR_OCCURRED state bit is set. Applications should be aware of this possibility, especially on small devices, and restart with fewer resource demands if possible.

See the Table of Diagrams for state transition diagrams.

Engine States: Allocation

The basic states of any speech Engine are DEALLOCATED, ALLOCATED, ALLOCATING_RESOURCES and DEALLOCATING_RESOURCES. An Engine in the ALLOCATED state has acquired all the resources it requires to perform its core functions.

Engines are created in the DEALLOCATED state and a call to allocate is required to prepare them for use. The ALLOCATING_RESOURCES state is an intermediate state between DEALLOCATED and ALLOCATED that an Engine occupies during the resource allocation process (which may be a very short period or take 10s of seconds).

Once an application finishes using a speech Engine it should always explicitly free system resources by calling the deallocate method. This call transitions the Engine to the DEALLOCATED state after some period of time in the DEALLOCATING_RESOURCES state.

The methods of an Engine instance perform differently according to the Engine's allocation state. Many methods cannot be performed when an Engine is in either the DEALLOCATED or DEALLOCATING_RESOURCES state. Many methods block (wait) for an Engine in the ALLOCATING_RESOURCES state until the Engine reaches the ALLOCATED state. This blocking/exception behavior is defined separately for each Engine subinterface.

Engine States: Substates of ALLOCATED

The ALLOCATED state has substates. (The DEALLOCATED, ALLOCATING_RESOURCES and DEALLOCATING_RESOURCES states do not have any substates.)

• Any ALLOCATED Engine is either PAUSED or RESUMED. These states indicate whether audio is being processed from/to the AudioManager.
• Engine subclasses define additional specific substates.

The pause and resume methods are used to transition an Engine instance between the PAUSED and RESUMED states. The PAUSED and RESUMED states of applications that use the same underlying resources operate independently. For instance, pausing an Engine instance within an application may cause that instance to stop processing audio during that time, but the underlying resources and any other Engine instances may continue to process audio.

Engine States: get/test/wait

The getEngineState method returns the current state of an Engine. The waitEngineState method blocks the calling Thread until the Engine reaches a specified state. The testEngineState method tests whether an Engine is in a specified state.

The state values can be bitwise OR'ed (using the "|" operator). For example, for an ALLOCATED, RESUMED Engine the state may be tested with

 Engine.ALLOCATED | Engine.RESUMED
 

Subinterfaces of Engine add additional states that may be combined with the basic Engine states for these methods.

The states and substates defined above put constraints upon the state of an Engine. The following are examples of illegal Engine states:

 Engine.DEALLOCATED | Engine.RESUMED
 Engine.ALLOCATED | Engine.DEALLOCATED
 

Calls to the testEngineState and waitEngineState methods with illegal state values cause an exception to be thrown.

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

Field Summary

static long	ALLOCATED Bit of state that is set when an Engine has been allocated.
static long	ALLOCATING_RESOURCES Bit of state that is set when an Engine is being allocated.
static int	ASYNCHRONOUS_MODE Constant value indicating asynchronous mode for a method.
static long	DEALLOCATED Bit of state that is set when an Engine has become deallocated.
static long	DEALLOCATING_RESOURCES Bit of state that is set when an Engine is becoming DEALLOCATED.
static long	DEFOCUSED Bit of state that is set when an ALLOCATED Engine does not have the speech focus of the underlying resources.
static long	ERROR_OCCURRED Bit of state that is set after an ENGINE_ERROR event occurs.
static long	FOCUSED Bit of state that is set when an ALLOCATED Engine has the speech focus of the underlying resources.
static int	IMMEDIATE_MODE Constant value indicating immediate mode for a method.
static long	PAUSED Bit of state that is set when an Engine is in the ALLOCATED state and is PAUSED.
static long	RESUMED Bit of state that is set when an Engine is in the ALLOCATED state and is RESUMED.

Method Summary

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.
AudioManager	getAudioManager() Returns an AudioManager that manages audio input or output for this Engine.
int	getEngineMask() Gets the mask used to filter events for added EngineListeners.
EngineMode	getEngineMode() Returns the operating modes of this Engine.
long	getEngineState() Returns an OR'ed set of flags indicating the current state of this Engine.
SpeechEventExecutor	getSpeechEventExecutor() Returns the SpeechEventExecutor for this Engine.
VocabularyManager	getVocabularyManager() Returns an Object that provides management of the vocabulary for this Engine.
void	pause() Pauses the audio processing for this Engine and puts it into the PAUSED state.
boolean	resume() Resumes audio processing for this Engine by entering the RESUMED state.
void	setEngineMask(int mask) Sets the mask to filter events for added EngineListeners.
void	setSpeechEventExecutor(SpeechEventExecutor speechEventExecutor) Sets the SpeechEventExecutor used to fire events for this Engine.
boolean	testEngineState(long state) Returns true if the current Engine state matches the specified state.
long	waitEngineState(long state) Blocks the calling Thread until the Engine is in a specified state.
long	waitEngineState(long state, long timeout) Blocks the calling Thread until the Engine is in a specified state, or a specified timeout has elapsed.

Field Detail

ALLOCATED

static final long ALLOCATED

Bit of state that is set when an Engine has been allocated. An Engine in the ALLOCATED state has acquired the resources required for it to carry out its core functions.

The ALLOCATED state has substates for RESUMED and PAUSED. Subinterfaces of Engine may define additional substates of ALLOCATED.

An Engine is always created in the DEALLOCATED state. It reaches the ALLOCATED state via the ALLOCATING_RESOURCES state with a call to the allocate method.

See Also:

allocate, DEALLOCATED, ALLOCATING_RESOURCES, ENGINE_ALLOCATED, PAUSED, RESUMED, getEngineState, testEngineState, waitEngineState, Constant Field Values

ALLOCATING_RESOURCES

static final long ALLOCATING_RESOURCES

Bit of state that is set when an Engine is being allocated. This is the transition state between DEALLOCATED and ALLOCATED following a call to the allocate method.

The ALLOCATING_RESOURCES state has no substates. In the ALLOCATING_RESOURCES state, many Engine methods will block until the Engine reaches the ALLOCATED state and the action can be performed.

See Also:

DEALLOCATED, allocate, ALLOCATED, EngineEvent.ENGINE_ALLOCATING_RESOURCES, getEngineState, testEngineState, waitEngineState, Constant Field Values

DEALLOCATED

static final long DEALLOCATED

Bit of state that is set when an Engine has become deallocated. An Engine in the DEALLOCATED state does not have the resources necessary for it to carry out its basic functions.

The DEALLOCATED state has no substates. In the DEALLOCATING_RESOURCES state, many Engine methods throw an exception when called.

An Engine is always created in the DEALLOCATED state. A DEALLOCATED state can transition to the ALLOCATED state via the ALLOCATING_RESOURCES state following a call to the allocate method. An Engine returns to the DEALLOCATED state via the DEALLOCATING_RESOURCES state with a call to the deallocate method.

See Also:

allocate, deallocate, ALLOCATED, DEALLOCATING_RESOURCES, EngineEvent.ENGINE_DEALLOCATED, getEngineState, testEngineState, waitEngineState, Constant Field Values

DEALLOCATING_RESOURCES

static final long DEALLOCATING_RESOURCES

Bit of state that is set when an Engine is becoming DEALLOCATED. This is the transition state between ALLOCATED and DEALLOCATED following a call to the deallocate method.

The DEALLOCATING_RESOURCES state has no substates. In the DEALLOCATING_RESOURCES state, many Engine methods throw an exception when called.

See Also:

deallocate, ALLOCATED, DEALLOCATED, ENGINE_DEALLOCATING_RESOURCES, getEngineState, testEngineState, waitEngineState, Constant Field Values

PAUSED

static final long PAUSED

Bit of state that is set when an Engine is in the ALLOCATED state and is PAUSED. In the PAUSED state, audio input or output processing is paused. Engine subinterfaces describe details in the pause method.

An ALLOCATED Engine is always in either the PAUSED or RESUMED state. The PAUSED and RESUMED states are substates of the ALLOCATED state.

See Also:

RESUMED, ALLOCATED, ENGINE_PAUSED, pause(), getEngineState, testEngineState, waitEngineState, Constant Field Values

RESUMED

static final long RESUMED

Bit of state that is set when an Engine is in the ALLOCATED state and is RESUMED. In the RESUMED state, audio input or output is processed. Engine subinterfaces describe details in the resume method.

An ALLOCATED Engine is always in either the PAUSED or RESUMED state. The PAUSED and RESUMED states are substates of the ALLOCATED state.

See Also:

PAUSED, ALLOCATED, ENGINE_RESUMED, resume(), getEngineState, testEngineState, waitEngineState, Constant Field Values

DEFOCUSED

static final long DEFOCUSED

Bit of state that is set when an ALLOCATED Engine does not have the speech focus of the underlying resources.

As focus is gained and lost, an ENGINE_FOCUSED or ENGINE_DEFOCUSED event is issued to indicate the state change. Details of focus management depend on the type of Engine and are explained in the "Focus Policy" section for each kind of Engine subinterface.

See Also:

FOCUSED, ENGINE_DEFOCUSED, getEngineState, testEngineState, waitEngineState, Constant Field Values

FOCUSED

static final long FOCUSED

Bit of state that is set when an ALLOCATED Engine has the speech focus of the underlying resources.

As focus is gained and lost, an ENGINE_FOCUSED or ENGINE_DEFOCUSED event is issued to indicate the state change. Details of focus management depend on the type of Engine and are explained in the "Focus Policy" section for each kind of Engine interface.

See Also:

DEFOCUSED, ENGINE_FOCUSED, getEngineState, testEngineState, waitEngineState, Constant Field Values

ERROR_OCCURRED

static final long ERROR_OCCURRED

Bit of state that is set after an ENGINE_ERROR event occurs.

In the ERROR_OCCURRED state, many of the methods of an Engine throw an exception when called. The ERROR_OCCURRED state has no substates.

See Also:

ENGINE_ERROR, getEngineState, testEngineState, waitEngineState, Constant Field Values

ASYNCHRONOUS_MODE

static final int ASYNCHRONOUS_MODE

Constant value indicating asynchronous mode for a method.

See Also:

allocate(int), allocate(int), Constant Field Values

IMMEDIATE_MODE

static final int IMMEDIATE_MODE

Constant value indicating immediate mode for a method.

See Also:

deallocate(int), Constant Field Values

Method Detail

setEngineMask

void setEngineMask(int mask)

Sets the mask to filter events for added EngineListeners.

Masking unused events can improve efficiency. Events of interest can be seen by using the logical OR of the event constants defined in the EngineEvent class. EngineEvent.DEFAULT_MASK is the initial value.

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

Parameters:

mask - the mask for EngineEvents

See Also:

DEFAULT_MASK, EngineEvent, EngineListener, getEngineMask

getEngineMask

int getEngineMask()

Gets the mask used to filter events for added EngineListeners. See setEngineMask for details.

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

Returns:

the current mask for Engine events

See Also:

setEngineMask

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.

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:

defined by subinterfaces

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);
 

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:

defined by subinterfaces

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.

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().

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

getAudioManager

AudioManager getAudioManager()

Returns an AudioManager that manages audio input or output for this Engine. Each Engine instance gets its own AudioManager.

The AudioManager is available in any state of an Engine.

Returns:

the AudioManager for this Engine

getEngineMode

EngineMode getEngineMode()

Returns the operating modes of this Engine. Engine implementations will also subclass EngineMode.

The EngineMode is available in any state of an Engine.

Returns:

an EngineMode for this Engine

getEngineState

long getEngineState()

Returns an OR'ed set of flags indicating the current state of this Engine. The format of the returned state value is described in the get/test/wait section.

An EngineEvent is issued each time the Engine changes state.

The getEngineState method can be called successfully in any Engine state.

Returns:

flags indicating the current state

See Also:

testEngineState, waitEngineState, EngineEvent

getVocabularyManager

VocabularyManager getVocabularyManager()

Returns an Object that provides management of the vocabulary for this Engine. Returns null if the Engine does not provide vocabulary management capabilities. Note that a VocabularyManager is not shared between Engine instances. This method may be called in any state of an Engine.

The VocabularyManager documentation describes vocabularies and their use with speech Engines.

Returns:

the VocabularyManager for the Engine or null if it does not have one

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.

Throws:

EngineStateException - when not in the standard Conditions for Operation

See Also:

resume, 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.

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, getEngineState, ENGINE_RESUMED, Thread

testEngineState

boolean testEngineState(long state)
                        throws IllegalArgumentException

Returns true if the current Engine state matches the specified state. The format of the state value is described in the get/test/wait section.

The test performed is not an exact match to the current state. Only the specified states are tested. For example, the following returns true only if the Engine has reached the RESUMED state, irrespective of allocation state.

 if (engine.testEngineState(Engine.RESUMED)) ...
 

The testEngineState method is equivalent to:

 if ((engine.getEngineState() & state) == state)
 

The testEngineState method can be called successfully in any Engine state.

Parameters:

state - a set of states to test

Returns:

true if the indicated state bits are set

Throws:

IllegalArgumentException - if the specified state is impossible

See Also:

getEngineState, waitEngineState, EngineEvent

waitEngineState

long waitEngineState(long state,
                     long timeout)
                     throws InterruptedException,
                            IllegalArgumentException,
                            IllegalStateException

Blocks the calling Thread until the Engine is in a specified state, or a specified timeout has elapsed. The format of the state value is described in the get/test/wait section.

This method returns when

1. All state bits specified in the state parameter must be set in order for the method to return, as defined for the testEngineState method.
2. The timeout time in milliseconds has elapsed, more or less. If timeout is zero, however, it is ignored and only the first condition applies.

The return value is the set of state bits available when the return was decided. This information may be used as follows:

 if (waitEngineState(state, timeout) & state == state) {
     // state matching branch
 }
 else {
     // timeout matching branch
 }
 

If the state parameter defines an impossible state (e.g. PAUSED | RESUMED), an IllegalArgumentException is thrown.

If the requested state becomes unreachable, an IllegalStateException is thrown. This can happen, for example, if waiting for the RESUMED state, but deallocate is called. All states except ALLOCATING_RESOURCES become unreachable from the DEALLOCATED state. All states become unreachable from the ERROR_OCCURRED state.

The waitEngineState method can be called successfully in any Engine state.

Parameters:

state - a set of Engine state bits

timeout - the maximum time to wait in milliseconds

Returns:

the set of state bits when return is decided

Throws:

InterruptedException - if another Thread has interrupted this Thread

IllegalArgumentException - if the specified state is impossible or timeout is negative

IllegalStateException - if the specified state is or becomes unreachable

See Also:

waitEngineState(long), testEngineState, getEngineState, EngineEvent

waitEngineState

long waitEngineState(long state)
                     throws InterruptedException,
                            IllegalArgumentException,
                            IllegalStateException

Blocks the calling Thread until the Engine is in a specified state. This method behaves exactly the same as a call to waitEngineState(state, 0). See that method for details.

Parameters:

state - a set of Engine state bits

Returns:

the set of state bits when the method returns

Throws:

InterruptedException - if another Thread has interrupted this Thread

IllegalArgumentException - if the specified state is impossible

IllegalStateException - if the specified state is or becomes unreachable

See Also:

waitEngineState(long,long), testEngineState, getEngineState, EngineEvent

getSpeechEventExecutor

SpeechEventExecutor getSpeechEventExecutor()

Returns the SpeechEventExecutor for this Engine. Applications can use this to synchronize SpeechEvents with other event queues.

The default is null meaning that the default Executor will be used.

Returns:

the current SpeechEventExecutor

See Also:

setSpeechEventExecutor

setSpeechEventExecutor

void setSpeechEventExecutor(SpeechEventExecutor speechEventExecutor)

Sets the SpeechEventExecutor used to fire events for this Engine. Applications can use this to synchronize SpeechEvents with other event queues. This applies to all SpeechEvents fired by this Engine and associated components (e.g., AudioManager and EngineProperties).

By default, SpeechEvents are delivered to applications using a Thread internal to the Engine implementation. Developers should be careful to avoid blocking this callback Thread for extended periods of time.

By setting a custom SpeechEventExecutor, applications can control which Thread the Engine implementation will use to fire events. This allows applications to synchronize SpeechEvents with, for example, user interface events on the deployment platform.

A MIDlet developer might use the following to synchronize event delivery with the UI event Thread:

 // Ensure speech events arrive on a MIDlet's UI thread
 Engine engine = ...
 engine.setSpeechEventExecutor(new SpeechEventExecutor() {
   public void execute(Runnable r) {
     javax.microedition.lcdui.Display.getDisplay(this).callSerially(r);
   }
 });
 

Whereas an AWT or Swing developer might want to synchronize with the AWT/Swing event Thread:

 // Ensure speech events arrive on an AWT or Swing UI thread
 Engine engine = ...
 engine.setSpeechEventExecutor(new SpeechEventExecutor() {
   public void execute(Runnable r) {
     java.awt.EventQueue.invokeLater(r);
   }
 });
 

A server-side developer might use this feature to control the Thread pool used to deliver events.

A null argument for speechEventExecutor causes the default executor to be used.

Parameters:

speechEventExecutor - the executor to use to dispatch events, or null to use the Engine's default

See Also:

getSpeechEventExecutor, SpeechEvent