plugin

插件

概述

本框架采用插件热加载，热卸载的模式对机器人进行交互。所以对于本框架而言，机器人是通过插件的方式进行交互（虽然框架默认自带对机器人进行简单管理的指令，但是我们建议使用插件的形式对机器人进行交互）。

简单使用

可以通过以下方式创建一个插件。

注意，@PluginType是必要的。

package top.focess.qq.plugin.example;

import top.focess.qq.api.plugin.Plugin;
import top.focess.qq.api.plugin.PluginType;

@PluginType
public class TestPlugin extends Plugin {

    @Override
    public void enable() {
        System.out.println("Hello, this is TestPlugin");
    }

    @Override
    public void disable() {
        System.out.println("Goodbye");
    }
}

同时你需要在资源路径上创建plugin.yml文件。

main: top.focess.qq.plugin.example.TestPlugin
name: TestPlugin
version: 1.0.0
author: MidCoard

对于一个插件来说，Plugin#enable()方法就是它的入口方法，Plugin#disable()方法就是它的退出方法。你需要在Plugin#disable()方法里面创建你所需要的资源，然后在Plugin#enable()方法里面释放你创建的资源。

在这个例子中，我们创建了一个插件，它的名字是TestPlugin，作者是MidCoard，版本是1.0.0。当它被加载的时候，会在控制台打印一条消息 "Hello, this is TestPlugin".当它被卸载的时候，会在控制台打印一条消息 "Goodbye"。

但在某些时候，我们并不需要Plugin#enable()方法和Plugin#disable()方法来创建和释放资源，我们就可以让我们的插件继承LazyPlugin，这样就可以不用写Plugin#enable()方法和Plugin#disable()方法了。但是仍然需要创建plugin.yml文件。

package top.focess.qq.plugin.example;

import top.focess.qq.api.plugin.LazyPlugin;
import top.focess.qq.api.plugin.PluginType;

@PluginType
public class TestPlugin extends LazyPlugin {
}

通过一个插件实例，你可以获取插件的名字，作者，版本等信息，可以得到它的默认配置文件以及默认文件夹，可以修改默认配置文件的配置，也可以将自己的数据保存在默认文件夹下面。

package top.focess.qq.plugin.example;

import top.focess.qq.FocessQQ;
import top.focess.qq.api.plugin.Plugin;
import top.focess.qq.api.plugin.PluginType;

import java.io.File;

@PluginType
public class TestPlugin extends Plugin {

    @Override
    public void enable() {
        FocessQQ.getLogger().info("Hello, this is TestPlugin");
        FocessQQ.getLogger().info("Plugin name: " + getName());
        this.getDefaultConfig().set("test", "test");
        File file = new File(getDefaultFolder(), "test.txt");
        if (!file.exists()) {
            try {
                file.createNewFile();
            } catch (Exception e) {
                e.printStackTrace();
            }
        }
        //......
    }

    @Override
    public void disable() {
        this.getDefaultConfig().save();
        //......
    }
}

快捷使用

运行时使用

你可以通过Plugin#plugin()或者Plugin#thisPlugin()静态方法在该插件任何位置获取该插件的单例，从而避免单独单例实现。

加载插件

初始化加载

你可以将插件放在与框架本体同目录的plugins文件夹下面，当框架启动的时候，它会自动加载plugins文件夹下所有的插件。当框架关闭的时候，它会自动卸载所有的插件。

热加载

你可以通过在控制台输入load指令来对插件进行加载。输入unload指令来对插件进行卸载。

load TestPlugin.jar

unload Test

卸载时会自动释放插件相关的所有内存。

其他

plugin.yml

plugin.yml是描述一个插件的基本信息的文件。 它包含8项，分别是main,name,version,author,soft-depend,depend,require-version,limit-version， 其中前两项是必要的（main,name）。

main: top.focess.qq.plugin.example.TestPlugin
# 插件的绝对类路径
name: Test
# 插件的名字
author: MidCoard
# 插件的作者 （默认值：""）
version: 1.0.0
# 插件的版本 （默认值：1.0.0）
soft-depend: Main
# 插件软依赖的其他插件（非必需，默认值无）
depend: Main
# 插件依赖的其他插件（必需，默认值无）
require-version: 4.1.2.0000
# 插件运行时要求的最低框架版本（默认值为当前框架运行版本）
limit-version: 4.1.2.1000
# 插件运行时要求的框架版本（不能高于也不能低于，默认值为当前框架运行版本）

lang.yml

lang.yml为我们存储了语言键值对信息。存储在lang.yml里面的语言信息可以轻松通过Plugin#getLangConfig()对象访问。

我们还特地为语言文件提供了一些方法简单直接输出语言文件里面的信息。

hello: "Hello, this is %s"

package top.focess.qq.plugin.example;

import top.focess.qq.FocessQQ;
import top.focess.qq.api.plugin.Plugin;
import top.focess.qq.api.plugin.PluginType;
import top.focess.qq.api.util.Property;

import java.io.File;

@PluginType
public class TestPlugin extends Plugin {

    @Override
    public void enable() {
        FocessQQ.getLogger().info("Hello, this is " + this.getName()); // 1
        FocessQQ.getLogger().infoLang("hello",this.getName()); // 2
        String value = this.getLangConfig().get("hello");
        FocessQQ.getLogger().info(String.format(value,this.getName())); // 3
        // 这三句执行结果是一样的
    }

    @Override
    public void disable() {
    }
}

注意事项

加载时卸载

当加载时因为不满足某一初始化条件，插件不应该继续加载，而应该卸载时，我们可以通过Plugin#unload()方法结束加载并告诉插件加载器卸载。

package top.focess.qq.plugin.example;

import top.focess.qq.FocessQQ;
import top.focess.qq.api.plugin.Plugin;
import top.focess.qq.api.plugin.PluginType;
import top.focess.qq.api.util.Property;

import java.io.File;

@PluginType
public class TestPlugin extends Plugin {

    @Override
    public void enable() {
        if (!Property.hasKey("test"))
            this.unload();
        //......
    }

    @Override
    public void disable() {
    }
}

快捷使用

快捷使用不应该在类初始化时使用，只有当插件已经成功加载后Plugin#plugin()和Plugin#thisPlugin()静态方法才会返回正确的结果。