@NotThreadSafe public abstract class

AbstractCommandBuilder

extends Object
implements CommandBuilder<B extends CommandBuilder<B>>
java.lang.Object
   ↳ com.atlassian.stash.scm.AbstractCommandBuilder<B extends com.atlassian.stash.scm.CommandBuilder<B>>
Known Direct Subclasses

Class Overview

Provides a basic implementation of most CommandBuilder functionality, to simplify creating builders. All CommandBuilder and CommandBuilderSupport methods are implemented except for the actual build method.

Summary

Fields
protected final LinkedList<String> arguments Maintains an ordered list of arguments.
protected final String binary The binary to execute when the command is run.
protected final Map<String, String> environment Maintains a map of environment variables and their values.
protected CommandErrorHandler errorHandler The CommandErrorHandler to receive and process the InputStream for reading data from the command's error stream.
protected CommandExitHandler exitHandler The CommandExitHandler to be invoked when the command runs.
protected final I18nService i18nService The I18nService, used to internationalise error messages for exceptions thrown during processing.
protected CommandInputHandler inputHandler The CommandInputHandler to receive and process the OutputStream for feeding data into the command.
protected File workingDirectory The working directory in which the command should be run.
Protected Constructors
AbstractCommandBuilder(I18nService i18nService, String binary)
Constructs a new AbstractCommandBuilder and sets the I18nService to use for internationalising error messages and the binary to execute.
AbstractCommandBuilder(I18nService i18nService, String binary, File workingDirectory)
Constructs a new AbstractCommandBuilder, sets the I18nService to use for internationalising error messages and the binary to execute, and optionally sets the workingDirectory where it should be executed.
Public Methods
@Nonnull B argument(String argument)
Appends the provided argument to the arguments, after ensuring it is not blank.
@Nonnull B argumentAfter(String anchor, String argument)
Finds the index of the specified anchor and inserts the provided argument immediately after it in the arguments.
@Nonnull B argumentAt(int index, String argument)
Inserts the provided argument at the specified index in the arguments, after ensuring it is not blank.
@Nonnull B argumentBefore(String anchor, String argument)
Finds the index of the specified anchor and inserts the provided argument directly before it in the arguments.
@Nonnull B clearArguments()
Clears the arguments, but does not null or replace the list instance.
@Nonnull B clearEnvironment()
Clears the environment, but does not null or replace the map instance.
@Nonnull B clearInputHandler()
Clears the inputHandler, setting it to null.
@Nonnull B defaultErrorHandler()
Indicates the default CommandErrorHandler should be applied when build(CommandOutputHandler) is called by setting the errorHandler to null.
@Nonnull B defaultExitHandler()
Indicates the default CommandExitHandler should be applied when build(CommandOutputHandler) is called by setting the exitHandler to null.
@Nonnull B defaultWorkingDirectory()
Indicates the default working directory should be used when build(CommandOutputHandler) is called by setting the workingDirectory to null.
@Nonnull B environment(String name, String value)
Puts the provided value in the environment map with the specified name, after ensuring both the name and value are not blank.
@Nonnull B errorHandler(CommandErrorHandler value)
Sets the provided value as the errorHandler to use for processing the standard error stream when the built command is executed.
@Nonnull B exitHandler(CommandExitHandler value)
Sets the provided value as the exitHandler to be called when the built command exits or is canceled.
@Nonnull B inputHandler(CommandInputHandler value)
Sets the provided value as the inputHandler to use for providing data on the standard input stream when the built command is executed.
@Nonnull B workingDirectory(File value)
Sets the provided value as the workingDirectory to use when the built command is executed.
@Nonnull B workingDirectory(String value)
Constructs a File from the provided value and sets it as the working directory to use when the built command is executed.
Protected Methods
@Nonnull File directoryExists(File value)
Ensures the provided File is not null, exists and is a directory.
@Nullable File directoryExistsOrIsNull(File value)
Ensures the provided File is null, or that it exists and is a directory.
@Nonnull String notBlank(String argument)
Ensures the provided argument is not null, empty or blank.
abstract B self()
Returns a reference to the current builder, typed correctly to appease Java generics.
[Expand]
Inherited Methods
From class java.lang.Object
From interface com.atlassian.stash.scm.CommandBuilder
From interface com.atlassian.stash.scm.CommandBuilderSupport

Fields

protected final LinkedList<String> arguments

Maintains an ordered list of arguments. LinkedList is used to optimise insertion, since the argument list is modified more than it is read.

