org.jitsi.service.audionotifier

Class AbstractSCAudioClip

java.lang.Object

org.jitsi.service.audionotifier.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 and 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.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	AbstractSCAudioClip(String uri, AudioNotifierService audioNotifier)

Method Summary

Modifier and Type	Method and 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.

Methods inherited from class java.lang.Object

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

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.

Constructor Detail

AbstractSCAudioClip

protected AbstractSCAudioClip(String uri,
                              AudioNotifierService audioNotifier)

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