Bukkit/插件开发教程/定时器编程

2016-03-15T11:25:49Z

A390807154：/* BukkitRunnable */

This tutorial will guide you in using the scheduler provided by bukkit. It will allow you to defer the execution of code to a later time. This is not the same as registering a [http://jd.bukkit.org/apidocs/index.html?org/bukkit/event/Listener.html Listener], a block of code which is executed in response to an [http://wiki.bukkit.org/Event_API_Reference event] in the game. Blocks of code may also be scheduled to be executed repeatedly at a fixed interval, with or without a delay. They will continue to execute until completed, or canceled, or your plugin is disabled.

When using [[#BukkitRunnable|BukkitRunnable]], with a separate class, scheduling work occurs in two steps for the programmer.
# Define the work to be done, see the section [[#Defining_work|Defining Work]]
# Notify Bukkit when the work should be executed, see the section [[#Scheduling_Work|Scheduling Work]]

Alternatively, work can be scheduled directly with the scheduler, this also occurs in two steps for the programmer.
# Define the work to be done, in a Runnable or Callable
# Then directly scheduling the work with the Bukkit Scheduler, see the section [[#BukkitScheduler|BukkitScheduler]]

= BukkitRunnable =
[http://jd.bukkit.org/apidocs/index.html?org/bukkit/scheduler/BukkitRunnable.html BukkitRunnable] 实现了[http://docs.oracle.com/javase/6/docs/api/index.html?java/lang/Runnable.html Runnable] 的抽象. 它还提供一个Runnable没有的功能, BukkitRunnables 可以安排和取消他自己的执行. 然而, 如果BukkitRunnables 没有被安排执行, 它也不能取消运行自身. BukkitRunnables 不是定时器, 没有任何定时器的逻辑功能,而且创建并不复杂. 插件应该更常使用BukkitRunnables 并且直接调用run()方法来直接调用 Runnable 和 BukkitScheduler.

: ''更多关于 BukkitRunnable 的信息, 请查看 [http://jd.bukkit.org/apidocs/index.html?org/bukkit/scheduler/BukkitRunnable.html BukkitRunnable JavaDocs]''

== 定义工作 ==
插件首先得完成t [http://docs.oracle.com/javase/tutorial/java/IandI/subclasses.html extend] [http://jd.bukkit.org/apidocs/index.html?org/bukkit/scheduler/BukkitRunnable.html BukkitRunnable] 的定义工作. 换句话说, 定义一个你想要定时执行的运行方法.

=== 基本例子 ===
这是可被定时的任务示例.
<blockquote><source lang=java>import org.bukkit.Bukkit;
import org.bukkit.plugin.java.JavaPlugin;
import org.bukkit.scheduler.BukkitRunnable;

public class ExampleTask extends BukkitRunnable {

private final JavaPlugin plugin;

public ExampleTask(JavaPlugin plugin) {
this.plugin = plugin;
}

@Override
public void run() {
// 你需要在运行的时候执行的内容放这
plugin.getServer().broadcastMessage("Welcome to Bukkit! Remember to read the documentation!");
}

}</source></blockquote>

=== 自我取消例子 ===
这是一个运行数次后自我取消的例子
<blockquote><source lang="java">import org.bukkit.plugin.java.JavaPlugin;
import org.bukkit.scheduler.BukkitRunnable;

public class ExampleSelfCancelingTask extends BukkitRunnable {

private final JavaPlugin plugin;

private int counter;

public ExampleSelfCancelingTask(JavaPlugin plugin, int counter) {
this.plugin = plugin;
if (counter < 1) {
throw new IllegalArgumentException("counter must be greater than 1");
} else {
this.counter = counter;
}
}

@Override
public void run() {
// 你需要在运行的时候执行的内容放这
if (counter > 0) {
plugin.getServer().broadcastMessage("Commence greeting in " + counter--);
} else {
plugin.getServer().broadcastMessage("Welcome to Bukkit! Remember to read the documentation!");
this.cancel();
}
}

}</source></blockquote>

== 定时任务 ==
在完成定义工作后, 插件需要定时这个BukkitRunnable. BukkitRunnables 将被定时执行run()方法. BukkitRunnable 的方法列表能在这找到:[http://jd.bukkit.org/rb/apidocs/index.html?org/bukkit/scheduler/BukkitRunnable.html Javadocs for BukkitRunnable]. 所有的run方法都将返回[[#BukkitTask | BukkitTask]] 对象

{{warning| Asynchronous tasks should never access any API in Bukkit}}

=== 例子 ===
这是一个注册了PlayerJoinEvent监听器的插件, 定时任务将在玩家加入游戏后20tick执行.
<blockquote><source lang="java">import org.bukkit.event.EventHandler;
import org.bukkit.event.Listener;
import org.bukkit.event.player.PlayerJoinEvent;
import org.bukkit.plugin.java.JavaPlugin;
import org.bukkit.scheduler.BukkitRunnable;
import org.bukkit.scheduler.BukkitTask;

public final class ExamplePlugin extends JavaPlugin {

@Override
public void onEnable() {
new ExampleListener(this);
}
}

class ExampleListener implements Listener {

private final ExamplePlugin plugin;

public ExampleListener(ExamplePlugin plugin) {
this.plugin = plugin;
plugin.getServer().getPluginManager().registerEvents(this, plugin);
}

@EventHandler
public void onJoin(PlayerJoinEvent event) {
// 创建一个20tick后仅执行一次的任务
BukkitTask task = new ExampleTask(this.plugin).runTaskLater(this.plugin, 20);
}

}
</source></blockquote>

=== 自我取消例子 ===
这是采用之前提到的 ExampleSelfCancelingTask 定时为20tick延迟后执行每10tick执行一次.
<blockquote><source lang="java">import org.bukkit.event.EventHandler;
import org.bukkit.event.Listener;
import org.bukkit.event.player.PlayerJoinEvent;
import org.bukkit.plugin.java.JavaPlugin;
import org.bukkit.scheduler.BukkitRunnable;
import org.bukkit.scheduler.BukkitTask;

public final class ExamplePlugin extends JavaPlugin {

@Override
public void onEnable() {
new ExampleListener(this);
}
}

class ExampleListener implements Listener {

private final ExamplePlugin plugin;

public ExampleListener(ExamplePlugin plugin) {
this.plugin = plugin;
plugin.getServer().getPluginManager().registerEvents(this, plugin);
}

@EventHandler
public void onJoin(PlayerJoinEvent event) {
// 创建定时任务
BukkitTask task = new ExampleSelfCancelingTask(this.plugin, 5).runTaskTimer(this.plugin, 10, 20);
}

}
</source></blockquote>

=== Anonymous BukkitRunnable Example ===
An anonymous BukkitRunnable will allow you to schedule a task, without creating a new class with a name. This examples combines the above two basic examples.
<blockquote><source lang="java">import org.bukkit.event.EventHandler;
import org.bukkit.event.Listener;
import org.bukkit.event.player.PlayerJoinEvent;
import org.bukkit.plugin.java.JavaPlugin;
import org.bukkit.scheduler.BukkitRunnable;
import org.bukkit.scheduler.BukkitTask;

public final class ExamplePlugin extends JavaPlugin {

@Override
public void onEnable() {
new ExampleListener(this);
}
}

class ExampleListener implements Listener {

private final ExamplePlugin plugin;

public ExampleListener(ExamplePlugin plugin) {
this.plugin = plugin;
plugin.getServer().getPluginManager().registerEvents(this, plugin);
}

@EventHandler
public void onJoin(PlayerJoinEvent event) {
// 创建一个20tick执行的匿名任务
new BukkitRunnable() {

@Override
public void run() {
// What you want to schedule goes here
plugin.getServer().broadcastMessage(
"Welcome to Bukkit! Remember to read the documentation!");
}

}.runTaskLater(this.plugin, 20);
}

}</source></blockquote>

= BukkitScheduler =
The [http://jd.bukkit.org/rb/apidocs/index.html?org/bukkit/scheduler/BukkitScheduler.html BukkitScheduler] allows plugins to schedule a [http://docs.oracle.com/javase/6/docs/api/index.html?java/lang/Runnable.html Runnable] and/or a [http://docs.oracle.com/javase/6/docs/api/index.html?java/util/concurrent/Callable.html Callable] , for execution at a later time. The list of methods for BukkitScheduler can be found in the [http://jd.bukkit.org/rb/apidocs/index.html?org/bukkit/scheduler/BukkitScheduler.html Javadocs for BukkitScheduler].

{{Note|Plugins should not schedule a BukkitRunnable with the scheduler, instead they should run the BukkitRunnable with the desired schedule.}}

===Example===
Example for directly scheduling an anonymous Runnable with the BukkitScheduler to run after 20 ticks.
<blockquote><source lang="java">
import org.bukkit.Bukkit;
import org.bukkit.plugin.java.JavaPlugin;
import org.bukkit.scheduler.BukkitScheduler;

public final class ExamplePlugin extends JavaPlugin {
public void onEnable() {
BukkitScheduler scheduler = Bukkit.getServer().getScheduler();
scheduler.scheduleSyncDelayedTask(this, new Runnable() {
@Override
public void run() {
// Do something
}
}, 20L);
}
}
</source></blockquote>

===Repeating Example===
Example for directly scheduling an anonymous Runnable with the BukkitScheduler to run every twenty ticks, forever, starting from when you schedule it.
<blockquote><source lang="java">
import org.bukkit.Bukkit;
import org.bukkit.plugin.java.JavaPlugin;
import org.bukkit.scheduler.BukkitScheduler;

public final class ExamplePlugin extends JavaPlugin {
public void onEnable() {
BukkitScheduler scheduler = Bukkit.getServer().getScheduler();
scheduler.scheduleSyncRepeatingTask(this, new Runnable() {
@Override
public void run() {
// Do something
}
}, 0L, 20L);
}
}
</source></blockquote>

{{warning| Asynchronous tasks should never access any API in Bukkit}}

== BukkitTask ==
A [http://jd.bukkit.org/rb/apidocs/index.html?org/bukkit/scheduler/BukkitTask.html BukkitTask] object is returned whenever a Runnable is scheduled. This object represents the task the scheduled task being executed by the scheduler. For more information see, [http://jd.bukkit.org/rb/apidocs/index.html?org/bukkit/scheduler/BukkitTask.html Javadocs for BukkitTask].

== Callable and Future ==
A [http://docs.oracle.com/javase/6/docs/api/index.html?java/util/concurrent/Callable.html Callable] given to the scheduler to call synchronously returns a [http://docs.oracle.com/javase/6/docs/api/index.html?java/util/concurrent/Future.html Future]. These are standard Java classes, for more information see, [http://docs.oracle.com/javase/6/docs/api/index.html?java/util/concurrent/Callable.html Javadocs for Callable] and [http://docs.oracle.com/javase/6/docs/api/index.html?java/util/concurrent/Future.html Javadocs for Future]

= Tips for thread safety =
The Bukkit API, with the exception of the scheduler package, is not thread safe nor guaranteed to be thread safe.
# Asynchronous tasks should never access any API in Bukkit.
# Do not access or modify shared collections from your asynchronous tasks. Normal collections are [http://stackoverflow.com/questions/1003026/hashmap-concurrency-issue not] [http://lightbody.net/blog/?p=307 thread-safe]. This also applies to objects which are not thread safe.
# An asynchronous task can schedule a synchronous task.
# A synchronous task can schedule an asynchronous task.

{{Languages|Scheduler Programming}}

Minecraft插件百科 - 用户贡献 [zh-cn]

Bukkit/插件开发教程/定时器编程