org.unix4j.builder

Interface CommandBuilder

All Superinterfaces:

To

All Known Subinterfaces:

Unix4jCommandBuilder

All Known Implementing Classes:

DefaultCommandBuilder, DefaultUnix4jCommandBuilder

public interface CommandBuilder
extends To

A builder used to build a single command or a chain of joined commands. Every command other than the last command redirects its output to the standard input of the next command. The last command writes its output to the final output destination. Executing a command and returning the output in different formats is reflected by the toXXX(..) methods inherited from the pseudo To command.

Method Summary

Methods

Modifier and Type	Method and Description
CommandBuilder	apply(LineOperation operation) Adds a new command based on the specified operation and adds it to the chain of commands held by this builder.
Command<?>	build() Builds the composite command and returns it.
CommandBuilder	join(Command<?> command) Adds the specified command to the chain of commands held by this builder.
CommandBuilder	reset() Resets this command builder to its initial state.
String	toString() Returns a string representation of the composite command that would be returned by build().

Methods inherited from interface org.unix4j.builder.To

toDevNull, toExitValue, toFile, toFile, toLineList, toOutput, toOutputStream, toStdOut, toStringList, toStringResult, toWriter

Method Detail

join

CommandBuilder join(Command<?> command)

Adds the specified command to the chain of commands held by this builder. Application code rarely needs to call this method directly; the command specific methods are usually called instead to join an instance of a certain command, e.g. one of the grep(..) methods to join a grep command.

If this is the fist joined command, the builder builds this command and returns or executes it if build() or toXXX(..) is called, respectively. If the command argument joins already existing commands, the last command in the chain redirects its output to the standard input of the specified command.

Parameters:

command - the command to join the last previously joined command

Returns:

the builder for chained method invocation to join other commands

Throws:

NullPointerException - if the command argument is null

apply

CommandBuilder apply(LineOperation operation)

Adds a new command based on the specified operation and adds it to the chain of commands held by this builder.

If this is the fist joined command, the builder builds the command created from the operation and returns or executes it if build() or toXXX(..) is called, respectively. If the command argument joins already existing commands, the last command in the chain redirects its output to the standard input of the specified command.

Parameters:

operation - the operation on which the added command is based

Returns:

the builder for chained method invocation to join other commands

Throws:

NullPointerException - if the operation argument is null

reset

CommandBuilder reset()

Resets this command builder to its initial state. All joined commands are removed from the command chain leaving the builder in a state to build a NoOp command. New commands can be joined subsequently to create a new command chain.

Returns:

the builder for chained method invocation for instance to join the first new command

build

Command<?> build()

Builds the composite command and returns it. The returned command contains a join of all the commands that have been joined up by invoking command specific methods of this builder.

This method is rarely used by application code. Usually one of the toXXX(..) methods is invoked to execute the command and return the output directly. To get a string representation of the built command, the command's toString() method can be used.

Returns:

a newly created composite command based on the commands joined up by invoking command specific methods of this builder

toString

String toString()

Returns a string representation of the composite command that would be returned by build(). A composite command string looks for instance like this:

 "echo -messages [Hello WORLD] | grep -matchString world -ignoreCase"
 

Use To.toStringResult() instead to execute the command and return the output as a string.

Overrides:

toString in class Object

Returns:

the composite command string with joined commands including arguments and options