Package org.jitsi.service.audionotifier

Class AbstractSCAudioClip

  • All Implemented Interfaces:
    SCAudioClip
    Direct Known Subclasses:
    AudioSystemClipImpl, JavaSoundClipImpl
    public abstract class AbstractSCAudioClip
extends Object
implements SCAudioClip
    An abstract base implementation of SCAudioClip which is provided in order to aid implementers by allowing them to extend AbstractSCAudioClip and focus on the task of playing actual audio once.
    Author:
    Damian Minkov, Lyubomir Marinov

    • Field Summary

      Fields 
      Modifier and Type Field Description
      protected AudioNotifierService audioNotifier
      The AudioNotifierService which has initialized this instance.
      protected Object sync
      The Object used for internal synchronization purposes which arise because this instance does the actual playback of audio in a separate thread.
      protected String uri
      The String uri of the audio to be played by this instance.

    • Method Summary

      All Methods Instance Methods Abstract Methods Concrete Methods 
      Modifier and Type Method Description
      protected void enterRunInPlayThread()
      Notifies this instance that its execution in its background/separate thread dedicated to the playback of this audio is about to start playing this audio for the first time.
      protected void enterRunOnceInPlayThread()
      Notifies this instance that its execution in its background/separate thread dedicated to the playback of this audio is about the start playing this audio once.
      protected void exitRunInPlayThread()
      Notifies this instance that its execution in its background/separate thread dedicated to the playback of this audio is about to stop playing this audio once.
      protected void exitRunOnceInPlayThread()
      Notifies this instance that its execution in its background/separate thread dedicated to the playback of this audio is about to stop playing this audio.
      int getLoopInterval()
      Gets the interval of time in milliseconds between consecutive plays of this audio.
      protected void internalStop()
      Stops this audio without setting the isLooping property in the case of a looping audio.
      boolean isInvalid()
      Determines whether this instance is invalid.
      boolean isLooping()
      Determines whether this instance plays the audio it represents in a loop.
      boolean isStarted()
      Determines whether this audio is started i.e.
      void play()
      Starts playing this audio once only.
      void play​(int loopInterval, Callable<Boolean> loopCondition)
      Starts playing this audio.
      protected abstract boolean runOnceInPlayThread()
      Plays this audio once.
      void setInvalid​(boolean invalid)
      Sets the indicator which determines whether this instance is invalid.
      void setLooping​(boolean looping)
      Sets the indicator which determines whether this audio is to play in a loop.
      void setLoopInterval​(int loopInterval)
      Sets the interval of time in milliseconds between consecutive plays of this audio in a loop.
      void stop()
      Stops playing this audio.

    • Field Detail

      • audioNotifier

        protected final AudioNotifierService audioNotifier
        The AudioNotifierService which has initialized this instance. AbstractSCAudioClip monitors its mute property/state in order to silence the played audio as appropriate/necessary.

      • sync

        protected final Object sync
        The Object used for internal synchronization purposes which arise because this instance does the actual playback of audio in a separate thread.

        The synchronization root is exposed to extenders in case they would like to, for example, get notified as soon as possible when this instance gets stopped.

      • uri

        protected final String uri
        The String uri of the audio to be played by this instance. AbstractSCAudioClip does not use it and just remembers it in order to make it available to extenders.

    • Method Detail

      • enterRunInPlayThread

        protected void enterRunInPlayThread()
        Notifies this instance that its execution in its background/separate thread dedicated to the playback of this audio is about to start playing this audio for the first time. Regardless of whether this instance is to be played once or multiple times in a loop, the method is called once in order to allow extenders/implementers to perform one-time initialization before this audio starts playing. The AbstractSCAudioClip implementation does nothing.

      • enterRunOnceInPlayThread

        protected void enterRunOnceInPlayThread()
        Notifies this instance that its execution in its background/separate thread dedicated to the playback of this audio is about the start playing this audio once. If this audio is to be played in a loop, the method is invoked at the beginning of each iteration of the loop. Allows extenders/implementers to perform per-loop iteration initialization. The AbstractSCAudioClip implementation does nothing.

      • exitRunInPlayThread

        protected void exitRunInPlayThread()
        Notifies this instance that its execution in its background/separate thread dedicated to the playback of this audio is about to stop playing this audio once. Regardless of whether this instance is to be played once or multiple times in a loop, the method is called once in order to allow extenders/implementers to perform one-time cleanup after this audio stops playing. The AbstractSCAudioClip implementation does nothing.

      • exitRunOnceInPlayThread

        protected void exitRunOnceInPlayThread()
        Notifies this instance that its execution in its background/separate thread dedicated to the playback of this audio is about to stop playing this audio. If this audio is to be played in a loop, the method is called at the end of each iteration of the loop. Allows extenders/implementers to perform per-loop iteraction cleanup. The AbstractSCAudioClip implementation does nothing.

      • getLoopInterval

        public int getLoopInterval()
        Gets the interval of time in milliseconds between consecutive plays of this audio.
        Returns:
        the interval of time in milliseconds between consecutive plays of this audio. If negative, this audio will not be played in a loop and will be played once only.

      • internalStop

        protected void internalStop()
        Stops this audio without setting the isLooping property in the case of a looping audio. The AudioNotifier uses this method to stop the audio when setMute(true) is invoked. This allows us to restore all looping audios when the sound is restored by calling setMute(false).

      • isInvalid

        public boolean isInvalid()
        Determines whether this instance is invalid. AbstractSCAudioClip does not use the invalid property/state of this instance and merely remembers the value which was set on it by setInvalid(boolean). The default value is false i.e. this instance is valid by default.
        Returns:
        true if this instance is invalid; otherwise, false

      • isLooping

        public boolean isLooping()
        Determines whether this instance plays the audio it represents in a loop.
        Returns:
        true if this instance plays the audio it represents in a loop; false, otherwise

      • isStarted

        public boolean isStarted()
        Determines whether this audio is started i.e. a play method was invoked and no subsequent stop has been invoked yet.
        Specified by:
        isStarted in interface SCAudioClip
        Returns:
        true if this audio is started; otherwise, false

      • play

        public void play()
        Starts playing this audio once only. The method behaves as if SCAudioClip.play(int, Callable) was invoked with a negative loopInterval and/or null loopCondition. Delegates to play(int, Callable) with loopInterval -1 and loopCondition null in order to conform with the contract for the behavior of this method specified by the interface SCAudioClip.
        Specified by:
        play in interface SCAudioClip

      • play

        public void play​(int loopInterval,
                 Callable<Boolean> loopCondition)
        Starts playing this audio. Optionally, the playback is looped.
        Specified by:
        play in interface SCAudioClip
        Parameters:
        loopInterval - the interval of time in milliseconds between consecutive plays of this audio. If negative, this audio is played once only and loopCondition is ignored.
        loopCondition - a Callable which is called at the beginning of each iteration of looped playback of this audio except the first one to determine whether to continue the loop. If loopInterval is negative or loopCondition is null, this audio is played once only.

      • runOnceInPlayThread

        protected abstract boolean runOnceInPlayThread()
        Plays this audio once.
        Returns:
        true if subsequent plays of this audio and, respectively, the method are to be invoked if this audio is to be played in a loop; otherwise, false. The value reflects an implementation-specific loop condition, is not dependent on loopInterval and loopCondition and is combined with the latter in order to determine whether there will be a subsequent iteration of the playback loop.

      • setInvalid

        public void setInvalid​(boolean invalid)
        Sets the indicator which determines whether this instance is invalid. AbstractSCAudioClip does not use the invalid property/state of this instance and merely remembers the value which was set on it so that it can be retrieved by isInvalid(). The default value is false i.e. this instance is valid by default.
        Parameters:
        invalid - true to mark this instance invalid or false to mark it valid

      • setLooping

        public void setLooping​(boolean looping)
        Sets the indicator which determines whether this audio is to play in a loop. Generally, public invocation of the method is not necessary because the looping is controlled by the loopInterval property of this instance and the loopInterval and loopCondition parameters of play(int, Callable) anyway.
        Parameters:
        looping - true to mark this instance that it should play the audio it represents in a loop; otherwise, false

      • setLoopInterval

        public void setLoopInterval​(int loopInterval)
        Sets the interval of time in milliseconds between consecutive plays of this audio in a loop. If negative, this audio is played once only. If non-negative, this audio may still be played once only if the loopCondition specified to play(int, Callable) is null or its invocation fails.
        Parameters:
        loopInterval - the interval of time in milliseconds between consecutive plays of this audio in a loop to be set on this instance

      • stop

        public void stop()
        Stops playing this audio.
        Specified by:
        stop in interface SCAudioClip