程序包 org.bukkit.plugin.java

# 类 JavaPlugin

java.lang.Object
org.bukkit.plugin.PluginBase
org.bukkit.plugin.java.JavaPlugin

所有已实现的接口:
  `CommandExecutor`, `TabCompleter`, `TabExecutor`, `Plugin`

public abstract class JavaPlugin extends PluginBase
代表一个 Java 插件及其主类. 其包含了插件正常加载并工作所需的基础方法和字段. 这是一个 `Plugin` 的间接实现.

- ## 构造器概要

  构造器
  限定符
  构造器
  说明
  ``
  `JavaPlugin()`
  `protected`
  `JavaPlugin(@NotNull JavaPluginLoader loader, @NotNull PluginDescriptionFile description, @NotNull File dataFolder, @NotNull File file)`

- ## 方法概要

  修饰符和类型
  方法
  说明
  `protected final @NotNull ClassLoader`
  `getClassLoader()`
  返回这个插件的ClassLoader.
  `@Nullable PluginCommand`
  `getCommand(@NotNull String name)`
  获取这个插件在plugin.yml里注册的命令 命令需要在`PluginDescriptionFile`里已被注册
  `@NotNull FileConfiguration`
  `getConfig()`
  获取这个插件的`FileConfiguration`实例, 它将读取config.yml中的内容.
  `final @NotNull File`
  `getDataFolder()`
  返回存放插件文件数据的文件夹.
  `@Nullable BiomeProvider`
  `getDefaultBiomeProvider(@NotNull String worldName, @Nullable String id)`
  Gets a `BiomeProvider` for use in a default world, as specified in the server configuration
  `@Nullable ChunkGenerator`
  `getDefaultWorldGenerator(@NotNull String worldName, @Nullable String id)`
  获取在服务器配置中指定的默认世界中使用的`ChunkGenerator`.
  `final @NotNull PluginDescriptionFile`
  `getDescription()`
  返回插件的plugin.yml的内容的描述信息.
  `protected @NotNull File`
  `getFile()`
  返回这个插件的文件.
  `@NotNull Logger`
  `getLogger()`
  返回与此服务器日志记录器关联的插件日志记录器.返回的日志记录器自动地用插件的名称标记所有日志消息.
  `static <T extends JavaPlugin>
  T`
  `getPlugin(@NotNull Class<T> clazz)`
  本方法可快速访问某个插件主类(或其子类)对应的插件实例.
  `final @NotNull PluginLoader`
  `getPluginLoader()`
  获取这个插件关联的PluginLoader.
  `static @NotNull JavaPlugin`
  `getProvidingPlugin(@NotNull Class<?> clazz)`
  获取提供给定类的插件.
  `@Nullable InputStream`
  `getResource(@NotNull String filename)`
  获取此插件包中的资源.
  `final @NotNull Server`
  `getServer()`
  返回正在运行此插件的服务器对象.
  `protected final @Nullable Reader`
  `getTextResource(@NotNull String file)`
  提供jar中文本文件的读取器.
  `final boolean`
  `isEnabled()`
  返回插件是否已正常启用.
  `final boolean`
  `isNaggable()`
  使用一个简单的布尔值表达 我们是否可以把一些东西记录到日志文件.
  `boolean`
  `onCommand(@NotNull CommandSender sender, @NotNull Command command, @NotNull String label, @NotNull String[] args)`
  执行给定的命令，成功时返回.
  `void`
  `onDisable()`
  当这个插件被关闭时调用.
  `void`
  `onEnable()`
  启用此插件时调用.
  `void`
  `onLoad()`
  在一个插件被加载之后启动之前调用.
  当有多个插件被加载时,确保所有插件的onLoad()全部调用完毕后才会调用onEnable().
  `@Nullable List<String>`
  `onTabComplete(@NotNull CommandSender sender, @NotNull Command command, @NotNull String alias, @NotNull String[] args)`
  用命令传递的参数请求可能的补全项的list.
  `void`
  `reloadConfig()`
  丢弃 `Plugin.getConfig()`中所有数据并且从磁盘重载.
  `void`
  `saveConfig()`
  保存插件的 `FileConfiguration`, 这可以使用`Plugin.getConfig()`获取.
  `void`
  `saveDefaultConfig()`
  将默认的config.yml文件数据保存到`Plugin.getConfig()`获取的config.yml所在的位置.
  这不会覆盖已经存在的config.yml.
  `void`
  `saveResource(@NotNull String resourcePath, boolean replace)`
  保存内置于插件的.jar文件的某个资源的原始内容(假使该资源可以使用`Plugin.getResource(String)`找到).
  保存于插件数据文件夹的资源的结构层次与.jar文件(内容)相同 (同时保存子目录).
  `protected final void`
  `setEnabled(boolean enabled)`
  设置插件开启的状态.
  `final void`
  `setNaggable(boolean canNag)`
  设置 Naggable 状态
  `@NotNull String`
  `toString()`

  ### 从类继承的方法 org.bukkit.plugin.PluginBase

  `equals, getName, hashCode`

  ### 从类继承的方法 java.lang.Object

  `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

- ## 构造器详细资料

  - ### JavaPlugin

    public JavaPlugin()

  - ### JavaPlugin

    protected JavaPlugin(@NotNull @NotNull JavaPluginLoader loader, @NotNull @NotNull PluginDescriptionFile description, @NotNull @NotNull File dataFolder, @NotNull @NotNull File file)

- ## 方法详细资料

  - ### getDataFolder

    @NotNull public final @NotNull File getDataFolder()
    返回存放插件文件数据的文件夹. 文件夹可能不存在.

    原文: Returns the folder that the plugin data's files are located in. The folder may not yet exist.

    返回:
      文件夹

  - ### getPluginLoader

    @NotNull public final @NotNull PluginLoader getPluginLoader()
    获取这个插件关联的PluginLoader.

    原文: Gets the associated PluginLoader responsible for this plugin

    返回:
      PluginLoader控制的插件.

  - ### getServer

    @NotNull public final @NotNull Server getServer()
    返回正在运行此插件的服务器对象.

    原文: Returns the Server instance currently running this plugin

    返回:
      服务器正在运行的插件

  - ### isEnabled

    public final boolean isEnabled()
    返回插件是否已正常启用.

    原文: Returns a value indicating whether or not this plugin is currently enabled

    返回:
      插件是否启用

  - ### getFile

    @NotNull protected @NotNull File getFile()
    返回这个插件的文件.

    原文: Returns the file which contains this plugin

    返回:
      插件的核心文件

  - ### getDescription

    @NotNull public final @NotNull PluginDescriptionFile getDescription()
    返回插件的plugin.yml的内容的描述信息.

    原文: Returns the plugin.yaml file containing the details for this plugin

    返回:
      plugin.yml的内容描述信息

  - ### getConfig

    @NotNull public @NotNull FileConfiguration getConfig()
    从接口复制的说明: `Plugin`
    获取这个插件的`FileConfiguration`实例, 它将读取config.yml中的内容.

    如果这个插件中含有config.yml文件, 那么这个config.yml将作为默认的配置文件.

    原文:Gets a `FileConfiguration` for this plugin, read through "config.yml"

    If there is a default config.yml embedded in this plugin, it will be provided as a default for this Configuration.

    返回:
      此插件的配置

  - ### getTextResource

    @Nullable protected final @Nullable Reader getTextResource(@NotNull @NotNull String file)
    提供jar中文本文件的读取器.

    返回的 reader 将以 UTF-8 编码读取文本.

    原文: Provides a reader for a text file located inside the jar.

    The returned reader will read text with the UTF-8 charset.

    参数:
      `file` - 需要加载的文本资源文件名
    返回:
      null 如果 `getResource(String)` 返回 null
    抛出:
      `IllegalArgumentException` - 如果文件为 null
    另请参阅:
      - `ClassLoader.getResourceAsStream(String)`

  - ### reloadConfig

    public void reloadConfig()
    从接口复制的说明: `Plugin`
    丢弃 `Plugin.getConfig()`中所有数据并且从磁盘重载.

    原文:Discards any data in `Plugin.getConfig()` and reloads from disk.

  - ### saveConfig

    public void saveConfig()
    从接口复制的说明: `Plugin`
    保存插件的 `FileConfiguration`, 这可以使用`Plugin.getConfig()`获取.

    原文: Saves the `FileConfiguration` retrievable by `Plugin.getConfig()`.

  - ### saveDefaultConfig

    public void saveDefaultConfig()
    从接口复制的说明: `Plugin`
    将默认的config.yml文件数据保存到`Plugin.getConfig()`获取的config.yml所在的位置.
    这不会覆盖已经存在的config.yml.

    原文:Saves the raw contents of the default config.yml file to the location retrievable by `Plugin.getConfig()`.
    This should fail silently if the config.yml already exists.

  - ### saveResource

    public void saveResource(@NotNull @NotNull String resourcePath, boolean replace)
    从接口复制的说明: `Plugin`
    保存内置于插件的.jar文件的某个资源的原始内容(假使该资源可以使用`Plugin.getResource(String)`找到).
    保存于插件数据文件夹的资源的结构层次与.jar文件(内容)相同 (同时保存子目录).

    原文:Saves the raw contents of any resource embedded with a plugin's .jar file assuming it can be found using `Plugin.getResource(String)`.
    The resource is saved into the plugin's data folder using the same hierarchy as the .jar file (subdirectories are preserved).

    参数:
      `resourcePath` - 在插件的.jar文件中查找的内置资源路径.(没有前面的斜杠)
      `replace` - 如果为true，则内置的资源将覆盖现有文件的内容

  - ### getResource

    @Nullable public @Nullable InputStream getResource(@NotNull @NotNull String filename)
    从接口复制的说明: `Plugin`
    获取此插件包中的资源.

    原文: Gets an embedded resource in this plugin

    参数:
      `filename` - 资源文件名
    返回:
      如果文件找到则返回相应的InputStream,否则为null

  - ### getClassLoader

    @NotNull protected final @NotNull ClassLoader getClassLoader()
    返回这个插件的ClassLoader.

    原文: Returns the ClassLoader which holds this plugin

    返回:
      ClassLoader控制的这个插件

  - ### setEnabled

    protected final void setEnabled(boolean enabled)
    设置插件开启的状态.

    原文: Sets the enabled state of this plugin

    参数:
      `enabled` - true表示设置插件为开启, false就是设置插件为关闭

  - ### onCommand

    public boolean onCommand(@NotNull @NotNull CommandSender sender, @NotNull @NotNull Command command, @NotNull @NotNull String label, @NotNull @NotNull String[] args)
    执行给定的命令，成功时返回.
    若返回假（false），则输出plugin.yml下所对应usage的内容返回至玩家聊天窗口（前提需要被定义）.
    译注：为假（false）输出一串例如：Usage: /gamemode [mode] [player]；如果为真（true）则不返回除方法内编写内容外任何内容.

    原文:Executes the given command, returning its success.
    If false is returned, then the "usage" plugin.yml entry for this command (if defined) will be sent to the player.

    参数:
      `sender` - 命令执行的来源（可以是 player 可以是 console）
      `command` - 被执行的命令
      `label` - 使用的命令别名
      `args` - 传递的命令参数（不包含命令主体）
    返回:
      如果是合法的命令则为true，否则为false

  - ### onTabComplete

    @Nullable public @Nullable List<String> onTabComplete(@NotNull @NotNull CommandSender sender, @NotNull @NotNull Command command, @NotNull @NotNull String alias, @NotNull @NotNull String[] args)
    用命令传递的参数请求可能的补全项的list.

    原文:Requests a list of possible completions for a command argument.

    参数:
      `sender` - 发起命令的来源. 至于玩家在命令方块内补全命令，这个来源就是玩家，而不是命令方块.
      `command` - 执行的Command
      `alias` - 使用的别名
      `args` - 传递给这个命令的参数，包括用来补全的部分最终参数
    返回:
      可能的最终补全参数列表(就是list里都是已经补全了的)，或为null则传递给命令执行器

  - ### getCommand

    @Nullable public @Nullable PluginCommand getCommand(@NotNull @NotNull String name)
    获取这个插件在plugin.yml里注册的命令 命令需要在`PluginDescriptionFile`里已被注册

    原文: Gets the command with the given name, specific to this plugin. Commands need to be registered in the `PluginDescriptionFile` to exist at runtime.

    参数:
      `name` - 一个属于这个插件注册了的命令
    返回:
      如果有返回值表示命令存在, 否则返回null

  - ### onLoad

    public void onLoad()
    从接口复制的说明: `Plugin`
    在一个插件被加载之后启动之前调用.
    当有多个插件被加载时,确保所有插件的onLoad()全部调用完毕后才会调用onEnable().

    原文:Called after a plugin is loaded but before it has been enabled.
    When multiple plugins are loaded, the onLoad() for all plugins is called before any onEnable() is called.

  - ### onDisable

    public void onDisable()
    从接口复制的说明: `Plugin`
    当这个插件被关闭时调用.

    原文:Called when this plugin is disabled

  - ### onEnable

    public void onEnable()
    从接口复制的说明: `Plugin`
    启用此插件时调用.

    原文:Called when this plugin is enabled

  - ### getDefaultWorldGenerator

    @Nullable public @Nullable ChunkGenerator getDefaultWorldGenerator(@NotNull @NotNull String worldName, @Nullable @Nullable String id)
    从接口复制的说明: `Plugin`
    获取在服务器配置中指定的默认世界中使用的`ChunkGenerator`.

    原文:Gets a `ChunkGenerator` for use in a default world, as specified in the server configuration

    参数:
      `worldName` - 将应用于世界的名称
      `id` - 唯一 ID,如果有的话,被指定来指示哪个生成器被调用
    返回:
      用于默认世界生成的 ChunkGenerator

  - ### getDefaultBiomeProvider

    @Nullable public @Nullable BiomeProvider getDefaultBiomeProvider(@NotNull @NotNull String worldName, @Nullable @Nullable String id)
    从接口复制的说明: `Plugin`
    Gets a `BiomeProvider` for use in a default world, as specified in the server configuration
    参数:
      `worldName` - Name of the world that this will be applied to
      `id` - Unique ID, if any, that was specified to indicate which biome provider was requested
    返回:
      BiomeProvider for use in the default world generation

  - ### isNaggable

    public final boolean isNaggable()
    从接口复制的说明: `Plugin`
    使用一个简单的布尔值表达 我们是否可以把一些东西记录到日志文件.

    原文:Simple boolean if we can still nag to the logs about things

    返回:
      返回一个布尔值如果这个插件是否可以进行记录

  - ### setNaggable

    public final void setNaggable(boolean canNag)
    从接口复制的说明: `Plugin`
    设置 Naggable 状态

    原文: Set naggable state

    参数:
      `canNag` - 这个插件是可以被记录的吗

  - ### getLogger

    @NotNull public @NotNull Logger getLogger()
    从接口复制的说明: `Plugin`
    返回与此服务器日志记录器关联的插件日志记录器.返回的日志记录器自动地用插件的名称标记所有日志消息.

    原文: Returns the plugin logger associated with this server's logger. The returned logger automatically tags all log messages with the plugin's name.

    返回:
      与此插件相关联的记录器

  - ### toString

    @NotNull public @NotNull String toString()
    覆盖:
      `toString` 在类中 `Object`

  - ### getPlugin

    @NotNull public static <T extends JavaPlugin> T getPlugin(@NotNull @NotNull Class<T> clazz)
    本方法可快速访问某个插件主类(或其子类)对应的插件实例.

    例外:如果插件jar中的插件类不继承JavaPlugin类, 将可能是不同的jar/类加载器.

    译注:这个怎么用呢? 比如我们知道某个插件主类叫 BukkitPluginMain, 如果要获取其实例, 就可以这样做:

         BukkitPluginMain plugin = JavaPlugin.getPlugin(BukkitPluginMain.class);

    原文: This method provides fast access to the plugin that has `provided` the given plugin class, which is usually the plugin that implemented it.

    An exception to this would be if plugin's jar that contained the class does not extend the class, where the intended plugin would have resided in a different jar / classloader.

    类型参数:
      `T` - 任何一个继承了JavaPlugin的类
    参数:
      `clazz` - 所需的类
    返回:
      提供并实现了给定类的插件的实例
    抛出:
      `IllegalArgumentException` - 如果参数 clazz 为 nul
      `IllegalArgumentException` - 如果插件类没有继承`JavaPlugin`类
      `IllegalStateException` - 如果这个类不是插件提供的,抛出无效的状态(IllegalStateException)错误. 比如, 如果调用 `JavaPlugin.getPlugin(JavaPlugin.class)`
      `IllegalStateException` - 如果从静态初始化代码块调用
      `ClassCastException` - 如果插件提供的类没有继承类, 抛出(ClassCastException)错误

  - ### getProvidingPlugin

    @NotNull public static @NotNull JavaPlugin getProvidingPlugin(@NotNull @NotNull Class<?> clazz)
    获取提供给定类的插件.

    原文: This method provides fast access to the plugin that has provided the given class.

    参数:
      `clazz` - 属于某个插件的类
    返回:
      提供此类的插件
    抛出:
      `IllegalArgumentException` - 如果这个类不属于某个JavaPlugin
      `IllegalArgumentException` - 如果参数为null
      `IllegalStateException` - 如果从静态初始化代码块调用