Module page.codeberg.friedolyn.Friedolyn

Package page.codeberg.friedolyn.util

Class Countdown

java.lang.Object

page.codeberg.friedolyn.util.Countdown

All Implemented Interfaces:

Copyable<Countdown>

public class Countdown
extends Object
implements Copyable<Countdown>

Timer that logs the time remaining until it reaches zero. The current time is updated once per second.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static interface	Countdown.CountdownListener	An object that is interested in the countdown's progress and that will be notified about any changes to it.
class	Countdown.CountdownTask	Decreases the countdown by one second, if the current value is greater than 1 second.
static enum	Countdown.Status	Indicates what a countdown is currently doing or what it has done.

Field Summary

Fields

Modifier and Type	Field	Description
private @NonNull Duration	countdown	The time remaining until the countdown reaches zero.
private @NonNull Countdown.CountdownTask	countdownTask	Decreases the countdown by one second, if the current value is greater than 1 second.
private final @NonNull Duration	initialTime	The time interval that the countdown started with.
private LocalDateTime	lastUpdate	Used by resume() to prevent the countdown from being fast-forwarded accidentally.
private @NonNull Set<@NonNull Countdown.CountdownListener>	listeners	All objects that are interested in the countdown's progress.
private final @NonNull ReentrantLock	LOCK	Facilitates mutual exclusion when updating the countdown.
private LocalDateTime	pausedAt	Used by resume() to prevent the countdown from being fast-forwarded accidentally.
private @NonNull Countdown.Status	status	Indicates what the countdown is currently doing or what it has done.

Constructor Summary

Constructors

Constructor	Description
Countdown(@NonNull Duration duration)	Creates a new countdown with the specified initial time.

Method Summary

Modifier and Type	Method	Description
void	cancel()	Aborts the countdown and sets it to zero.
@NonNull Countdown	copy()
void	finish()	Prematurely sets the countdown to zero and notifies all listeners about it.
@NonNull Duration	get()
void	pause()	Temporarily halts the countdown at the current value until resume() is called.
void	registerListener(@NonNull Countdown.CountdownListener listener)	Adds a Countdown.CountdownListener to the list of objects that are interested in the countdown's progress.
boolean	removeListener(@NonNull Countdown.CountdownListener listener)	Deletes an already registered Countdown.CountdownListener from the list of objects that are interested in the countdown's progress.
void	reset()	Sets the countdown back to the initial time.
void	restart()	Sets the countdown back to the initial time and immediately launches the countdown again.
void	resume()	Continues the countdown from where it was paused.
void	start()	Launches the timer that decreases the countdown by one second every second.
private void	start(Duration delay)	Launches the timer that decreases the countdown by one second every second, after waiting for the specified delay.

Methods inherited from class java.lang.Object

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

Field Details

countdown

@NonNull
private @NonNull Duration countdown

The time remaining until the countdown reaches zero.

initialTime

@NonNull
private final @NonNull Duration initialTime

The time interval that the countdown started with.

lastUpdate

@Nullable
private LocalDateTime lastUpdate

Used by resume() to prevent the countdown from being fast-forwarded accidentally. TL;DR: When pausing the countdown, that never happens precisely at a whole second, resulting in a small delay that we must wait for when resuming the countdown.

pausedAt

@Nullable
private LocalDateTime pausedAt

Used by resume() to prevent the countdown from being fast-forwarded accidentally. TL;DR: When pausing the countdown, that never happens precisely at a whole second, resulting in a small delay that we must wait for when resuming the countdown.

LOCK

@NonNull
private final @NonNull ReentrantLock LOCK

Facilitates mutual exclusion when updating the countdown.

status

@NonNull
private @NonNull Countdown.Status status

Indicates what the countdown is currently doing or what it has done.

listeners

@NonNull
private @NonNull Set<@NonNull Countdown.CountdownListener> listeners

All objects that are interested in the countdown's progress. Whenever the countdown is updated, all listeners are notified via Countdown.CountdownListener.onUpdate(Duration). Once the countdown reaches zero, all listeners are notified via Countdown.CountdownListener.onFinished().

countdownTask

@NonNull
private @NonNull Countdown.CountdownTask countdownTask

Decreases the countdown by one second, if the current value is greater than 1 second.

Constructor Details

Countdown

public Countdown(@NonNull
 @NonNull Duration duration)
          throws IllegalArgumentException

Creates a new countdown with the specified initial time.

Parameters:

duration - The time that should be counted down until it reaches zero. Must not be negative.

Throws:

IllegalArgumentException - If the given duration is negative.

Method Details

registerListener

public void registerListener(@NonNull
 @NonNull Countdown.CountdownListener listener)

Adds a Countdown.CountdownListener to the list of objects that are interested in the countdown's progress. Whenever the countdown is updated, all listeners are notified via Countdown.CountdownListener.onUpdate(Duration). Once the countdown reaches zero, all listeners are notified via Countdown.CountdownListener.onFinished().

Parameters:

listener - The new listener that will be notified about the countdown's progress.

removeListener

public boolean removeListener(@NonNull
 @NonNull Countdown.CountdownListener listener)

Deletes an already registered Countdown.CountdownListener from the list of objects that are interested in the countdown's progress. Use the exact same reference that was passed to registerListener(CountdownListener) previously.

Parameters:

listener - The currently registered listener that will be removed from the list of listeners.

Returns:

true if the listener was removed, false if the listener could not be found.

get

@NonNull
public @NonNull Duration get()

Returns:

A deep copy of the current countdown (not the actual reference of it, for security reasons).

start

public void start()
           throws IllegalStateException

Launches the timer that decreases the countdown by one second every second. Notifies all listeners about the start.

Throws:

IllegalStateException - If the countdown has already been started.

Implementation Note:

Relies on start(Duration) to notify the listeners and actually start the countdown; i.e. this method does neither of these things itself. This means that the listeners will not be notified twice, and the countdown will not be started twice.

start

private void start(Duration delay)
            throws IllegalArgumentException,
IllegalStateException

Launches the timer that decreases the countdown by one second every second, after waiting for the specified delay. Notifies all listeners about the start.

Parameters:

delay - The time to wait before starting the countdown. Must not be negative.

Throws:

IllegalArgumentException - If the delay is negative.

IllegalStateException - If the countdown has already been started.

pause

public void pause()

Temporarily halts the countdown at the current value until resume() is called. Notifies all listeners.

resume

public void resume()
            throws IllegalStateException

Continues the countdown from where it was paused. Notifies all listeners.

Throws:

IllegalStateException - If the countdown has already been resumed or if it had not been paused before.

Implementation Note:

When the countdown is paused, this happens a fraction of a second before the next update of the countdown would have been made (i.e. we always pause the countdown a little bit too early). That means, when resuming the countdown, we must wait for that fraction of a second before continuing the countdown. (Otherwise, the user could fast-forward the countdown by rapidly pausing and resuming it in quick succession.)

restart

public void restart()

Sets the countdown back to the initial time and immediately launches the countdown again. Notifies all listeners about the reset.

See Also:

• reset()

reset

public void reset()

Sets the countdown back to the initial time. Will not automatically start the countdown again.

See Also:

• restart()

cancel

public void cancel()

Aborts the countdown and sets it to zero. Notifies all listeners.

finish

public void finish()

Prematurely sets the countdown to zero and notifies all listeners about it. Sets the status to finished.

copy

@NonNull
public @NonNull Countdown copy()

Specified by:

copy in interface Copyable<Countdown>

Returns:

A deep copy of the object, i.e. a clone that has the exact same values as the original object, but is a different instance (new reference).