Jump to: navigation, search

Writing CLI commands

Revision as of 14:39, 17 July 2013 by Scott.fisher.oracle.com (Talk | contribs)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)

Plugins can contribute additional commands to Hudson CLI. This is useful for (1) exposing administrative commands to admins, so that they can script some of the Hudson babysitting work, and (2) exposing data and operations to builds executing inside Hudson, so that they can interact with Hudson 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, Hudson 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.

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.