Jenkins插件开发（6.2）—— 如何自定义CLI命令

官方文档参照：https://wiki.jenkins-ci.org/display/JENKINS/Writing+CLI+commands

Plugins can contribute additional commands to Jenkins CLI which, since Jenkins 1.445, will also be available via Jenkins SSH.

This is useful for (1) exposing administrative commands to admins, so that they can script some of the Jenkins babysitting work, and (2) exposing data and operations to builds executing inside Jenkins, so that they can interact with Jenkins in a richer way.

Writing commands can be done in two ways.

By putting CLIMethod on methods of your model objects

If you are exposing behaviors of your model objects as CLI commands, the easiest way to achieve it is to put @CLIMethod on a method of your model object. See Queue.clear() as an example. In addition to the command name as specified in the annotation, you also need to define "CLI.command-name.shortDescription" as a message resource, which captures one line human-readable explanation of the command (see CLICommand.getShortDescription()).

public class AbstractItem {
    @CLIMethod(name="delete-job")
    public synchronized void delete() throws IOException, InterruptedException {
        performDelete();

        if(this instanceof TopLevelItem)
            Hudson.getInstance().deleteJob((TopLevelItem)this);

        Hudson.getInstance().rebuildDependencyGraph();
    }
    ...
}

Notice that the method is an instance method. So when the delete-job command is executed, which job is deleted? To resolve this, you also need to define a "CLI resolver", which uses a portion of arguments and options to determine the instance object that receives a method call.

@CLIResolver
public static AbstractItem resolveForCLI(
        @Argument(required=true,metaVar="NAME",usage="Job name") String name) throws CmdLineException {
    AbstractItem item = Hudson.getInstance().getItemByFullName(name, AbstractItem.class);
    if (item==null)
        throw new CmdLineException(null,"No such job exists:"+name);
    return item;
}

Of all the resolver methods that are discovered, Jenkins picks the one that returns the best return type. It doesn't matter where the resolver method is defined, or how it's named.

Both resolver methods and CLI methods can have any number of args4j annotations, which causes the parameters and arguments to be injected upon a method invocation. All the other unannotated parameters receive null. Combined with the stapler method binding, this enables you to make your method invokable from both CLI and HTTP.

备注：

结合@CLIMethod的JavaDoc文档 http://javadoc.jenkins-ci.org/hudson/cli/declarative/CLIMethod.html

总共要做三件事情：

（1）添加一个带有@CLIMethod(name="xxxx")注解的方法，来申明CLI命令

（2）添加一个带有@CLIResolver来得到Item

（3）添加Messages.properties到同级目录下

对于第（3）点要特别说明一下：

取自https://wiki.jenkins-ci.org/display/JENKINS/Writing+CLI+commands的“In addition to the command name as specified in the annotation, you also need to define "CLI.command-name.shortDescription" as a message resource, which captures one line human-readable explanation of the command (see CLICommand.getShortDescription()).”，以及取自http://javadoc.jenkins-ci.org/hudson/cli/declarative/CLIMethod.html的“You need to have Messages.properties in the same package with the CLI.command-name.shortDescription key to describe the command. This is used for the same purpose as CLICommand.getShortDescription().”

让我们知道需要创建一个Messages.properties文件。而且从java doc看，好像是要我们把Messages.properties放到java文件的同级目录下。（好吧，我承认，我踩到这个坑了，而且被困了很长时间。mvn clean package运行CliSanityTest总是报找不到Message的资源文件：No resource was found for xxx.Messages）

CLIMethod的Java Doc里面的"same package"应该解释为：resources目录下的相同层级目录。

例如：我如果在 src/main/java/com/mycompany/plugin/jenkins/cli/MyCLICommand.java暴露了CLI注解（@CLIMethod，@CLIResolver），

        那么Messages.properties的位置应该是： src/main/resources/com/mycompany/plugin/jenkins/cli/Messages.properties

运行如下命令：

mvn clean package
set MAVEN_OPTS=-Xdebug -Xrunjdwp:transport=dt_socket,server=y,address=8000,suspend=n
mvn hpi:run

登录到：http://localhost:8080/cli后，可以看到自定义的CLI命令已经被加到列表里了，截图如下：

下载jenkins-cli.jar后，运行如下命令后，也会发现自定义CLI命令也被加到help列表中。

java -jar jenkins-cli.jar -s http://localhost:8080/ help

 对于第（2）点也要特别说明一下：

TBD

By extending CLICommand

You can also implement a CLI commmand as a subtype of CLICommand, and put @Extension. You can use existing implementations in the core, such as GroovyCommand, as a starting point. CLICommand exposes a lower-level control of the CLI set up (such as a Channel.)

This approach is suitable for the commands that require more serious terminal interaction and remote code execution.

See the javadoc of CLICommand for more details.