Annotations - kriyss/Bukkit-Plugin-Utils GitHub Wiki

Annotations

Bukkit-Plugin-Utils se sert des annotations lors de la compilation de votre plugin. Dans cette partie chaque annotation sera expliquée.

@Plugin

C'est l'annotation principale qui permet generer votre plugin. Elle se place sur une classe JavaPlugin de bukkit. Votre plugin ne doit contenir qu'une seule annotation @Plugin.

    @Plugin(version ="0.1")
    public class Economy extends JavaPlugin {
        ...
    }

Par default le nom de votre plugin sera le nom de la classe annotée de @Plugin, Dans l'exemple ci-dessus le nom du plugin sera "economy". Le champs version sert lors de la génération du fichier plugin.yml. Il est possible de specifier le nom du plugin en remplissant le champ name de la maniere suivante :

    @Plugin(name="othername", version ="0.1")
    public class Economy extends JavaPlugin {
        ...
    }

Dans ce cas le nom du plugin sera othername.

@CommandGroup

Cette annotation permet de definir un groupe de commande. Cela permet par exemple que certaine commande et une racine commune. Le plus gros avantage est de pouvoir definir des droits pour un groupe de commande directement avec cette annotation. Il est possible de definir la racine commune des commandes grace au champs value, par default il est à vide. Exemple basique :

    @CommandGroup
    public class MyCommandsGroup {
        ...
    }

Dans l'exemple ci-dessous les differentes commandes dans ce groupe de commande commencerons toutes par admin_.

    @CommandGroup("admin_")
    public class MyCommandsGroup {
        ...
    }

L'annotation @CommandGroup regroupe plusieurs commandes annotées @Command.

@Command

Cette annotation permet de generer des commandes. La façon la plus simple de l'utilisé est comme il suit :

    @Command(description = "add two number")
    public boolean add(CommandSender sender, @Param Integer number1, @Param Integer number2){
        Integer result = number1 + number2;
        sender.sendMessage("result : " + result);
        return true;
    }

Ce code permet de generer la partie de plugin.ymlsuivante :

commands:
   add:
        description: add two number
        usage: /add [number1] [number2] 

Par default le nom de la commande est le nom de la methode annotée. Mais il est possible de specifié son nom grace au champ name. Le code suivant

    @Command(name = "multiply", description = "multiply two number")
    public boolean product(CommandSender sender, @Param Integer number1, @Param Integer number2){
        Integer result = number1 * number2;
        sender.sendMessage("result : " + result);
        return true;
    }

genereras ce yml :

commands:
   multiply:
        description: multiply two number
        usage: /multiply [number1] [number2] 

Il est possible de gerer les Permissions unitairement sur les commandes mais j'y reviendrais plus tard. Les parametres d'une commande sont ceux que vous definisé. Le framework s'occuperas de vous les injectées. Le seul prerequis c'est de mettre le CommandSender en parametre de methode. Apres vous pouvez mettre autant de parametre que vous voulez.

    @Command(description = "concat some strings")
    public boolean concat(CommandSender sender, @Param String s1, @Param String s2, @Param String s3){
        sender.sendMessage("result : " + s1 + s2 + s3);
        return true;
    }

Ce code genereras le yml suivant :

commands:
   concat :
        description: concat some strings
        usage: /concat [s1] [s2] [s3] 

@Param

Elle sert a définir les différents paramètres que le Framework doit injecter pour une Commande annotée de @Command. Pour le moment Elle ne gère que Types String et Integer. Elle permet également de faire générer les différents contrôles de taille et d’existence. Elle dispose de plusieurs champs permettant de gérer la taille maximum / minimum et si la variable est requise avec les champs min, max et required. Il existe aussi un champs name si vous voulez changer un nom de parametre.

Exemple :

    @Command(description = "divide two number")
    public boolean divide(CommandSender sender, @Param Integer number1, @Param(min = 0) Integer number2){
        Integer result = number1 / number2;
        sender.sendMessage("result : " + result);
        return true;
    }

Dans cet exemple, la compilation vas générer la classe DivideExecutor : La classe DivideExecutor se divise en 3 parties :

• La création des différentes variables :

        Integer number1 = (0 < strings.length) && NumberUtils.isNumber(strings[0]) ? Integer.valueOf(strings[0]) : null;
        Integer number2 = (1 < strings.length) && NumberUtils.isNumber(strings[1]) ? Integer.valueOf(strings[1]) : null;

• Les différents contrôles de surface et affichages des erreurs :

    // surface control for number1
    if(number1 == null){
            errors.add("[number1] is required");
        } else {
            if(number1 < -2147483648)
                errors.add("[number1] has to be highter than -2147483648");
            if(number1 > 2147483647)
                errors.add("[number1] has to be smaller than 2147483647");
        }
    ...
    // display errors if exist and break method.
     if(!errors.isEmpty()) {
            for(String message : errors){
                commandSender.sendMessage(message);
            }
            return true;
        }

• Et pour finir l'appel a votre méthode :

         return super.divide(commandSender, number1, number2);

Il est possible de rendre un champ non obligatoire. Ce qui donne :

    @Command(description = "concat some strings")
    public boolean concat(CommandSender sender, 
            @Param String s1, 
            @Param(required =false) String s2, 
            @Param(required =false) String s3){
        ...
        return true;
    }

Ce code généreras donc les contrôle de surface en fonction de ce paramètre. Le fichier YML généré donneras :

    concat :
        description: concat some strings
        usage: /concat [s1] [s2(optionnal)] [s3(optionnal)]