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.

If you wish to apply a decorator to all actions within a class, you can do this by annotating the class with the decorator. By default, if you also place the same decorator on the action itself, it would be used instead of the one on the class. You can find more information regarding the specific DecoratorMerge strategies here.

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

1. @Cooldown
2. @Permissions
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.cooldowns.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!";
}

@Permissions

The @Permissions 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.

Unlike the other built-in decorators, the @Permission decorator employes the KEEP_BOTH merge strategy. Because of this, if you annotate both an action and the class containing the action with @Permissions, both of the permission decorators will be applied to the action. As such, you can define a base permission users must-have for actions in a class while also being able to add additional permissions for specific actions if necessary.

The @Permissions annotation supports a few different things:

1. JDA's built-in Permission enum.
2. Custom string-based permissions (Either defined through permission suppliers or role binding).
3. Making the permissions be OR'd or AND'd together by using a Merge strategy.

For more information on how permissions work, including how to create your own custom permissions, refer to the documentation here.

Example usages:

Show Imports

import net.dv8tion.jda.api.Permission;

import org.dockbox.hartshorn.core.annotations.stereotype.Service;

import nz.pumbas.halpbot.commands.annotations.Command;
import nz.pumbas.halpbot.permissions.HalpbotPermissions;
import nz.pumbas.halpbot.permissions.Merger;
import nz.pumbas.halpbot.permissions.Permissions;

// HalpbotPermissions.GUILD_OWNER is a built-in permission supplier
@Permissions(permissions = HalpbotPermissions.GUILD_OWNER)
@Command(description = "Tests the @Permissions decorator")
public String permission() {
    return "This command is restricted to people who own the guild this command was invoked in";
}

@Permissions(value = {Permission.MANAGE_PERMISSIONS, Permission.MANAGE_ROLES}, merger = Merger.OR)
@Command(description = "Tests the OR merger in the @Permission decorator")
public String orPermissions() {
    return "This command is restricted to people with the *MANAGE_PERMISSIONS* or *MANAGE_ROLES* permissions";
}

@Service
@Permissions(Permission.MANAGE_PERMISSIONS)
public class ExamplePermissionCommands
{
    @Command(description = "Testing class level permissions")
    public String classPermission() {
        return "You need the *MANAGE_PERMISSIONS* permission to use this command";
    }

    @Permissions(Permission.BAN_MEMBERS)
    @Command(description = "Testing class level permissions")
    public String actionPermission() {
        return "You need the *MANAGE_PERMISSIONS* and *BAN_MEMBERS* permissions to use this command";
    }
}

@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()