Scheduler API Reference/fr

L'api bukkit dispose d'un système de planification de tâche. Il permet aux plugins d'exécuter du code, de façon synchrone ou asynchrone (dans un Thread différent de celui du serveur), après un certain temps et/ou à intervalles réguliers. Ces tâches ne s'arrêteront que lorsqu'elles auront fini de s'exécuter, ou si elles sont annulées, ou si le plugin qui les a planifié est désactivé.
Il y a deux façons de planifier des tâches:

1. En utilisant une classe qui hérite de BukkitRunnable
2. En implémentant Runnable et en utilisant le BukkitScheduler

BukkitRunnable

BukkitRunnable est une implémentation abstraite de Runnable. Elle ajoute la possibilité de planifier son exécution et de l'annuler. C'est un moyen simple et recommandé de planifier des tâches.

Création de la tâche

Créez une classe qui hérite de BukkitRunnable. La méthode run() que vous devez définir contient le code à exécuter:

public class ExempleTask extends BukkitRunnable {
   @Override
   public void run() {
      //Code a exécuter
   }
}

Planification

Planifiez ensuite cette tâche, avec ses méthodes héritées de BukkitRunnable:

• runTask(Plugin plugin): exécute la tâche immédiatement
• runTaskAsynchronously(Plugin plugin): exécute la tâche dans un autre Thread.
• runTaskLater(Plugin plugin, long delay): exécute la tâche après un certains nombres de ticks
• runTaskLaterAsynchronously(Plugin plugin, long delay): exécute la tâche dans un autre Thread, après un certains nombres de ticks
• runTaskTimer(Plugin plugin, long delay, long period): exécute la tâche tous les period ticks, après delay ticks.
• runTaskTimerAsynchronously(Plugin plugin, long delay, long period): exécute la tâche dans un autre Thread, tous les period ticks, après delay ticks.

Warning:

Les tâches asynchrones (exécutées dans un autre Thread) ne doivent utiliser AUCUNE api bukkit durant leur exécution

Note: Sur un serveur sans lag, 20 ticks durent 1 seconde

Exemple au démarrage de votre plugin:

@Override
public void onEnable() {
   BukkitRunnable task = new ExempleTask();
   task.runTaskLater(this, 60);//On lance la tâche dans 60 ticks, soit 3 secondes
}

Annulation

Vous pouvez annuler la planification d'une tâche avec sa méthode cancel().
Vous pouvez même faire une tâche qui s'arrête d'elle même, en appelant cancel() durant son exécution. Par exemple pour faire un compte à rebours:
La tâche:

public class CounterTask extends BukkitRunnable {
   private int count = 5;
   
   @Override
   public void run() {
      if(count > 0) {
         Bukkit.getServer().broadcastMessage("Il reste " + count + " seconde(s)"); 
         count--;
      } else {
         Bukkit.getServer().broadcastMessage("Terminé !"); 
         this.cancel();
      }
   }
}

Planification de la tâche:

BukkitRunnable counter = new CounterTask();
counter.runTaskTimer(plugin, 0, 20);//On exécute la tâche tous les 20 ticks, soit toutes les secondes

BukkitScheduler

La classe BukkitScheduler permet de planifier l'exécution de Runnable ou de Callable. On l'obtient ainsi:

BukkitScheduler scheduler = Bukkit.getServer().getScheduler();

Création de la tâche

Créez une classe qui implémente Runnable. La méthode run() que vous devez définir contient le code à exécuter:

public class ExempleTask implements Runnable {
   @Override
   public void run() {
      //Code a exécuter
   }
}

Planification

Planifiez ensuite cette tâche, avec les méthodes du BukkitScheduler:

• runTask(Plugin plugin): exécute la tâche immédiatement
• runTaskAsynchronously(Plugin plugin): exécute la tâche dans un autre Thread.
• runTaskLater(Plugin plugin, long delay): exécute la tâche après un certains nombres de ticks
• runTaskLaterAsynchronously(Plugin plugin, long delay): exécute la tâche dans un autre Thread, après un certains nombres de ticks
• runTaskTimer(Plugin plugin, long delay, long period): exécute la tâche tous les period ticks, après delay ticks.
• runTaskTimerAsynchronously(Plugin plugin, long delay, long period): exécute la tâche dans un autre Thread, tous les period ticks, après delay ticks.

Vous obtenez alors un objet BukkitRunnable.

Warning:

Vous ne devriez PAS planifier l'exécution d'une classe héritant de BukkitRunnable avec le BukkitScheduler !

Note: Les méthodes scheduleXXX() permettent de faire la même chose que les méthodes runTaskXXX(). Ces premières ont été dépréciées à cause de leur nom pas clair: les gens pensaient que "scheduleAsyncDelayedTask" voulait dire "schedule a sync task", soit "planifier une tâche synchrone", alors que ça voulait dire "schedule an async task", soit "planifier une tâche asynchrone".

Annulation

Avec BukkitTask

L'objet BukkitTask, associé à une tâche planifiée par le BukkitScheduler, permet de l'annuler très simplement, avec la méthode cancel():

BukkitTask task = Bukkit.getServer().getScheduler().runTask(plugin, new ExempleTask());
task.cancel();//On annule de la tâche

Avec BukkitScheduler

Le BukkitScheduler permet d'annuler une tâche particulière avec cancelTask(int taskId), et d'annuler toutes les tâches d'un plugin avec cancelTasks(Plugin plugin). Vous pouvez obtenir l'id d'une tâche à partir de l'objet BukkitTask associé:

BukkitScheduler scheduler = Bukkit.getServer().getScheduler()
BukkitTask task = scheduler.runTask(plugin, new ExempleTask());
int id = task.getTaskId();//Id de la tâche
scheduler.canceltask(id);//On annule la tâche

Callable et Future

Vous pouvez appeler, de façon synchrone, une implémentation de Callable avec la méthode callSyncMethod(Plugin plugin, Callable<T> task). Vous obtenez alors un objet Future. Pour plus d'informations, regardez la javadoc de Callable et celle de Future.