public abstract class CLICommand extends Object implements ExtensionPoint, Cloneable
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.
Extension
on your implementation to have it discovered by Hudson.
main(List, Locale, InputStream, PrintStream, PrintStream)
method directly.
Callable
to a CLI agent by using channel
to get local interaction,
such as uploading a file, asking for a password, etc.
CLIMethod
ExtensionPoint.LegacyInstancesAreScopedToHudson
Modifier and Type | Field and Description |
---|---|
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 and Description |
---|
CLICommand() |
Modifier and Type | Method and Description |
---|---|
static ExtensionList<CLICommand> |
all()
Returns all the registered
CLICommand s. |
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.
|
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()
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
OptionHandler s 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.
|
public transient PrintStream stdout
(In contrast, calling System.out.println(...)
would print out
the message to the server log file, which is probably not what you want.
public transient PrintStream stderr
(In contrast, calling System.out.println(...)
would print out
the message to the server log file, which is probably not what you want.
public transient InputStream stdin
This input stream is buffered to hide the latency in the remoting.
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
public transient Locale locale
public static final hudson.remoting.ChannelProperty<org.acegisecurity.Authentication> TRANSPORT_AUTHENTICATION
Channel.getProperty(Object)
that links to the Authentication
object
which captures the identity of the client given by the transport layer.public String getName()
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".
public abstract String getShortDescription()
public int main(List<String> args, Locale locale, InputStream stdin, PrintStream stdout, PrintStream stderr)
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.
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.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
protected org.kohsuke.args4j.CmdLineParser getCmdLineParser()
CLIRegisterer
.public hudson.remoting.Channel checkChannel() throws AbortException
AbortException
protected org.acegisecurity.Authentication loadStoredAuthentication() throws InterruptedException
ClientAuthenticationCache
if the current transport provides Channel
.InterruptedException
protected boolean shouldPerformAuthentication(org.acegisecurity.Authentication auth)
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
auth
- Always non-null.
If the underlying transport had already performed authentication, this object is something other than
Jenkins.ANONYMOUS
.public org.acegisecurity.Authentication getTransportAuthentication()
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
.
public void setTransportAuth(org.acegisecurity.Authentication transportAuth)
protected abstract int run() throws Exception
This is an internal contract between CLICommand
and its subtype.
To execute CLI method from outside, use main(List, Locale, InputStream, PrintStream, PrintStream)
run()
as a custom error code.Exception
- If a further unspecified exception is thrown; means: Unknown and/or unexpected issue occurredorg.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 incorect state of Jenkins, job, build etc.AbortException
- If the execution can't continue due to an other (rare, but foreseeable) issueorg.acegisecurity.AccessDeniedException
- If the caller doesn't have sufficent rights for requested actionorg.acegisecurity.BadCredentialsException
- If bad credentials were provided to CLIprotected void printUsage(PrintStream stderr, org.kohsuke.args4j.CmdLineParser p)
@Restricted(value=org.kohsuke.accmod.restrictions.NoExternalUse.class) public final String getSingleLineSummary()
@Restricted(value=org.kohsuke.accmod.restrictions.NoExternalUse.class) public final String getUsage()
@Restricted(value=org.kohsuke.accmod.restrictions.NoExternalUse.class) public final String getLongDescription()
protected void printUsageSummary(PrintStream stderr)
protected String getClientSystemProperty(String name) throws IOException, InterruptedException
IOException
InterruptedException
protected Charset getClientCharset() throws IOException, InterruptedException
IOException
InterruptedException
protected String getClientEnvironmentVariable(String name) throws IOException, InterruptedException
IOException
InterruptedException
protected CLICommand createClone()
protected void registerOptionHandlers()
OptionHandler
s and add them to the given command line parser.public static ExtensionList<CLICommand> all()
CLICommand
s.public static CLICommand clone(String name)
public static CLICommand getCurrent()
Copyright © 2018. All rights reserved.