TimeTrigger.java

package reghzy.api.utils;

import java.util.concurrent.TimeUnit;

/**
 * <h2>
 *     A class for helping with time-based execution of things, without requiring constant update
 * </h2>
 * <h3>
 *     An example usage, GriefPrevention's "warning: you haven't claimed this land" when placing blocks.
 * </h3>
 * <p>
 *     When they place a block, you called {@link TimeTrigger#canTrigger()}. If that returns true, you send them a message.
 *     No matter what that returns, you always call {@link TimeTrigger#canTrigger()} after that. Example:
 * <p>
 * <pre>
 * if ({@link TimeTrigger#canTrigger()}) {
 *     sendMessage("Try claiming your land!");
 * }
 *
 * {@link TimeTrigger#trigger()}
 * </pre>
 * </p>
 * <p>
 *     This ensures that if they keep placing blocks, they wont get spammed.
 *     But if they stop placing blocks for {@link TimeTrigger#getInterval()} number of milliseconds,
 *     it will message them again, and the loop continues
 * </p>
 *
 * <p>
 *     You can also use {@link TimeTrigger#getAndTrigger()} instead, like so:
 * <pre>
 * if ({@link TimeTrigger#getAndTrigger()}) {
 *     sendMessage("Try claiming your land!");
 * }
 * </pre>
 * </p>
 * </p>
 */
public class TimeTrigger {
    protected long interval;
    protected long lastTrigger;

    /**
     * Creates a time trigger with an interval of 0 (aka always trigger-able)
     */
    public TimeTrigger() {

    }

    /**
     * Creates a time trigger with the given interval
     * @param intervalMillis The minimum required time between the last execution, and the next for {@link TimeTrigger#canTrigger()} to return true.
     *                       Measured in MILLISECONDS
     */
    public TimeTrigger(long intervalMillis) {
        this.interval = intervalMillis;
    }

    /**
     * Creates an instance where the time is millisecond-based (1000 milliseconds in a second)
     */
    public static TimeTrigger fromMillis(long millis) {
        return new TimeTrigger(millis);
    }

    /**
     * Creates an instance where the time is second-based (the seconds get converted into millis)
     * @see TimeTrigger#TimeTrigger(long)
     * @see TimeUnit#convert(long, TimeUnit)
     */
    public static TimeTrigger fromSeconds(long seconds) {
        return new TimeTrigger(TimeUnit.MILLISECONDS.convert(seconds, TimeUnit.SECONDS));
    }

    /**
     * Creates an instance where the time is minute-based (the minutes get converted into millis)
     * @see TimeTrigger#TimeTrigger(long)
     * @see TimeUnit#convert(long, TimeUnit)
     */
    public static TimeTrigger fromMinutes(long minutes) {
        return new TimeTrigger(TimeUnit.MILLISECONDS.convert(minutes, TimeUnit.MINUTES));
    }

    /**
     * Checks if the difference between the system time and the last trigger time is bigger than this time trigger's interval
     * @return True if it is, false if not
     */
    public boolean canTrigger() {
        return (System.currentTimeMillis() - this.lastTrigger) >= getInterval();
    }

    /**
     * Updates the last trigger time of this time trigger, most likely causing {@link TimeTrigger#canTrigger()} to no longer return true
     */
    public void trigger() {
        this.lastTrigger = System.currentTimeMillis();
    }

    /**
     * Gets whether this can be triggered and returns it. And also triggers in the process (after getting whether this can be triggered)
     * <p>
     *     This essentially removes the need to use an if block on the {@link TimeTrigger#canTrigger()}
     *     and then executing {@link TimeTrigger#trigger()} after the if block has exited; you can simply it in this single method
     * </p>
     */
    public boolean getAndTrigger() {
        boolean canTrigger = canTrigger();
        trigger();
        return canTrigger;
    }

    /**
     * Returns the interval that this time trigger is set to
     */
    public long getInterval() {
        return this.interval;
    }

    /**
     * Sets the interval time for this time trigger
     */
    public void setInterval(long intervalMillis) {
        this.interval = intervalMillis;
    }
}