com.sun.speech.engine
Class BaseEngine

java.lang.Object
  com.sun.speech.engine.BaseEngine

All Implemented Interfaces:

javax.speech.Engine, SpeechEventDispatcher

Direct Known Subclasses:

BaseSynthesizer

public abstract class BaseEngine

extends java.lang.Object

implements javax.speech.Engine, SpeechEventDispatcher

Supports the JSAPI 1.0 Engine interface. Actual JSAPI implementations might want to extend or modify this implementation.

Field Summary

protected javax.speech.AudioManager	audioManager The AudioManager for this Engine.
protected static long	CLEAR_ALL_STATE Utility state for clearing the engineState.
protected java.util.Vector	engineListeners List of EngineListeners registered for EngineEvents on this Engine.
protected javax.speech.EngineModeDesc	engineModeDesc The EngineModeDesc for this Engine.
protected javax.speech.EngineProperties	engineProperties The EngineProperties for this Engine.
protected long	engineState A bitmask holding the current state of this Engine.
protected java.lang.Object	engineStateLock An Object used for synchronizing access to engineState.

Fields inherited from interface javax.speech.Engine

ALLOCATED, ALLOCATING_RESOURCES, DEALLOCATED, DEALLOCATING_RESOURCES, PAUSED, RESUMED

Constructor Summary

BaseEngine()
Creates a new Engine in the DEALLOCATED state.

BaseEngine(javax.speech.EngineModeDesc desc)
Creates a new Engine in the DEALLOCATED state.

Method Summary

void	addEngineListener(javax.speech.EngineListener listener) Requests notification of EngineEvents from this Engine.
void	allocate() Allocates the resources required for this Engine and puts it into the ALLOCATED state.
protected void	checkEngineState(long state) Convenience method that throws an EngineStateError if any of the bits in the passed state are set in the state.
protected abstract BaseEngineProperties	createEngineProperties() Factory constructor for EngineProperties object.
void	deallocate() Frees the resources of this Engine that were acquired during allocation and during operation and return this Engine to the DEALLOCATED.
void	dispatchSpeechEvent(javax.speech.SpeechEvent event) Dispatches a SpeechEvent.
void	fireEngineAllocated(javax.speech.EngineEvent event) Utility function that sends an ENGINE_ALLOCATED event to all EngineListeners registered with this Engine.
void	fireEngineAllocatingResources(javax.speech.EngineEvent event) Utility function that sends an ENGINE_ALLOCATING_RESOURCES event to all EngineListeners registered with this Engine.
void	fireEngineDeallocated(javax.speech.EngineEvent event) Utility function that sends an ENGINE_DEALLOCATED event to all EngineListeners registered with this Engine.
void	fireEngineDeallocatingResources(javax.speech.EngineEvent event) Utility function that sends a ENGINE_DEALLOCATING_RESOURCES event to all EngineListeners registered with this Engine.
void	fireEnginePaused(javax.speech.EngineEvent event) Utility function that sends an ENGINE_PAUSED event to all EngineListeners registered with this Engine.
void	fireEngineResumed(javax.speech.EngineEvent event) Utility function that sends an ENGINE_RESUMED event to all EngineListeners registered with this Engine.
javax.speech.AudioManager	getAudioManager() Returns an object that provides management of the audio input or output of this Engine.
javax.speech.EngineModeDesc	getEngineModeDesc() Gets the current operating properties and mode of this Engine.
javax.speech.EngineProperties	getEngineProperties() Gets the EngineProperties of this Engine.
long	getEngineState() Returns a or'ed set of flags indicating the current state of this Engine.
javax.speech.VocabManager	getVocabManager() Returns an object that provides management of the vocabulary for this Engine.
protected abstract void	handleAllocate() Called from the allocate method.
protected abstract void	handleDeallocate() Called from the deallocate method.
protected abstract void	handlePause() Called from the pause method.
protected abstract void	handleResume() Called from the resume method.
void	pause() Pauses the audio stream for this Engine and put this Engine into the PAUSED state.
protected void	postEngineAllocated(long oldState, long newState) Utility function that generates an ENGINE_ALLOCATED event and posts it to the event queue.
protected void	postEngineAllocatingResources(long oldState, long newState) Utility function that generates an ENGINE_ALLOCATING_RESOURCES event and posts it to the event queue.
protected void	postEngineDeallocated(long oldState, long newState) Utility function that generates an ENGINE_DEALLOCATED event and posts it to the event queue.
protected void	postEngineDeallocatingResources(long oldState, long newState) Utility function that generates ENGINE_DEALLOCATING_RESOURCES event and posts it to the event queue.
protected void	postEnginePaused(long oldState, long newState) Utility function that generates an ENGINE_PAUSED event and posts it to the event queue.
protected void	postEngineResumed(long oldState, long newState) Utility function that generates an ENGINE_RESUMED event and posts it to the event queue.
void	removeEngineListener(javax.speech.EngineListener listener) Removes an EngineListener from the list of EngineListeners.
void	resume() Resumes the audio stream for this Engine and put this Engine into the RESUMED state.
protected void	setEngineModeDesc(javax.speech.EngineModeDesc desc) Sets the current operating properties and mode of this Engine.
protected long[]	setEngineState(long clear, long set) Updates this Engine state by clearing defined bits, then setting other specified bits.
protected java.lang.String	stateToString(long state) Returns a String of the names of all the Engine states in the given Engine state.
boolean	testEngineState(long state) Returns true if this state of this Engine matches the specified state.
java.lang.String	toString() Returns the engine name and mode for debug purposes.
void	waitEngineState(long state) Blocks the calling thread until this Engine is in a specified state.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