Derived classes may add and remove arguments, but they may not replace the list reference.

protected final String binary

The binary to execute when the command is run. This must be provided to the constructor, cannot be null and may not be updated.

Note: When constructing the Command in build(CommandOutputHandler), the derived class may opt to use an alternative, equivalent binary. For example, when using git, give a binary of "git" and a first argument of "http-backend", the builder may opt to call git-http-backend (from libexec/git-core) rather than git http-backend.

protected final Map<String, String> environment

Maintains a map of environment variables and their values.

Derived classes may add, replace and remove keys and their values, but they may not replace the map reference.

Note: Java's ProcessBuilder.environment does not support null keys or values. Derived classes should validate entries before they are put into the map to ensure they do not violate that contract.

protected CommandErrorHandler errorHandler

The CommandErrorHandler to receive and process the InputStream for reading data from the command's error stream. This field may be null, but when it is implementations should apply a default when building the Command. The default should be accumulate error stream output to provide to the CommandExitHandler.

See Also
  • com.atlassian.utils.process.StringOutputHandler

protected CommandExitHandler exitHandler

The CommandExitHandler to be invoked when the command runs. This field may be null, but when it is implementations should apply a default when building the Command.

protected final I18nService i18nService

The I18nService, used to internationalise error messages for exceptions thrown during processing.

protected CommandInputHandler inputHandler

The CommandInputHandler to receive and process the OutputStream for feeding data into the command. Not all commands will support input, so this field may be null.

protected File workingDirectory

The working directory in which the command should be run. Per the contract for ProcessBuilder.directory, this field may be null to use the Java process's working directory.

Protected Constructors

protected AbstractCommandBuilder (I18nService i18nService, String binary)

Constructs a new AbstractCommandBuilder and sets the I18nService to use for internationalising error messages and the binary to execute.

Parameters
i18nService the I18nService for internationalising error messages
binary the binary to execute
Throws
IllegalArgumentException if the provided binary is empty or blank
NullPointerException if the provided i18nService or binary is null

protected AbstractCommandBuilder (I18nService i18nService, String binary, File workingDirectory)

Constructs a new AbstractCommandBuilder, sets the I18nService to use for internationalising error messages and the binary to execute, and optionally sets the workingDirectory where it should be executed.

Parameters
i18nService the I18nService for internationalising error messages
binary the binary to execute
workingDirectory the working directory for the command, or null for the default
Throws
IllegalArgumentException if the provided binary is empty or blank, or if a working directory is provided which does not exist or is not a directory
NullPointerException if the provided i18nService or binary is null

Public Methods

@Nonnull public B argument (String argument)

Appends the provided argument to the arguments, after ensuring it is not blank.

Parameters
argument the argument to append to the command
Returns
Throws
IllegalArgumentException if the provided argument is empty or blank
NullPointerException if the privided argument is null

@Nonnull public B argumentAfter (String anchor, String argument)

Finds the index of the specified anchor and inserts the provided argument immediately after it in the arguments. If the anchor is not found, the provided argument is appended at the end of the argument list.

Parameters
anchor the argument serving as the anchor for the new argument
argument the argument to add immediately after the specified anchor
Returns
Throws
IllegalArgumentException if the provided anchor or argument is empty or blank
NullPointerException if the provided anchor or argument is null

@Nonnull public B argumentAt (int index, String argument)

Inserts the provided argument at the specified index in the arguments, after ensuring it is not blank.

Parameters
index the index at which the argument should be inserted
argument the argument to insert at the specified index
Returns
Throws
IllegalArgumentException if the provided argument is empty or blank
IndexOutOfBoundsException if the specified index is out of range for the argument list
NullPointerException if the provided argument is null

@Nonnull public B argumentBefore (String anchor, String argument)

Finds the index of the specified anchor and inserts the provided argument directly before it in the arguments. If the anchor is not found, the provided argument is appended at the end of the argument list.

Parameters
anchor the argument serving as the anchor for the new argument
argument the argument to add immediately before the specified anchor
Returns
Throws
IllegalArgumentException if the provided anchor or argument is empty or blank
NullPointerException if the provided anchor or argument is null

@Nonnull public B clearArguments ()

Clears the arguments, but does not null or replace the list instance.

Returns

@Nonnull public B clearEnvironment ()

Clears the environment, but does not null or replace the map instance.

Returns

@Nonnull public B clearInputHandler ()

Clears the inputHandler, setting it to null.

