revxrsal.commands.command

Interface CooldownHandle

@ApiStatus.Experimental
public interface CooldownHandle

Represents a handle that allows for fine-grained control for the cooldown of a command.

A cooldown handle can be used in two main ways:

1. Combined with @Cooldown annotation:

   {@code

See Also:

Cooldown

Method Summary

Modifier and Type	Method and Description
void	cooldown() Starts the cooldown with the duration specified in @Cooldown.
void	cooldown(@Range(from=1L,to=9223372036854775807L) long duration, @NotNull java.util.concurrent.TimeUnit unit) Starts the cooldown for a specific duration.
default long	elapsed(@NotNull java.util.concurrent.TimeUnit outputUnit) Returns the elapsed cooldown time in the specified time unit.
long	elapsedMillis() Returns the elapsed time since the cooldown started in milliseconds.
boolean	isOnCooldown() Checks if the cooldown is currently active.
default long	remainingTime(long cooldownValue, @NotNull java.util.concurrent.TimeUnit cooldownUnit) Calculates the remaining cooldown time in the same unit as the cooldown.
default long	remainingTime(long cooldownValue, @NotNull java.util.concurrent.TimeUnit cooldownUnit, @NotNull java.util.concurrent.TimeUnit outputUnit) Calculates the remaining cooldown time in a specified output unit.
long	remainingTime(@NotNull java.util.concurrent.TimeUnit outputUnit) Gets the remaining cooldown time in the specified unit.
long	remainingTimeMillis() Gets the remaining cooldown time in milliseconds.
default long	remainingTimeMillis(long cooldownValue, @NotNull java.util.concurrent.TimeUnit cooldownUnit) Calculates the remaining time for a specific cooldown in milliseconds.
void	removeCooldown() Removes the active cooldown immediately.
void	requireNotOnCooldown() Throws an exception if currently on cooldown.
void	requireNotOnCooldown(long cooldownValue, @NotNull java.util.concurrent.TimeUnit cooldownUnit) Throws an exception if on cooldown based on the specified duration.
@NotNull CooldownHandle	withCooldown(long cooldownValue, @NotNull java.util.concurrent.TimeUnit unit) Creates a new CooldownHandle that is identical to this handle, except that it has a specified cooldown value and unit.

Method Detail

withCooldown

@CheckReturnValue
 @Contract(pure=true,
          value="_, _ -> new")
 @NotNull
@NotNull CooldownHandle withCooldown(long cooldownValue,
                                                                                                                      @NotNull
                                                                                                                      @NotNull java.util.concurrent.TimeUnit unit)

Creates a new CooldownHandle that is identical to this handle, except that it has a specified cooldown value and unit.

This handle allows calling shortcut methods such as cooldown(), remainingTimeMillis(), etc.

Parameters:

cooldownValue - Cooldown value

unit - The time unit of the cooldown

Returns:

A newly created CooldownHandle

isOnCooldown

boolean isOnCooldown()

Checks if the cooldown is currently active.

Returns:

true if on cooldown, false otherwise.

elapsedMillis

long elapsedMillis()

Returns the elapsed time since the cooldown started in milliseconds.

If the user is not on cooldown, this will return zero.

Returns:

Elapsed time in milliseconds.

cooldown

void cooldown()

Starts the cooldown with the duration specified in @Cooldown.

Throws:

java.lang.IllegalArgumentException - if the CooldownHandle parameter does not have @Cooldown on it

requireNotOnCooldown

void requireNotOnCooldown()
                   throws CooldownException

Throws an exception if currently on cooldown.

Throws:

CooldownException - if on cooldown.

java.lang.IllegalArgumentException - if the CooldownHandle parameter does not have @Cooldown on it

requireNotOnCooldown

void requireNotOnCooldown(long cooldownValue,
                          @NotNull
                          @NotNull java.util.concurrent.TimeUnit cooldownUnit)
                   throws CooldownException

Throws an exception if on cooldown based on the specified duration.

Parameters:

cooldownValue - Cooldown duration.

cooldownUnit - Time unit for the cooldown duration.

Throws:

CooldownException - if on cooldown.

removeCooldown

void removeCooldown()

Removes the active cooldown immediately.

elapsed

default long elapsed(@NotNull
                     @NotNull java.util.concurrent.TimeUnit outputUnit)

Returns the elapsed cooldown time in the specified time unit.

Parameters:

outputUnit - Time unit for the result.

Returns:

Elapsed time in the specified unit.

cooldown

void cooldown(@Range(from=1L,to=9223372036854775807L) long duration,
              @NotNull
              @NotNull java.util.concurrent.TimeUnit unit)

Starts the cooldown for a specific duration.

Parameters:

duration - Cooldown duration.

unit - Time unit for the duration.

remainingTimeMillis

long remainingTimeMillis()

Gets the remaining cooldown time in milliseconds.

Returns:

Remaining time in milliseconds.

Throws:

java.lang.IllegalArgumentException - if the CooldownHandle parameter does not have @Cooldown on it

remainingTime

long remainingTime(@NotNull
                   @NotNull java.util.concurrent.TimeUnit outputUnit)

Gets the remaining cooldown time in the specified unit.

Parameters:

outputUnit - Time unit for the result.

Returns:

Remaining time in the specified unit.

Throws:

java.lang.IllegalArgumentException - if the CooldownHandle parameter does not have @Cooldown on it

remainingTimeMillis

default long remainingTimeMillis(long cooldownValue,
                                 @NotNull
                                 @NotNull java.util.concurrent.TimeUnit cooldownUnit)

Calculates the remaining time for a specific cooldown in milliseconds.

Parameters:

cooldownValue - Cooldown duration.

cooldownUnit - Time unit for the duration.

Returns:

Remaining time in milliseconds.

remainingTime

default long remainingTime(long cooldownValue,
                           @NotNull
                           @NotNull java.util.concurrent.TimeUnit cooldownUnit)

Calculates the remaining cooldown time in the same unit as the cooldown.

Parameters:

cooldownValue - Cooldown duration.

cooldownUnit - Time unit for the cooldown.

Returns:

Remaining time in the cooldown unit.

remainingTime

default long remainingTime(long cooldownValue,
                           @NotNull
                           @NotNull java.util.concurrent.TimeUnit cooldownUnit,
                           @NotNull
                           @NotNull java.util.concurrent.TimeUnit outputUnit)

Calculates the remaining cooldown time in a specified output unit.

Parameters:

cooldownValue - Cooldown duration.

cooldownUnit - Time unit for the cooldown.

outputUnit - Desired time unit for the result.

Returns:

Remaining time in the output unit.