hudson.cli
Class CLICommand

java.lang.Object
  hudson.cli.CLICommand

All Implemented Interfaces:

ExtensionPoint, Cloneable

Direct Known Subclasses:

AbstractBuildRangeCommand, BuildCommand, CloneableCLICommand, CommandDuringBuild, ConsoleCommand, CopyJobCommand, CreateJobCommand, GetJobCommand, GroovyCommand, GroovyshCommand, HelpCommand, InstallPluginCommand, InstallToolCommand, ListJobsCommand, ListPluginsCommand, LoginCommand, LogoutCommand, SessionIdCommand, SetBuildDescriptionCommand, SetBuildDisplayNameCommand, UpdateJobCommand, VersionCommand, WhoAmICommand

public abstract class CLICommand
extends Object
implements ExtensionPoint, Cloneable

Base class for Hudson CLI.

How does a CLI command work

The users starts the "CLI agent" on a remote system, by specifying arguments, like "java -jar jenkins-cli.jar command arg1 arg2 arg3". The CLI agent creates a remoting channel with the server, and it sends the entire arguments to the server, along with the remoted stdin/out/err.

The Hudson master then picks the right CLICommand to execute, clone it, and calls main(List, Locale, InputStream, PrintStream, PrintStream) method.

Note for CLI command implementor

Start with this document to get the general idea of CLI.