engineState

protected long engineState

A bitmask holding the current state of this Engine.

engineStateLock

protected java.lang.Object engineStateLock

An Object used for synchronizing access to engineState.

See Also:

engineState

engineListeners

protected java.util.Vector engineListeners

List of EngineListeners registered for EngineEvents on this Engine.

audioManager

protected javax.speech.AudioManager audioManager

The AudioManager for this Engine.

engineModeDesc

protected javax.speech.EngineModeDesc engineModeDesc

The EngineModeDesc for this Engine.

engineProperties

protected javax.speech.EngineProperties engineProperties

The EngineProperties for this Engine.

CLEAR_ALL_STATE

protected static final long CLEAR_ALL_STATE

Utility state for clearing the engineState.

See Also:

Constant Field Values

Constructor Detail

BaseEngine

public BaseEngine()

Creates a new Engine in the DEALLOCATED state.

BaseEngine

public BaseEngine(javax.speech.EngineModeDesc desc)

Creates a new Engine in the DEALLOCATED state.

Parameters:

desc - the operating mode of this Engine

Method Detail

getEngineState

public long getEngineState()

Returns a or'ed set of flags indicating the current state of this Engine.

An EngineEvent is issued each time this Engine changes state.

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

Specified by:

getEngineState in interface javax.speech.Engine

Returns:

the current state of this Engine

See Also:

getEngineState(), waitEngineState(long)

waitEngineState

public void waitEngineState(long state)
                     throws java.lang.InterruptedException,
                            java.lang.IllegalArgumentException

Blocks the calling thread until this Engine is in a specified state.

All state bits specified in the state parameter must be set in order for the method to return, as defined for the testEngineState method. If the state parameter defines an unreachable state (e.g. PAUSED | RESUMED) an exception is thrown.

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

Specified by:

waitEngineState in interface javax.speech.Engine

Parameters:

state - a bitmask of the state to wait for

Throws:

java.lang.InterruptedException - if another thread has interrupted this thread.

java.lang.IllegalArgumentException - if the specified state is unreachable

See Also:

testEngineState(long), getEngineState()

testEngineState

public boolean testEngineState(long state)
                        throws java.lang.IllegalArgumentException

Returns true if this state of this Engine matches the specified state.

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 Synthesizer queue is empty, irrespective of the pause/resume and allocation states.

    if (synth.testEngineState(Synthesizer.QUEUE_EMPTY)) ...
 

