Package hudson.cli

Class CLICommand

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

      • locale

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

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

      • getCmdLineParser

        protected org.kohsuke.args4j.CmdLineParser getCmdLineParser()
        Get parser for this command. Exposed to be overridden by CLIRegisterer.
        Since:
        1.538

      • 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

      • setTransportAuth2

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

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

      • setClientCharset

        public void setClientCharset​(@NonNull
                             Charset encoding)
        Define the encoding for the command.
        Since:
        2.54

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

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