Package com.sun.speech.engine

# Class BaseEngine

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

All Implemented Interfaces:
  `SpeechEventDispatcher`

Direct Known Subclasses:
  `BaseSynthesizer`

public abstract class BaseEngine extends Object implements SpeechEventDispatcher
Supports the JSAPI 1.0 `Engine` interface. Actual JSAPI implementations might want to extend or modify this implementation.

## Field Summary

Fields
Modifier and Type
Field
Description
`protected AudioManager`
`audioManager`
The `AudioManager` for this `Engine`.
`protected static final long`
`CLEAR_ALL_STATE`
Utility state for clearing the `engineState`.
`protected Collection`
`engineListeners`
List of `EngineListeners` registered for `EngineEvents` on this `Engine`.
`protected EngineModeDesc`
`engineModeDesc`
The `EngineModeDesc` for this `Engine`.
`protected EngineProperties`
`engineProperties`
The `EngineProperties` for this `Engine`.
`protected long`
`engineState`
A bitmask holding the current state of this `Engine`.
`protected Object`
`engineStateLock`
An `Object` used for synchronizing access to `engineState`.

## Constructor Summary

Constructors
Constructor
Description
`BaseEngine()`
Creates a new `Engine` in the `DEALLOCATED` state.
`BaseEngine(EngineModeDesc desc)`
Creates a new `Engine` in the `DEALLOCATED` state.

## Method Summary

Modifier and Type
Method
Description
`void`
`addEngineListener(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(SpeechEvent event)`
Dispatches a `SpeechEvent`.
`void`
`fireEngineAllocated(EngineEvent event)`
Utility function that sends an `ENGINE_ALLOCATED` event to all `EngineListeners` registered with this `Engine`.
`void`
`fireEngineAllocatingResources(EngineEvent event)`
Utility function that sends an `ENGINE_ALLOCATING_RESOURCES` event to all `EngineListeners` registered with this `Engine`.
`void`
`fireEngineDeallocated(EngineEvent event)`
Utility function that sends an `ENGINE_DEALLOCATED` event to all `EngineListeners` registered with this `Engine`.
`void`
`fireEngineDeallocatingResources(EngineEvent event)`
Utility function that sends a `ENGINE_DEALLOCATING_RESOURCES` event to all `EngineListeners` registered with this `Engine`.
`void`
`fireEnginePaused(EngineEvent event)`
Utility function that sends an `ENGINE_PAUSED` event to all `EngineListeners` registered with this `Engine`.
`void`
`fireEngineResumed(EngineEvent event)`
Utility function that sends an `ENGINE_RESUMED` event to all `EngineListeners` registered with this `Engine`.
`AudioManager`
`getAudioManager()`
Returns an object that provides management of the audio input or output of this `Engine`.
`EngineModeDesc`
`getEngineModeDesc()`
Gets the current operating properties and mode of this `Engine`.
`EngineProperties`
`getEngineProperties()`
Gets the `EngineProperties` of this `Engine`.
`long`
`getEngineState()`
Returns a or'ed set of flags indicating the current state of this `Engine`.
`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(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(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 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.
`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 Details

### engineState

protected long engineState
A bitmask holding the current state of this `Engine`.

### engineStateLock

protected Object engineStateLock
An `Object` used for synchronizing access to `engineState`.

See Also:
  - `engineState`

### engineListeners

protected Collection engineListeners
List of `EngineListeners` registered for `EngineEvents` on this `Engine`.

### audioManager

protected AudioManager audioManager
The `AudioManager` for this `Engine`.

### engineModeDesc

protected EngineModeDesc engineModeDesc
The `EngineModeDesc` for this `Engine`.

### engineProperties

protected 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 Details

### BaseEngine

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

### BaseEngine

public BaseEngine(EngineModeDesc desc)
Creates a new `Engine` in the `DEALLOCATED` state.

Parameters:
  `desc` - the operating mode of this `Engine`

## Method Details

### 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.

