public interface

CommandExitHandler

com.atlassian.bitbucket.scm.CommandExitHandler

Class Overview

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:

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.

Summary

Public Methods
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.

Public Methods

public void onCancel (String command, int exitCode, String stdErr, Throwable thrown)

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

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

public void onExit (String command, int exitCode, String stdErr, 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