Package hudson.cli

Class CLICommand

java.lang.Object
hudson.cli.CLICommand
All Implemented Interfaces:
ExtensionPoint, Cloneable
Direct Known Subclasses:
AbstractBuildRangeCommand, AddJobToViewCommand, BuildCommand, CancelQuietDownCommand, ClearQueueCommand, CloneableCLICommand, ConnectNodeCommand, ConsoleCommand, CopyJobCommand, CreateJobCommand, CreateNodeCommand, CreateViewCommand, DeleteJobCommand, DeleteNodeCommand, DeleteViewCommand, DisablePluginCommand, DisconnectNodeCommand, EnablePluginCommand, GetJobCommand, GetNodeCommand, GetViewCommand, GroovyCommand, GroovyshCommand, HelpCommand, InstallPluginCommand, ListJobsCommand, ListPluginsCommand, OfflineNodeCommand, OnlineNodeCommand, QuietDownCommand, ReloadConfigurationCommand, ReloadJobCommand, RemoveJobFromViewCommand, RunRangeCommand, SafeRestartCommand, SessionIdCommand, SetBuildDescriptionCommand, SetBuildDisplayNameCommand, StopBuildsCommand, 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 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.

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.
Since:
1.302
Author:
Kohsuke Kawaguchi
See Also:

  • Field Details

    • ALLOW_AT_SYNTAX

      @Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class) public static boolean ALLOW_AT_SYNTAX
      Boolean values to either allow or disallow parsing of @-prefixes. If a command line value starts with @, it is interpreted as being a file, loaded, and interpreted as if the file content would have been passed to the command line

    • 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.
      No longer used.

    • locale

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

  • Constructor Details

    • CLICommand

      public CLICommand()

  • Method Details

    • 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 getTransportAuthentication2(), 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
      CodeDefinition
      0everything went well.
      1further unspecified exception is thrown while performing the command.
      2CmdLineException is thrown while performing the command.
      3IllegalArgumentException is thrown while performing the command.
      4IllegalStateException is thrown while performing the command.
      5AbortException is thrown while performing the command.
      6AccessDeniedException is thrown while performing the command.
      7BadCredentialsException is thrown while performing the command.
      8-15are reserved for future usage.
      16+a custom CLI exit error code (meaning defined by the CLI command itself)
      Note: For details - see JENKINS-32273

    • handleException

      protected int handleException(Throwable e, CLIContext context, org.kohsuke.args4j.CmdLineParser p)
      Determines command stderr output and return the exit code as described on main(List, Locale, InputStream, PrintStream, PrintStream)

    • 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

    • getTransportAuthentication2

      public org.springframework.security.core.Authentication getTransportAuthentication2()
      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.ANONYMOUS2.

      Since:
      2.266

    • getTransportAuthentication

      @Deprecated public Authentication getTransportAuthentication()
      Deprecated.
      use getTransportAuthentication2()

    • setTransportAuth2

      public void setTransportAuth2(org.springframework.security.core.Authentication transportAuth)
      Since:
      2.266

    • setTransportAuth

      @Deprecated public void setTransportAuth(Authentication transportAuth)
      Deprecated.
      use setTransportAuth2(org.springframework.security.core.Authentication)

    • 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.springframework.security.access.AccessDeniedException - If the caller doesn't have sufficient rights for requested action
      org.springframework.security.authentication.BadCredentialsException - If bad credentials were provided to CLI

    • printUsage

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

    • getSingleLineSummary

      @Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class) public final String getSingleLineSummary()
      Get single line summary as a string.

    • getUsage

      @Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class) public final String getUsage()
      Get usage as a string.

    • getLongDescription

      @Restricted(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.

    • 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.