Returns:
  the current state of this `Engine`
See Also:
  - `getEngineState()`
  - `waitEngineState(long)`

### waitEngineState

public void waitEngineState(long state) throws InterruptedException, 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.

Parameters:
  `state` - a bitmask of the state to wait for
Throws:
  `InterruptedException` - if another thread has interrupted this thread.
  `IllegalArgumentException` - if the specified state is unreachable
See Also:
  - `testEngineState(long)`
  - `getEngineState()`

### testEngineState

public boolean testEngineState(long state) throws 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() invalid input: '&' state) == state)

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

Parameters:
  `state` - a bitmask of the states to test for
Returns:
  `true` if this `Engine` matches `state`; otherwise `false`
Throws:
  `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 EngineException, 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.

See Also:
  - `deallocate()`

### handleAllocate

protected abstract void handleAllocate() throws EngineException
Called from the `allocate` method. Override this in subclasses.

See Also:
  - `allocate()`

### deallocate

public void deallocate() throws EngineException, 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`.

See Also:
  - `allocate()`

### handleDeallocate

protected abstract void handleDeallocate() throws EngineException
Called from the `deallocate` method. Override this in subclasses.

### pause

public void pause() throws EngineStateError
Pauses the audio stream for this `Engine` and put this `Engine` into the `PAUSED` state.

### handlePause

protected abstract void handlePause()
Called from the `pause` method. Override this in subclasses.

### resume

public void resume() throws AudioException, EngineStateError
Resumes the audio stream for this `Engine` and put this `Engine` into the `RESUMED` state.

### handleResume

protected abstract void handleResume()
Called from the `resume` method. Override in subclasses.

### getAudioManager

public AudioManager getAudioManager()
Returns an object that provides management of the audio input or output of this `Engine`.

Returns:
  the audio manader for this `Engine`

### getVocabManager

public VocabManager getVocabManager() throws EngineStateError
Returns an object that provides management of the vocabulary for this `Engine`. Returns `null` if this `Engine` does not support vocabulary management.

Returns:
  the vocabulary manager of this `Engine`

### getEngineProperties

public EngineProperties getEngineProperties()
Gets the `EngineProperties` of this `Engine`. Must be set in subclasses.

Returns:
  the `EngineProperties` of this `Engine`.

### getEngineModeDesc

public EngineModeDesc getEngineModeDesc() throws SecurityException
Gets the current operating properties and mode of this `Engine`.

Returns:
  the operating mode of this `Engine`
Throws:
  `SecurityException`

### setEngineModeDesc

protected void setEngineModeDesc(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(EngineListener listener)
Requests notification of `EngineEvents` from this `Engine`.

Parameters:
  `listener` - the listener to add.

### removeEngineListener

public void removeEngineListener(EngineListener listener)
Removes an `EngineListener` from the list of `EngineListeners`.

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(EngineEvent)`
  - `dispatchSpeechEvent(SpeechEvent)`

### fireEngineAllocated

public void fireEngineAllocated(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(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(EngineEvent)`
  - `dispatchSpeechEvent(SpeechEvent)`

### fireEngineAllocatingResources

public void fireEngineAllocatingResources(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(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(EngineEvent)`
  - `dispatchSpeechEvent(SpeechEvent)`

### fireEngineDeallocated

public void fireEngineDeallocated(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(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(EngineEvent)`
  - `dispatchSpeechEvent(SpeechEvent)`

### fireEngineDeallocatingResources

public void fireEngineDeallocatingResources(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(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(EngineEvent)`
  - `dispatchSpeechEvent(SpeechEvent)`

### fireEnginePaused

public void fireEnginePaused(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(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(EngineEvent)`
  - `dispatchSpeechEvent(SpeechEvent)`

### fireEngineResumed

public void fireEngineResumed(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(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 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

### stateToString

protected 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(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 String toString()
Returns the engine name and mode for debug purposes.

Overrides:
  `toString` in class `Object`
Returns:
  the engine name and mode.