Decorators

Decorators allow for you to call another method, before invoking the action using the decorator pattern. In doing so, you can restrict, or modify how the action is called. It's also possible to add multiple decorators to one action, allowing you to extensively enhance the functionality of an action with very little work.

Annotating the class itself with decorators causes them to be applied to all actions within the class. It's important to note that using the same decorator on an action within the class will not override the decorator on the class, instead, both decorators will be applied to the action. Still W.I.P

Halpbot currently has 3 built-in decorators that can be used on any public method annotated with: @ButtonAction, @Command or @CustomParameter:

1. @Cooldown
2. @Permission
3. @Log

@Cooldown

This decorator allows you to specify a period of time that a user must wait before being able to invoke an action again. If the user is still cooling down it will temporarily display a MessageEmbed telling you how many seconds you have to wait before you can use the action again.

Example usages:

Show Imports

import java.time.temporal.ChronoUnit;

import nz.pumbas.halpbot.actions.annotations.Cooldown;
import nz.pumbas.halpbot.commands.annotations.Command;
import nz.pumbas.halpbot.utilities.Duration;

@Cooldown(duration = @Duration(30))
@Command(description = "Tests the @Cooldown decorator")
public String cooldown() {
    return "This command has a 30 second cooldown!";
}

@Cooldown(duration = @Duration(value = 1, unit = ChronoUnit.MINUTES))
@Command(description = "Tests the @Cooldown decorator")
public String cooldown() {
    return "This command has a 1 minute cooldown!";
}

@Permission

The @Permission decorator allows you to specify which permissions a user must have if they want to invoke an action. If the user does not have all the specified permissions, then the action won't be invoked and a MessageEmbed will be temporarily displayed informing you that you lack the permissions to use the action.

Permissions allow for role-based restrictions on who can invoke actions. For more information on how they work, including how to create your own permissions refer to the documentation here.

Example usages:

Show Imports

import nz.pumbas.halpbot.commands.annotations.Command;
import nz.pumbas.halpbot.permissions.HalpbotPermissions;
import nz.pumbas.halpbot.permissions.Permission;

@Permission(HalpbotPermissions.GUILD_OWNER)
@Command(description = "Tests the @Permission decorator")
public String permission() {
    return "This command is restricted to people with the *halpbot.owner.guild* permission";
}

@Permission({"halpbot.example.a", "halpbot.example.b"})
@Command(description = "Tests the @Permission decorator")
public String permission() {
    return "This command is restricted to people with the *halpbot.example.a* and *halpbot.example.b* permissions";
}

@Log

The @Log decorator specifies that an action should be logged whenever it is invoked, allowing for you to easily keep a record of who is using the actions. You also have the option to change the logging level used when logging. By default, this is DEBUG.

Example usages:

Show Imports

import nz.pumbas.halpbot.commands.annotations.Command;
import nz.pumbas.halpbot.decorators.log.Log;
import nz.pumbas.halpbot.utilities.LogLevel;

@Log
@Command(description = "Tests the @Log decorator")
public String log() {
    return "This command is logged when it is invoked";
}

@Log(LogLevel.INFO)
@Command(description = "Tests the @Log decorator")
public String log() {
    return "This command is logged when it is invoked";
}

When invoked, this causes the following to be logged:

20:28:11.308 [ inWS-ReadThread] @ 17272 -> n.p.h.decorators.log.LogDecorator      INFO  - [Bot Testing][general] pumbas600#7051 has invoked the action HalpbotCommands#log()