The testEngineState method is equivalent to:

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

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

Specified by:

testEngineState in interface javax.speech.Engine

Parameters:

state - a bitmask of the states to test for

Returns:

true if this Engine matches state; otherwise false

Throws:

java.lang.IllegalArgumentException - if the specified state is unreachable

setEngineState

protected long[] setEngineState(long clear,
                                long set)

Updates this Engine state by clearing defined bits, then setting other specified bits.

Returns:

a length-2 array with old and new state values.

allocate

public void allocate()
              throws javax.speech.EngineException,
                     javax.speech.EngineStateError

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

During the processing of the method, this Engine is temporarily in the ALLOCATING_RESOURCES state.

Specified by:

allocate in interface javax.speech.Engine

Throws:

javax.speech.EngineException - if this Engine cannot be allocated

javax.speech.EngineStateError - if this Engine is in the DEALLOCATING_RESOURCES state

See Also:

deallocate()

handleAllocate

protected abstract void handleAllocate()
                                throws javax.speech.EngineException

Called from the allocate method. Override this in subclasses.

Throws:

javax.speech.EngineException - if problems are encountered

See Also:

allocate()

deallocate

public void deallocate()
                throws javax.speech.EngineException,
                       javax.speech.EngineStateError

Frees the resources of this Engine that were acquired during allocation and during operation and return this Engine to the DEALLOCATED. When this method returns the DEALLOCATED bit of this Engine state is set so the testEngineState(Engine.DEALLOCATED) method returns true.

During the processing of the method, this Engine is temporarily in the DEALLOCATING_RESOURCES state.

A deallocated engine can be re-started with a subsequent call to allocate.

Specified by:

deallocate in interface javax.speech.Engine

Throws:

javax.speech.EngineException - if this Engine cannot be deallocated

javax.speech.EngineStateError - if this Engine is in the ALLOCATING_RESOURCES state

See Also:

allocate()

handleDeallocate

protected abstract void handleDeallocate()
                                  throws javax.speech.EngineException

Called from the deallocate method. Override this in subclasses.

Throws:

javax.speech.EngineException - if this Engine cannot be deallocated.

pause

public void pause()
           throws javax.speech.EngineStateError

Pauses the audio stream for this Engine and put this Engine into the PAUSED state.

Specified by:

pause in interface javax.speech.Engine

Throws:

javax.speech.EngineStateError - if this Engine is in the DEALLOCATING_RESOURCES or DEALLOCATED state.

handlePause

protected abstract void handlePause()

Called from the pause method. Override this in subclasses.

resume

public void resume()
            throws javax.speech.AudioException,
                   javax.speech.EngineStateError

Resumes the audio stream for this Engine and put this Engine into the RESUMED state.

Specified by:

resume in interface javax.speech.Engine

Throws:

javax.speech.AudioException - if unable to gain access to the audio channel

javax.speech.EngineStateError - if this Engine is in the DEALLOCATING_RESOURCES or DEALLOCATED state

handleResume

protected abstract void handleResume()

Called from the resume method. Override in subclasses.

getAudioManager

public javax.speech.AudioManager getAudioManager()

Returns an object that provides management of the audio input or output of this Engine.

Specified by:

getAudioManager in interface javax.speech.Engine

Returns:

the audio manader for this Engine

getVocabManager

public javax.speech.VocabManager getVocabManager()
                                          throws javax.speech.EngineStateError

Returns an object that provides management of the vocabulary for this Engine. Returns null if this Engine does not support vocabulary management.

Specified by:

getVocabManager in interface javax.speech.Engine

Returns:

the vocabulary manager of this Engine

Throws:

javax.speech.EngineStateError - if this Engine in the DEALLOCATING_RESOURCES or DEALLOCATED state

getEngineProperties

public javax.speech.EngineProperties getEngineProperties()

Gets the EngineProperties of this Engine. Must be set in subclasses.

Specified by:

