@NotThreadSafe public interface

CommandBuilder

implements CommandBuilderSupport<B extends CommandBuilderSupport<B>>
com.atlassian.bitbucket.scm.CommandBuilder<B extends com.atlassian.bitbucket.scm.CommandBuilder<B>>
Known Indirect Subclasses

Class Overview

Provides a fluent interface for creating free-form commands using arbitrary arguments.

As this builder is free-form, it is left to the caller to ensure the validity of the command being built. This includes, among other things:

  • the arguments provided
  • the order the arguments are provided in
  • the environment variables defined
  • whether an input handler is supported
Implementors are encouraged not to validate the free-form commands, or to validate them only minimally. This allows callers the most flexibility to use the process or processes backing the commands to their fullest. However, the contract for this builder interface does not prohibit such validation.

Methods for removing property values have two possible prefixes, where each property will only provide one:

  • clear: Removes any set value, for properties that are not required
  • default: Replaces any set value with an appropriate default, for properties that are required

About arguments: Each call to a method accepting an argument is expected to be provided a single argument. Providing multiple arguments separated by a space will cause the executed command to fail. Consider the following example: 


     CommandBuilder<Void> builder = ...;
     builder.command("someCommand").argument("a b").build(someOutputHandler).call();
The argument array for the executed command will contain a single entry, "a b", not two entries "a" and "b". This is likely to result in usage exceptions. This applies to:

About whitespace: In general, leading and trailing whitespace for most arguments is usually a mistake, and likely to result in the command failing unexpectedly. When typing commands into a shell, the shell typically consumes leading and trailing whitespace. That behavior is emulated by the following methods:

Arguments added via those methods will have any leading and trailing whitespace trimmed. If whitespace is intentional, such as when passing a path as an argument, use one of the following methods instead: Arguments added via those methods are added verbatim, with any leading and trailing whitespace intact.

Warning: Command builders are not thread-safe. Each builder should be used on a single thread. If multiple threads require builders, each thread should construct its own. Chained builders returned from any method on builder interfaces are attached to their originating build and share threading semantics. This means calling builder methods and passing the returned objects to different threads is also not supported.

Summary

Public Methods
@Nonnull B argument(String argument)
Appends the provided argument, with leading and trailing whitespace trimmed

Note: Arguments must be provided one per invocation.

@Nonnull B argumentAfter(String anchor, String argument)
Inserts the provided argument, with leading and trailing whitespace trimmed, immediately after the specified anchor if the anchor can be found.
@Nonnull B argumentAt(int index, String argument)
Inserts the provided argument, with leading and trailing whitespace trimmed, at the specified index.
@Nonnull B argumentBefore(String anchor, String argument)
Inserts the provided argument, with leading and trailing whitespace trimmed, immediately before the specified anchor if the anchor can be found.
@Nonnull B clearArguments()
Clears any arguments which have been set.
@Nonnull B clearInputHandler()
Clears the input handler, if one has been set.
@Nonnull B defaultErrorHandler()
Applies the default error handler, which will collect any output written to the error stream and provide that output to the exit handler.
@Nonnull B errorHandler(CommandErrorHandler value)
Sets the error handler which will be used to process any output written to the error stream as the command runs.
@Nonnull B inputHandler(CommandInputHandler value)
Sets the input handler which will be used to feed data to the command's input stream.
@Nonnull B rawArgument(String argument)
Appends the provided argument, verbatim

Note: Arguments must be provided one per invocation.

@Nonnull B rawArgumentAfter(String anchor, String argument)
Inserts the provided argument, verbatim, immediately after the specified anchor if the anchor can be found.
@Nonnull B rawArgumentAt(int index, String argument)
Inserts the provided argument, verbatim, at the specified index.
@Nonnull B rawArgumentBefore(String anchor, String argument)
Inserts the provided argument, verbatim, immediately before the specified anchor if the anchor can be found.
[Expand]
Inherited Methods
From interface com.atlassian.bitbucket.scm.CommandBuilderSupport

