开发者指南

插件开发

插件开发主要包括以下的几个要素：

• XPocketPlugin （主要负责处理插件生命周期相关的工作，非必要）
• XPocketCommand （封装了命令实现，必要）
• xpocket.def (配置文件，必要)
• 插件开发示例程序XPocket-plugin-example (opens new window)，插件开发的包依赖XPocket-plugin-spi (opens new window)

1.XPocketPlugin

public interface XPocketPlugin {

    /**
     * init the plugin
     *
     * @param process process info of current xpocket runtime
     */
    void init(XPocketProcess process);

    /**
     * destory the resource current plugin used.
     * @throws java.lang.Throwable
     */
    void destory() throws Throwable;
    
    /**
     * when XPocket switched on this plugin,it will call this method
     * @param context 
     */
    void switchOn(SessionContext context);
    
    /**
     * when XPocket switched off or leave this plugin,it will call this method
     * @param context 
     */
    void switchOff(SessionContext context);
    
    /**
     * print plugin`s own logo when switch in this plugin
     * @param process 
     */
    void printLogo(XPocketProcess process);

}

作为一个接口，如果插件有一些资源准备工作以及资源销毁等操作，那么可以自己实现这个接口。

• init：插件的初始化工作
• destory：负责资源释放
• switchOn：开启插件时会调用
• switchOff：退出插件时会调用
• printLogo：插件自定义logo的打印

XPocket也提供了一个空实现 AbstractXPocketPlugin，用户使用的时候可以继承AbstractXPocketPlugin并自己实现相关逻辑，如果插件不需要进行相关的工作，那么XPocketPlugin并非是必要的。

2.XPocketCommand

public interface XPocketCommand {

        
    /**
     * init XPocketCommand instance
     * @param plugin 
     */
    void init(XPocketPlugin plugin);
    
    /**
     * Do this command support piped execution.
     *
     * @return
     */
    boolean isPiped();

    /**
     * checking the command is avaible now
     *
     * @param cmd
     * @return
     */
    boolean isAvailableNow(String cmd);

    /**
     * detail current command
     * @return 
     */
    String details(String cmd);

    /**
     * invoke
     *
     * @param process
     * @param context
     * @throws java.lang.Throwable
     */
    void invoke(XPocketProcess process, SessionContext context) throws Throwable;
    
    /**
     * return some details of command usage.
     * @return 
     */
    String[] tips();

}

自定义命令所需要实现的接口

• isPiped：是否支持管道操作
• isAvailableNow：当前是否可用
• details：命令详情介绍
• setPlugin：设置所属插件
• invoke：命令的执行逻辑
• tips：命令相关的tips信息

Example

XPocket提供了一个默认的抽象类实现AbstractXPocketCommand以供程序员开发命令时使用,如下所示。

@CommandInfo(name = "example1", usage = "demo command 1", index = 0)
@CommandInfo(name = "example2", usage = "demo command 2", index = 1)
public class ExampleXPocketCommand extends AbstractXPocketCommand {

    @Override
    public void invoke(XPocketProcess process) throws Throwable {
        XPocketProcessTemplate.execute(process, 
                (String cmd, String[] args) -> 
                        String.format("EXECUTION %s %s",cmd , 
                                args == null ? null : Arrays.toString(args)));
    }

}

注解CommandInfo负责提供命令的基本描述信息，如果希望同时提供多个命令的描述信息，那么可以同时使用多个CommandInfo来描述。

3.xpocket.def

包含一些必要的配置信息，主要的配置项包括

• plugin-name : 插件名（必要）
• plugin-namespace : 插件命名空间，通常是公司名，统一大写（必要）
• main-implementation : 插件规则实现类，如果提供了，插件初始化的时候会执行相关的插件生命周期方法（非必要）
• plugin-description : 插件的描述（非必要）
• usage-tips : 插件使用建议（非必要）
• github : 插件的github地址（非必要）
• plugin-command-package : 插件主要可用命令所在的包（非必要）
• plugin-author : 插件作者（非必要）
• plugin-project : 插件项目名（非必要）
• plugin-version : 插件版本（非必要）
• tool-author : 原工具作者（非必要）
• tool-project : 原工具项目名（非必要）
• tool-version : 原工具版本（非必要）

注：该配置文件需要放在META-INF文件夹下，如有不明确，请下载示例程序XPocket-plugin-example (opens new window)

Example

plugin-name=jdb
plugin-namespace=jdk
plugin-version=0.0.1-SNAPSHOT
plugin-author=PerfMa
plugin-project=https://github.com/perfma/xpocket-plugin-jdb
tools-author=Oracle
usage-tips=1.使用jdb -help获取详细帮助信息。\n 2.使用jdb -listconnectors 获取当前支持的所有连接器。\n 3.可以使用例如 jdb -connect com.sun.jdi.SocketAttach:hostname=127.0.0.1,port=8000 链接已经开启debug模式的java进程。 \n 4.使用jdb -classspath .:$CLASS_PATH 来启动jdb会话（windows上需要使用;分隔多个路径），然后通过stop in/at 设置断点并使用run启动一个可以被debug的java进程。\n 5.启动jdb会话以后也可以通过help命令获取详细帮助。
plugin-command-package=com.perfma.xpocket.plugin.jdb
main-implementation=com.perfma.xpocket.plugin.jdb.JDBPlugin

4.使用自定义插件

• 打包自定义插件
• 将打包好的插件的jar包放在xpocket/plugins目录下
• 重新启动xpocket