• Put Extension on your implementation to have it discovered by Hudson.
• Use args4j annotation on your implementation to define options and arguments (however, if you don't like that, you could override the main(List, Locale, InputStream, PrintStream, PrintStream) method directly.
• stdin, stdout, stderr are remoted, so proper buffering is necessary for good user experience.
• Send Callable to a CLI agent by using channel to get local interaction, such as uploading a file, asking for a password, etc.

Since:

1.302

Author:

Kohsuke Kawaguchi

See Also:

CLIMethod

Nested Class Summary

Nested classes/interfaces inherited from interface hudson.ExtensionPoint

ExtensionPoint.LegacyInstancesAreScopedToHudson

Field Summary

hudson.remoting.Channel	channel Channel that represents the CLI JVM.
Locale	locale The locale of the client.
PrintStream	stderr Connected to stdout and stderr of the CLI agent that initiated the session.
InputStream	stdin Connected to stdin of the CLI agent.
PrintStream	stdout Connected to stdout and stderr of the CLI agent that initiated the session.
static hudson.remoting.ChannelProperty<org.acegisecurity.Authentication>	TRANSPORT_AUTHENTICATION Key for Channel.getProperty(Object) that links to the Authentication object which captures the identity of the client given by the transport layer.

Constructor Summary

CLICommand()

Method Summary

static ExtensionList<CLICommand>	all() Returns all the registered CLICommands.
hudson.remoting.Channel	checkChannel()
static CLICommand	clone(String name) Obtains a copy of the command for invocation.
protected CLICommand	createClone() Creates a clone to be used to execute a command.
protected Charset	getClientCharset()
protected String	getClientEnvironmentVariable(String name) Convenience method for subtypes to obtain environment variables of the client.
protected String	getClientSystemProperty(String name) Convenience method for subtypes to obtain the system property of the client.
static CLICommand	getCurrent() If the calling thread is in the middle of executing a CLI command, return it.
String	getName() Gets the command name.
abstract String	getShortDescription() Gets the quick summary of what this command does.
org.acegisecurity.Authentication	getTransportAuthentication() Returns the identity of the client as determined at the CLI transport level.
protected org.acegisecurity.Authentication	loadStoredAuthentication() Loads the persisted authentication information from ClientAuthenticationCache if the current transport provides Channel.
int	main(List<String> args, Locale locale, InputStream stdin, PrintStream stdout, PrintStream stderr) Entry point to the CLI command.
protected void	printUsage(PrintStream stderr, org.kohsuke.args4j.CmdLineParser p)
protected void	printUsageSummary(PrintStream stderr) Called while producing usage.
protected void	registerOptionHandlers() Auto-discovers OptionHandlers and add them to the given command line parser.
protected abstract int	run() Executes the command, and return the exit code.
void	setTransportAuth(org.acegisecurity.Authentication transportAuth)
protected boolean	shouldPerformAuthentication(org.acegisecurity.Authentication auth) Determines if the user authentication is attempted through CLI before running this command.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

stdout

public transient PrintStream stdout

Connected to stdout and stderr of the CLI agent that initiated the session. IOW, if you write to these streams, the person who launched the CLI command will see the messages in his terminal.

(In contrast, calling System.out.println(...) would print out the message to the server log file, which is probably not what you want.

stderr

public transient PrintStream stderr

Connected to stdout and stderr of the CLI agent that initiated the session. IOW, if you write to these streams, the person who launched the CLI command will see the messages in his terminal.

(In contrast, calling System.out.println(...) would print out the message to the server log file, which is probably not what you want.

stdin

public transient InputStream stdin

Connected to stdin of the CLI agent.

This input stream is buffered to hide the latency in the remoting.

channel

public transient hudson.remoting.Channel channel

Channel that represents the CLI JVM. You can use this to execute Callable on the CLI JVM, among other things.

Starting 1.445, CLI transports are not required to provide a channel (think of sshd, telnet, etc), so in such a case this field is null.

See checkChannel() to get a channel and throw an user-friendly exception

locale

public transient Locale locale

The locale of the client. Messages should be formatted with this resource.

TRANSPORT_AUTHENTICATION

public static final hudson.remoting.ChannelProperty<org.acegisecurity.Authentication> TRANSPORT_AUTHENTICATION

Key for Channel.getProperty(Object) that links to the Authentication object which captures the identity of the client given by the transport layer.

Constructor Detail

CLICommand

public CLICommand()

Method Detail

getName

public String getName()

Gets the command name.

For example, if the CLI is invoked as java -jar cli.jar foo arg1 arg2 arg4, on the server side CLICommand that returns "foo" from getName() will be invoked.

By default, this method creates "foo-bar-zot" from "FooBarZotCommand".

getShortDescription

public abstract String getShortDescription()

Gets the quick summary of what this command does. Used by the help command to generate the list of commands.

main

public int main(List<String> args,
                Locale locale,
                InputStream stdin,
                PrintStream stdout,
                PrintStream stderr)

Entry point to the CLI command.

The default implementation uses args4j to parse command line arguments and call run(), but if that processing is undesirable, subtypes can directly override this method and leave run() to an empty method.

Parameters:

args - Arguments to the sub command. For example, if the CLI is invoked like "java -jar cli.jar foo bar zot", then "foo" is the sub-command and the argument list is ["bar","zot"].

locale - Locale of the client (which can be different from that of the server.) Good behaving command implementation would use this locale for formatting messages.

stdin - Connected to the stdin of the CLI client.

stdout - Connected to the stdout of the CLI client.

stderr - Connected to the stderr of the CLI client.

Returns:

Exit code from the command.

checkChannel

public hudson.remoting.Channel checkChannel()
                                     throws AbortException

Throws:

AbortException

loadStoredAuthentication

protected org.acegisecurity.Authentication loadStoredAuthentication()
                                                             throws InterruptedException

Loads the persisted authentication information from ClientAuthenticationCache if the current transport provides Channel.

Throws:

InterruptedException

shouldPerformAuthentication

protected boolean shouldPerformAuthentication(org.acegisecurity.Authentication auth)

Determines if the user authentication is attempted through CLI before running this command.

If your command doesn't require any authentication whatsoever, and if you don't even want to let the user authenticate, then override this method to always return false — doing so will result in all the commands running as anonymous user credential.

Note that even if this method returns true, the user can still skip aut

Parameters:

auth - Always non-null. If the underlying transport had already performed authentication, this object is something other than Jenkins.ANONYMOUS.

getTransportAuthentication

public org.acegisecurity.Authentication getTransportAuthentication()

Returns the identity of the client as determined at the CLI transport level.

When the CLI connection to the server is tunneled over HTTP, that HTTP connection can authenticate the client, just like any other HTTP connections to the server can authenticate the client. This method returns that information, if one is available. By generalizing it, this method returns the identity obtained at the transport-level authentication.

For example, imagine if the current SecurityRealm is doing Kerberos authentication, then this method can return a valid identity of the client.

If the transport doesn't do authentication, this method returns Jenkins.ANONYMOUS.

setTransportAuth

public void setTransportAuth(org.acegisecurity.Authentication transportAuth)

run

protected abstract int run()
                    throws Exception

Executes the command, and return the exit code.

This is an internal contract between CLICommand and its subtype. To execute CLI method from outside, use main(List, Locale, InputStream, PrintStream, PrintStream)

Returns:

0 to indicate a success, otherwise an error code.

Throws:

AbortException - If the processing should be aborted. Hudson will report the error message without stack trace, and then exits this command.

Exception - All the other exceptions cause the stack trace to be dumped, and then the command exits with an error code.

printUsage

protected void printUsage(PrintStream stderr,
                          org.kohsuke.args4j.CmdLineParser p)

printUsageSummary

protected void printUsageSummary(PrintStream stderr)

Called while producing usage. This is a good method to override to render the general description of the command that goes beyond a single-line summary.

getClientSystemProperty

protected String getClientSystemProperty(String name)
                                  throws IOException,
                                         InterruptedException

Convenience method for subtypes to obtain the system property of the client.

Throws:

IOException

InterruptedException

getClientCharset

protected Charset getClientCharset()
                            throws IOException,
                                   InterruptedException

Throws:

IOException

InterruptedException

getClientEnvironmentVariable

protected String getClientEnvironmentVariable(String name)
                                       throws IOException,
                                              InterruptedException

Convenience method for subtypes to obtain environment variables of the client.

Throws:

IOException

InterruptedException

createClone

protected CLICommand createClone()

Creates a clone to be used to execute a command.

registerOptionHandlers

protected void registerOptionHandlers()

Auto-discovers OptionHandlers and add them to the given command line parser.

all

public static ExtensionList<CLICommand> all()

Returns all the registered CLICommands.

clone

public static CLICommand clone(String name)

Obtains a copy of the command for invocation.

getCurrent

public static CLICommand getCurrent()

If the calling thread is in the middle of executing a CLI command, return it. Otherwise null.