Returns

@Nonnull public B defaultErrorHandler ()

Indicates the default CommandErrorHandler should be applied when build(CommandOutputHandler) is called by setting the errorHandler to null.

Derived classes may override this to preemptively set the default error handler, or they may apply the default in build(CommandOutputHandler) when the errorHandler field is null. The latter is the preferred approach, as it does not require code using the builder to call this method to trigger applying the default handler.

Returns

@Nonnull public B defaultExitHandler ()

Indicates the default CommandExitHandler should be applied when build(CommandOutputHandler) is called by setting the exitHandler to null.

Derived classes may override this to preemptively set the default exit handler, or they may apply the default in build(CommandOutputHandler) when the exitHandler field is null. The latter is the preferred approach, as it does not require code using the builder to call this method to trigger applying the default handler.

Returns

@Nonnull public B defaultWorkingDirectory ()

Indicates the default working directory should be used when build(CommandOutputHandler) is called by setting the workingDirectory to null. This is consistent with ProcessBuilder.

Returns

@Nonnull public B environment (String name, String value)

Puts the provided value in the environment map with the specified name, after ensuring both the name and value are not blank.

Parameters
name the name of the environment variable to set
value the value to set for the environment variable
Returns
Throws
IllegalArgumentException if the provided name or value is empty or blank
NullPointerException if the provided name or value is null

@Nonnull public B errorHandler (CommandErrorHandler value)

Sets the provided value as the errorHandler to use for processing the standard error stream when the built command is executed.

Note: As described on the CommandErrorHandler and CommandExitHandler interfaces, providing an error handler will prevent the exit handler from receiving any output written to the standard error stream.

Parameters
value the handler to receive and process the command's error stream
Returns
Throws
NullPointerException if the provided value is null

@Nonnull public B exitHandler (CommandExitHandler value)

Sets the provided value as the exitHandler to be called when the built command exits or is canceled.

Note: As described on the CommandErrorHandler and CommandExitHandler interfaces, providing an error handler will prevent the exit handler from receiving any output written to the standard error stream.

Parameters
value the handler which should be invoked when the command exits
Returns
Throws
NullPointerException if the provided value is null

@Nonnull public B inputHandler (CommandInputHandler value)

Sets the provided value as the inputHandler to use for providing data on the standard input stream when the built command is executed.

Parameters
value the handler to receive and process the command's input stream
Returns
Throws
NullPointerException if the provided value is null

@Nonnull public B workingDirectory (File value)

Sets the provided value as the workingDirectory to use when the built command is executed.

Parameters
value the desired working directory
Returns
Throws
IllegalArgumentException if the provided value does not exist, or does not reference a directory
NullPointerException if the provided value is null

@Nonnull public B workingDirectory (String value)

Constructs a File from the provided value and sets it as the working directory to use when the built command is executed.

Parameters
value the absolute path to the desired working directory
Returns
Throws
IllegalArgumentException if the provided value does not exist, or does not reference a directory
NullPointerException if the provided value is null

Protected Methods

@Nonnull protected File directoryExists (File value)

Ensures the provided File is not null, exists and is a directory.

Parameters
value the File to validate
Returns
  • the provided value
Throws
IllegalArgumentException if the provided value does not exist, or does not reference a directory
NullPointerException if the provided value is null

@Nullable protected File directoryExistsOrIsNull (File value)

Ensures the provided File is null, or that it exists and is a directory.

Parameters
value the File to validate
Returns
  • the provided value, which may be null
Throws
IllegalArgumentException if the provided value is not null but does not exist, or does not reference a directory

@Nonnull protected String notBlank (String argument)

Ensures the provided argument is not null, empty or blank. The returned argument is trimmed to remove both leading and trailing whitespace.

Parameters
argument the argument to validate
Returns
  • the provided argument, trimmed
Throws
IllegalArgumentException if the provided argument is empty or blank
NullPointerException if the provided argument is null

protected abstract B self ()

Returns a reference to the current builder, typed correctly to appease Java generics.

Implementations of this method on derived builders are encouraged to use a covariant return type to return the actual implementation class. For example:

     public interface MyBuilder extends CommandBuilder<MyBuilder> {
         //Implementation omitted
     }

     public class DefaultMyBuilder extends AbstractCommandBuilder<MyBuilder> implements MyBuilder {
         //Implementation omitted

         @Override
         protected DefaultMyBuilder self() {
             return this;
         }
     }
 

Returns
  • this, in a derived class