com.atlassian.bitbucket.scm

Interface CommandExitHandler

public interface CommandExitHandler

Describes a handler for processing Command exit details, whether the command completes or is canceled. The most common use case for implementing this interface is to process exit code, standard error or Throwable information from the command's execution to determine whether the command "failed" or "succeeded". For "failed" commands, implementations may throw an exception to explain the failure. When throwing an exception, implementors are encouraged to throw exceptions derived from:

• CommandCanceledException if the command was canceled in an unexpected way; for example, in response to an error during output processing
• CommandFailedException if the command exited abnormally; for example, in response to invalid input

Note: Using a CommandErrorHandler may affect the input received by implementations of this interface. If a custom CommandErrorHandler is used, no stdErr will be received by this handler. It is expected that any output written to standard error has already been processed by that handler and does not need to be reprocessed by this handler.

Method Summary

Modifier and Type	Method and Description
void	onCancel(String command, int exitCode, String stdErr, Throwable thrown) Invoked after a Command exits after having been canceled.
void	onExit(String command, int exitCode, String stdErr, Throwable thrown) Invoked after a Command exists after running to completion without being canceled.

Method Detail

onCancel

void onCancel(@Nonnull
              String command,
              int exitCode,
              @Nullable
              String stdErr,
              @Nullable
              Throwable thrown)

Invoked after a Command exits after having been canceled. Commands may be canceled by:

• their CommandErrorHandler
• their CommandInputHandler
• their CommandOutputHandler
• their Future, for AsyncCommand

For some commands, being canceled is not an indication of an error condition. For example, an output handler receiving a PageRequest may cancel the command when the requested page has been filled. However, it is worth noting that, to the executing command, being canceled is usually unexpected and will often result in a non-zero exit code (often 13, for the SIGPIPE signal the command receives when the JVM closes streams to the process).

Parameters:

command - the command that was canceled

exitCode - the exit code from the process

stdErr - any output written to standard error, if no CommandErrorHandler is in use

thrown - any exception thrown by the handlers or the command implementation

onExit

void onExit(@Nonnull
            String command,
            int exitCode,
            @Nullable
            String stdErr,
            @Nullable
            Throwable thrown)

Invoked after a Command exists after running to completion without being canceled. The command may have completed successfully or failed; determining which is left to the implementation to determine.

Some potential candidates for detecting failures:

• non-zero exit codes
• output written to standard error
• exceptions thrown by a handler

Each of these candidates is situational. For example, some commands that perform long-running or verbose processing and write results to standard output write progress information to standard error. For such commands, the presence of standard error output does not necessarily indicate a failure.

Multiple failure cases may be triggered at once. For example, if a command returns with a non-zero exit code, it may have written an explanation to standard error or produced other output that triggered one of the handlers to throw an exception. Prioritising or merging the possible sources of error details is left to the implementor; it is not part of the contract for this interface.

Parameters:

command - the command that has exited

exitCode - the exit code from the process

stdErr - any output written to standard error, if no CommandErrorHandler is in use

thrown - any exception thrown by the handlers or the command implementation