getEngineProperties in interface javax.speech.Engine

Returns:

the EngineProperties of this Engine.

getEngineModeDesc

public javax.speech.EngineModeDesc getEngineModeDesc()
                                              throws java.lang.SecurityException

Gets the current operating properties and mode of this Engine.

Specified by:

getEngineModeDesc in interface javax.speech.Engine

Returns:

the operating mode of this Engine

Throws:

java.lang.SecurityException

setEngineModeDesc

protected void setEngineModeDesc(javax.speech.EngineModeDesc desc)

Sets the current operating properties and mode of this Engine.

Parameters:

desc - the new operating mode of this Engine

addEngineListener

public void addEngineListener(javax.speech.EngineListener listener)

Requests notification of EngineEvents from this Engine.

Specified by:

addEngineListener in interface javax.speech.Engine

Parameters:

listener - the listener to add.

removeEngineListener

public void removeEngineListener(javax.speech.EngineListener listener)

Removes an EngineListener from the list of EngineListeners.

Specified by:

removeEngineListener in interface javax.speech.Engine

Parameters:

listener - the listener to remove.

postEngineAllocated

protected void postEngineAllocated(long oldState,
                                   long newState)

Utility function that generates an ENGINE_ALLOCATED event and posts it to the event queue. Eventually fireEngineAllocated will be called by the dispatchSpeechEvent as a result of this action.

Parameters:

oldState - the old state of this Engine

newState - the new state of this Engine

See Also:

fireEngineAllocated(javax.speech.EngineEvent), dispatchSpeechEvent(javax.speech.SpeechEvent)

fireEngineAllocated

public void fireEngineAllocated(javax.speech.EngineEvent event)

Utility function that sends an ENGINE_ALLOCATED event to all EngineListeners registered with this Engine. Called by dispatchSpeechEvent.

Parameters:

event - the ENGINE_ALLOCATED event

See Also:

postEngineAllocated(long, long), dispatchSpeechEvent(javax.speech.SpeechEvent)

postEngineAllocatingResources

protected void postEngineAllocatingResources(long oldState,
                                             long newState)

Utility function that generates an ENGINE_ALLOCATING_RESOURCES event and posts it to the event queue. Eventually fireEngineAllocatingResources will be called by dispatchSpeechEvent as a result of this action.

Parameters:

oldState - the old state of this Engine

newState - the new state of this Engine

See Also:

fireEngineAllocatingResources(javax.speech.EngineEvent), dispatchSpeechEvent(javax.speech.SpeechEvent)

fireEngineAllocatingResources

public void fireEngineAllocatingResources(javax.speech.EngineEvent event)

Utility function that sends an ENGINE_ALLOCATING_RESOURCES event to all EngineListeners registered with this Engine. Called by dispatchSpeechEvent.

Parameters:

event - the ENGINE_ALLOCATING_RESOURCES event

See Also:

postEngineAllocatingResources(long, long), dispatchSpeechEvent(javax.speech.SpeechEvent)

postEngineDeallocated

protected void postEngineDeallocated(long oldState,
                                     long newState)

Utility function that generates an ENGINE_DEALLOCATED event and posts it to the event queue. Eventually fireEngineDeallocated will be called by dispatchSpeechEvent as a result of this action.

Parameters:

oldState - the old state of this Engine

newState - the new state of this Engine

See Also:

fireEngineDeallocated(javax.speech.EngineEvent), dispatchSpeechEvent(javax.speech.SpeechEvent)

fireEngineDeallocated

public void fireEngineDeallocated(javax.speech.EngineEvent event)

Utility function that sends an ENGINE_DEALLOCATED event to all EngineListeners registered with this Engine. Called by dispatchSpeechEvent.

Parameters:

event - the ENGINE_DEALLOCATED event

See Also:

postEngineDeallocated(long, long), dispatchSpeechEvent(javax.speech.SpeechEvent)

postEngineDeallocatingResources

protected void postEngineDeallocatingResources(long oldState,
                                               long newState)

