Class BaseEngine

  • All Implemented Interfaces:
    SpeechEventDispatcher
    Direct Known Subclasses:
    BaseSynthesizer

    public abstract class BaseEngine
    extends java.lang.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 long CLEAR_ALL_STATE
      Utility state for clearing the engineState.
      protected java.util.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 java.lang.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

      All Methods Instance Methods Abstract Methods Concrete Methods 
      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 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.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 Detail

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

        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.

        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.

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

        Throws:
        EngineException - if this Engine cannot be allocated
        EngineStateError - if this Engine is in the DEALLOCATING_RESOURCES state
        See Also:
        deallocate()
      • handleAllocate

        protected abstract void handleAllocate()
                                        throws EngineException
        Called from the allocate method. Override this in subclasses.
        Throws:
        EngineException - if problems are encountered
        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.

        Throws:
        EngineException - if this Engine cannot be deallocated
        EngineStateError - if this Engine is in the ALLOCATING_RESOURCES state
        See Also:
        allocate()
      • handleDeallocate

        protected abstract void handleDeallocate()
                                          throws EngineException
        Called from the deallocate method. Override this in subclasses.
        Throws:
        EngineException - if this Engine cannot be deallocated.
      • pause

        public void pause()
                   throws EngineStateError
        Pauses the audio stream for this Engine and put this Engine into the PAUSED state.
        Throws:
        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 AudioException,
                           EngineStateError
        Resumes the audio stream for this Engine and put this Engine into the RESUMED state.
        Throws:
        AudioException - if unable to gain access to the audio channel
        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 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
        Throws:
        EngineStateError - if this Engine in the DEALLOCATING_RESOURCES or DEALLOCATED state
      • 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 java.lang.SecurityException
        Gets the current operating properties and mode of this Engine.
        Returns:
        the operating mode of this Engine
        Throws:
        java.lang.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
        Throws:
        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
      • toString

        public java.lang.String toString()
        Returns the engine name and mode for debug purposes.
        Overrides:
        toString in class java.lang.Object
        Returns:
        the engine name and mode.