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 connection to 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.
CLIMethod
ExtensionPoint.LegacyInstancesAreScopedToHudson
Modifier and Type | Field and Description |
---|---|
hudson.remoting.Channel |
channel
Deprecated.
No longer used.
|
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.
|
Constructor and Description |
---|
CLICommand() |
Modifier and Type | Method and Description |
---|---|
static ExtensionList<CLICommand> |
all()
Returns all the registered
CLICommand s. |
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.
|
Authentication |
getTransportAuthentication()
Deprecated.
|
org.springframework.security.core.Authentication |
getTransportAuthentication2()
Returns the identity of the client as determined at the CLI transport level.
|
String |
getUsage()
Get usage as a string.
|
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 |
setClientCharset(Charset encoding)
Define the encoding for the command.
|
void |
setTransportAuth(Authentication transportAuth)
|
void |
setTransportAuth2(org.springframework.security.core.Authentication transportAuth) |
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.
@Deprecated public transient hudson.remoting.Channel channel
public transient Locale locale
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 getTransportAuthentication2()
,
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.Code | Definition |
---|---|
0 | everything went well. |
1 | further unspecified exception is thrown while performing the command. |
2 | CmdLineException is thrown while performing the command. |
3 | IllegalArgumentException is thrown while performing the command. |
4 | IllegalStateException is thrown while performing the command. |
5 | AbortException is thrown while performing the command. |
6 | AccessDeniedException is thrown while performing the command. |
7 | BadCredentialsException is thrown while performing the command. |
8-15 | are reserved for future usage. |
16+ | a custom CLI exit error code (meaning defined by the CLI command itself) |
protected org.kohsuke.args4j.CmdLineParser getCmdLineParser()
CLIRegisterer
.@Deprecated public hudson.remoting.Channel checkChannel() throws AbortException
AbortException
public org.springframework.security.core.Authentication getTransportAuthentication2()
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.ANONYMOUS2
.
@Deprecated public Authentication getTransportAuthentication()
getTransportAuthentication2()
public void setTransportAuth2(org.springframework.security.core.Authentication transportAuth)
@Deprecated public void setTransportAuth(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 incorrect state of Jenkins, job, build etc.AbortException
- If the execution can't continue due to an other (rare, but foreseeable) issueorg.springframework.security.access.AccessDeniedException
- If the caller doesn't have sufficient rights for requested actionorg.springframework.security.authentication.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)
@Deprecated protected String getClientSystemProperty(String name) throws IOException, InterruptedException
IOException
InterruptedException
public void setClientCharset(@NonNull Charset encoding)
@NonNull protected Charset getClientCharset() throws IOException, InterruptedException
IOException
InterruptedException
@Deprecated 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 © 2004–2022. All rights reserved.