Utility function that generates ENGINE_DEALLOCATING_RESOURCES event and posts it to the event queue. Eventually fireEngineAllocatingResources will be called by dispatchSpeechEvent as a result of this action.

Parameters:

oldState - the old state of this Engine

newState - the new state of this Engine

See Also:

fireEngineDeallocatingResources(javax.speech.EngineEvent), dispatchSpeechEvent(javax.speech.SpeechEvent)

fireEngineDeallocatingResources

public void fireEngineDeallocatingResources(javax.speech.EngineEvent event)

Utility function that sends a ENGINE_DEALLOCATING_RESOURCES event to all EngineListeners registered with this Engine. Called by dispatchSpeechEvent.

Parameters:

event - the ENGINE_DEALLOCATING_RESOURCES event

See Also:

postEngineDeallocatingResources(long, long), dispatchSpeechEvent(javax.speech.SpeechEvent)

postEnginePaused

protected void postEnginePaused(long oldState,
                                long newState)

Utility function that generates an ENGINE_PAUSED event and posts it to the event queue. Eventually fireEnginePaused will be called by dispatchSpeechEvent as a result of this action.

Parameters:

oldState - the old state of this Engine

newState - the new state of this Engine

See Also:

fireEnginePaused(javax.speech.EngineEvent), dispatchSpeechEvent(javax.speech.SpeechEvent)

fireEnginePaused

public void fireEnginePaused(javax.speech.EngineEvent event)

Utility function that sends an ENGINE_PAUSED event to all EngineListeners registered with this Engine. Called by dispatchSpeechEvent.

Parameters:

event - the ENGINE_PAUSED event

See Also:

postEnginePaused(long, long), dispatchSpeechEvent(javax.speech.SpeechEvent)

postEngineResumed

protected void postEngineResumed(long oldState,
                                 long newState)

Utility function that generates an ENGINE_RESUMED event and posts it to the event queue. Eventually fireEngineResumed will be called by dispatchSpeechEvent as a result of this action.

Parameters:

oldState - the old state of this Engine

newState - the new state of this Engine

See Also:

fireEngineResumed(javax.speech.EngineEvent), dispatchSpeechEvent(javax.speech.SpeechEvent)

fireEngineResumed

public void fireEngineResumed(javax.speech.EngineEvent event)

Utility function that sends an ENGINE_RESUMED event to all EngineListeners registered with this Engine. Called by dispatchSpeechEvent.

Parameters:

event - the ENGINE_RESUMED event

See Also:

postEngineResumed(long, long), dispatchSpeechEvent(javax.speech.SpeechEvent)

createEngineProperties

protected abstract BaseEngineProperties createEngineProperties()

Factory constructor for EngineProperties object.

Returns:

a BaseEngineProperties object specific to a subclass.

checkEngineState

protected void checkEngineState(long state)
                         throws javax.speech.EngineStateError

Convenience method that throws an EngineStateError if any of the bits in the passed state are set in the state.

Parameters:

state - the Engine state to check

Throws:

javax.speech.EngineStateError - if any of the bits in the passed state are set in the state

stateToString

protected java.lang.String stateToString(long state)

Returns a String of the names of all the Engine states in the given Engine state.

Parameters:

state - the bitmask of states

Returns:

a String containing the names of all the states set in state

dispatchSpeechEvent

public void dispatchSpeechEvent(javax.speech.SpeechEvent event)

Dispatches a SpeechEvent. The dispatcher should notify all EngineListeners from this method. The SpeechEvent was added via the various post methods of this class.

Specified by:

dispatchSpeechEvent in interface SpeechEventDispatcher

Parameters:

event - the SpeechEvent to dispatch

See Also:

postEngineAllocatingResources(long, long), postEngineAllocated(long, long), postEngineDeallocatingResources(long, long), postEngineDeallocated(long, long), postEnginePaused(long, long), postEngineResumed(long, long)

toString

public java.lang.String toString()

Returns the engine name and mode for debug purposes.

Returns:

the engine name and mode.