com.atlassian.bitbucket.scm

Interface CommandBuilder<B extends CommandBuilder<B>>

All Superinterfaces:

CommandBuilderSupport<B>

All Known Subinterfaces:

ScmCommandBuilder<B>

@NotThreadSafe
public interface CommandBuilder<B extends CommandBuilder<B>>
extends CommandBuilderSupport<B>

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:

• argument(String)
• argumentAfter(String, String)
• argumentAt(int, String)
• argumentBefore(String, String)
• rawArgument(String)
• rawArgumentAfter(String, String)
• rawArgumentAt(int, String)
• rawArgumentBefore(String, String)

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:

• argument(String)
• argumentAfter(String, String)
• argumentAt(int, String)
• argumentBefore(String, String)

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:

• rawArgument(String)
• rawArgumentAfter(String, String)
• rawArgumentAt(int, String)
• rawArgumentBefore(String, String)

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.

Method Summary

Modifier and Type	Method and Description
B	argument(String argument) Appends the provided argument, with leading and trailing whitespace trimmed
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.
B	argumentAt(int index, String argument) Inserts the provided argument, with leading and trailing whitespace trimmed, at the specified index.
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.
B	clearArguments() Clears any arguments which have been set.
B	clearInputHandler() Clears the input handler, if one has been set.
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.
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.
B	inputHandler(CommandInputHandler value) Sets the input handler which will be used to feed data to the command's input stream.
B	rawArgument(String argument) Appends the provided argument, verbatim
B	rawArgumentAfter(String anchor, String argument) Inserts the provided argument, verbatim, immediately after the specified anchor if the anchor can be found.
B	rawArgumentAt(int index, String argument) Inserts the provided argument, verbatim, at the specified index.
B	rawArgumentBefore(String anchor, String argument) Inserts the provided argument, verbatim, immediately before the specified anchor if the anchor can be found.

Methods inherited from interface com.atlassian.bitbucket.scm.CommandBuilderSupport

build, clearEnvironment, defaultExitHandler, defaultWorkDir, defaultWorkingDirectory, exitHandler, removeEnvironment, withEnvironment, workDir, workDir, workingDirectory, workingDirectory, workingDirectory

Method Detail

argument

@Nonnull
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

argumentAfter

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

argumentAt

@Nonnull
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

argumentBefore

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

clearArguments

@Nonnull
B clearArguments()

Clears any arguments which have been set.

Returns:

this

clearInputHandler

@Nonnull
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

defaultErrorHandler

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

Returns:

this

errorHandler

@Nonnull
B errorHandler(@Nonnull
                        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

inputHandler

@Nonnull
B inputHandler(@Nonnull
                        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

rawArgument

@Nonnull
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

Since:

6.0

rawArgumentAfter

@Nonnull
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

Since:

6.0

rawArgumentAt

@Nonnull
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

Since:

6.0

rawArgumentBefore

@Nonnull
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

Since:

6.0