hudson.cli

Class CLICommand

java.lang.Object

hudson.cli.CLICommand

All Implemented Interfaces:

ExtensionPoint, Cloneable

Direct Known Subclasses:

AbstractBuildRangeCommand, AddJobToViewCommand, BuildCommand, CancelQuietDownCommand, ClearQueueCommand, CloneableCLICommand, CommandDuringBuild, ConnectNodeCommand, ConsoleCommand, CopyJobCommand, CreateJobCommand, CreateNodeCommand, CreateViewCommand, DeleteJobCommand, DeleteNodeCommand, DeleteViewCommand, DisconnectNodeCommand, EnablePluginCommand, GetJobCommand, GetNodeCommand, GetViewCommand, GroovyCommand, GroovyshCommand, HelpCommand, InstallPluginCommand, InstallToolCommand, ListJobsCommand, ListPluginsCommand, LoginCommand, LogoutCommand, OfflineNodeCommand, OnlineNodeCommand, QuietDownCommand, ReloadConfigurationCommand, ReloadJobCommand, RemoveJobFromViewCommand, RunRangeCommand, SessionIdCommand, SetBuildDescriptionCommand, SetBuildDisplayNameCommand, UpdateJobCommand, UpdateNodeCommand, UpdateViewCommand, VersionCommand, WaitNodeOfflineCommand, WaitNodeOnlineCommand, 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

Fields

Modifier and Type	Field and Description
hudson.remoting.Channel	channel Deprecated. Specific to Remoting-based protocol.
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

Constructors

Constructor and Description
CLICommand()

Method Summary

Modifier and Type	Method and Description
static ExtensionList<CLICommand>	all() Returns all the registered CLICommands.
hudson.remoting.Channel	checkChannel() Deprecated. Specific to Remoting-based protocol.
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) Deprecated. Specific to Remoting-based protocol.
protected String	getClientSystemProperty(String name) Deprecated. Specific to Remoting-based protocol.
protected org.kohsuke.args4j.CmdLineParser	getCmdLineParser() Get parser for this command.
static CLICommand	getCurrent() If the calling thread is in the middle of executing a CLI command, return it.
String	getLongDescription() Get long description as a string.
String	getName() Gets the command name.
abstract String	getShortDescription() Gets the quick summary of what this command does.
String	getSingleLineSummary() Get single line summary as a string.
org.acegisecurity.Authentication	getTransportAuthentication() Returns the identity of the client as determined at the CLI transport level.
String	getUsage() Get usage as a string.
protected org.acegisecurity.Authentication	loadStoredAuthentication() Deprecated. Assumes Remoting, and vulnerable to JENKINS-12543.
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	setClientCharset(Charset encoding) Define the encoding for the command.
void	setTransportAuth(org.acegisecurity.Authentication transportAuth)
protected boolean	shouldPerformAuthentication(org.acegisecurity.Authentication auth) Deprecated. Unused.

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

@Deprecated
public transient hudson.remoting.Channel channel

Deprecated. Specific to Remoting-based protocol.

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. You would however then have to consider CliAuthenticator and getTransportAuthentication(), so this is not really recommended.

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 CLI command execution

Jenkins standard exit codes from CLI: 0 means everything went well. 1 means further unspecified exception is thrown while performing the command. 2 means CmdLineException is thrown while performing the command. 3 means IllegalArgumentException is thrown while performing the command. 4 mean IllegalStateException is thrown while performing the command. 5 means AbortException is thrown while performing the command. 6 means AccessDeniedException is thrown while performing the command. 7 means BadCredentialsException is thrown while performing the command. 8-15 are reserved for future usage 16+ mean a custom CLI exit error code (meaning defined by the CLI command itself)

Note: For details - see JENKINS-32273

getCmdLineParser

protected org.kohsuke.args4j.CmdLineParser getCmdLineParser()

Get parser for this command. Exposed to be overridden by CLIRegisterer.

Since:

1.538

checkChannel

@Deprecated
public hudson.remoting.Channel checkChannel()
                                                 throws AbortException

Deprecated. Specific to Remoting-based protocol.

Throws:

AbortException

loadStoredAuthentication

@Deprecated
protected org.acegisecurity.Authentication loadStoredAuthentication()
                                                                         throws InterruptedException

Deprecated. Assumes Remoting, and vulnerable to JENKINS-12543.

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

Throws:

InterruptedException

shouldPerformAuthentication

@Deprecated
protected boolean shouldPerformAuthentication(org.acegisecurity.Authentication auth)

Deprecated. Unused.

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 a custom error code. Error codes 1-15 shouldn;t be used in run() as a custom error code.

Throws:

Exception - If a further unspecified exception is thrown; means: Unknown and/or unexpected issue occurred

org.kohsuke.args4j.CmdLineException - If a wrong parameter specified, input value can't be decoded etc.

IllegalArgumentException - If the execution can't continue due to wrong input parameter (job doesn't exist etc.)

IllegalStateException - If the execution can't continue due to an incorrect state of Jenkins, job, build etc.

AbortException - If the execution can't continue due to an other (rare, but foreseeable) issue

org.acegisecurity.AccessDeniedException - If the caller doesn't have sufficient rights for requested action

org.acegisecurity.BadCredentialsException - If bad credentials were provided to CLI

printUsage

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

getSingleLineSummary

@Restricted(value=org.kohsuke.accmod.restrictions.NoExternalUse.class)
public final String getSingleLineSummary()

Get single line summary as a string.

getUsage

@Restricted(value=org.kohsuke.accmod.restrictions.NoExternalUse.class)
public final String getUsage()

Get usage as a string.

getLongDescription

@Restricted(value=org.kohsuke.accmod.restrictions.NoExternalUse.class)
public final String getLongDescription()

Get long description as a string.

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

@Deprecated
protected String getClientSystemProperty(String name)
                                              throws IOException,
                                                     InterruptedException

Deprecated. Specific to Remoting-based protocol.

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

Throws:

IOException

InterruptedException

setClientCharset

public void setClientCharset(@Nonnull
                             Charset encoding)

Define the encoding for the command.

Since:

2.54

getClientCharset

@Nonnull
protected Charset getClientCharset()
                                     throws IOException,
                                            InterruptedException

Throws:

IOException

InterruptedException

getClientEnvironmentVariable

@Deprecated
protected String getClientEnvironmentVariable(String name)
                                                   throws IOException,
                                                          InterruptedException

Deprecated. Specific to Remoting-based protocol.

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.