Public Methods

@Nonnull public B argument (String argument)

Appends the provided argument, with leading and trailing whitespace trimmed

Note: Arguments must be provided one per invocation. There is no need to quote strings which include spaces; spaces in arguments are not interpreted. They are passed as-is to the command.

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

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

Inserts the provided argument, with leading and trailing whitespace trimmed, immediately after the specified anchor if the anchor can be found. Otherwise, the argument is appended at the end.

Note: Arguments must be provided one per invocation. There is no need to quote strings which include spaces; spaces in arguments are not interpreted. They are passed as-is to the command.

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

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

Inserts the provided argument, with leading and trailing whitespace trimmed, at the specified index.

Note: Arguments must be provided one per invocation. There is no need to quote strings which include spaces; spaces in arguments are not interpreted. They are passed as-is to the command.

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

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

Inserts the provided argument, with leading and trailing whitespace trimmed, immediately before the specified anchor if the anchor can be found. Otherwise, the argument is appended at the end.

Note: Arguments must be provided one per invocation. There is no need to quote strings which include spaces; spaces in arguments are not interpreted. They are passed as-is to the command.

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

@Nonnull public B clearArguments ()

Clears any arguments which have been set.

Returns
  • this

@Nonnull public B clearInputHandler ()

Clears the input handler, if one has been set. Without an input handler, no data will be provided on the command's input stream.

Some commands always read data from their input stream, rather than, or in addition to, considering arguments provided on the command line. For such commands, the caller must provide an explicit input handler; there is no automatic default.

Returns
  • this

@Nonnull public B defaultErrorHandler ()

Applies the default error handler, which will collect any output written to the error stream and provide that output to the exit handler.

Returns
  • this

@Nonnull public B errorHandler (CommandErrorHandler value)

Sets the error handler which will be used to process any output written to the error stream as the command runs.

When using a custom error handler, the exit handler will not receive error stream output; it is assumed that the error handler will have received and processed the output already. If the error handler throws an exception in response to error stream output, the exit handler will receive that exception.

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

@Nonnull public B inputHandler (CommandInputHandler value)

Sets the input handler which will be used to feed data to the command's input stream.

Some commands require specific arguments to trigger processing data provided via an input stream. For such commands, the caller must also provide those arguments in addition to setting the input handler; the builder does not add them automatically.

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

@Nonnull public B rawArgument (String argument)

Appends the provided argument, verbatim

Note: Arguments must be provided one per invocation. There is no need to quote strings which include spaces; spaces in arguments are not interpreted. They are passed as-is to the command.

Parameters
argument the argument to append to the command
Returns
  • this
Throws
NullPointerException if the provided argument is null

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

Inserts the provided argument, verbatim, immediately after the specified anchor if the anchor can be found. Otherwise, the argument is appended at the end.

Note: Arguments must be provided one per invocation. There is no need to quote strings which include spaces; spaces in arguments are not interpreted. They are passed as-is to the command.

Parameters
anchor the argument serving as the anchor for the new argument
argument the argument to add immediately after the specified anchor
Returns
  • this
Throws
NullPointerException if the provided argument is null

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

Inserts the provided argument, verbatim, at the specified index.

Note: Arguments must be provided one per invocation. There is no need to quote strings which include spaces; spaces in arguments are not interpreted. They are passed as-is to the command.

Parameters
index the index at which the argument should be inserted
argument the argument to insert at the specified index
Returns
  • this
Throws
IndexOutOfBoundsException if the provided index is out of bounds
NullPointerException if the provided argument is null

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

Inserts the provided argument, verbatim, immediately before the specified anchor if the anchor can be found. Otherwise, the argument is appended at the end.

Note: Arguments must be provided one per invocation. There is no need to quote strings which include spaces; spaces in arguments are not interpreted. They are passed as-is to the command.

Parameters
anchor the argument serving as the anchor for the new argument
argument the argument to add immediately before the specified anchor
Returns
  • this
Throws
NullPointerException if the provided argument is null