001package org.unix4j.builder;
002
003import org.unix4j.command.Command;
004import org.unix4j.command.NoOp;
005import org.unix4j.operation.LineOperation;
006
007/**
008 * A builder used to build a single command or a chain of joined commands. Every
009 * command other than the last command redirects its output to the standard
010 * input of the next command. The last command writes its output to the final
011 * output destination. Executing a command and returning the output in different
012 * formats is reflected by the {@code toXXX(..)} methods inherited from the
013 * pseudo {@link To} command.
014 */
015public interface CommandBuilder extends To {
016
017        /**
018         * Adds the specified command to the chain of commands held by this builder.
019         * Application code rarely needs to call this method directly; the command
020         * specific methods are usually called instead to join an instance of a
021         * certain command, e.g. one of the {@code grep(..)} methods to join a grep
022         * command.
023         * <p>
024         * If this is the fist joined command, the builder <i>builds</i> this
025         * command and returns or executes it if {@link #build()} or
026         * {@code toXXX(..)} is called, respectively. If the command argument joins
027         * already existing commands, the last command in the chain redirects its
028         * output to the standard input of the specified command.
029         * 
030         * @param command
031         *            the command to join the last previously joined command
032         * @return the builder for chained method invocation to join other commands
033         * @throws NullPointerException
034         *             if the command argument is null
035         */
036        CommandBuilder join(Command<?> command);
037        
038        /**
039         * Adds a new command based on the specified operation and adds it to the
040         * chain of commands held by this builder.
041         * <p>
042         * If this is the fist joined command, the builder <i>builds</i> the command
043         * created from the operation and returns or executes it if {@link #build()} 
044         * or {@code toXXX(..)} is called, respectively. If the command argument joins
045         * already existing commands, the last command in the chain redirects its
046         * output to the standard input of the specified command.
047         * 
048         * @param operation
049         *            the operation on which the added command is based
050         * @return the builder for chained method invocation to join other commands
051         * @throws NullPointerException
052         *             if the operation argument is null
053         */
054        CommandBuilder apply(LineOperation operation);
055
056        /**
057         * Resets this command builder to its initial state. All joined commands are
058         * removed from the command chain leaving the builder in a state to build a
059         * {@link NoOp} command. New commands can be {@link #join(Command) joined}
060         * subsequently to create a new command chain.
061         * 
062         * @return the builder for chained method invocation for instance to join
063         *         the first new command
064         */
065        CommandBuilder reset();
066
067        /**
068         * Builds the composite command and returns it. The returned command
069         * contains a join of all the commands that have been joined up by invoking
070         * command specific methods of this builder.
071         * <p>
072         * This method is rarely used by application code. Usually one of the
073         * toXXX(..) methods is invoked to execute the command and return the output
074         * directly. To get a string representation of the built command, the
075         * command's toString() method can be used.
076         * 
077         * @return a newly created composite command based on the commands joined up
078         *         by invoking command specific methods of this builder
079         */
080        Command<?> build();
081
082        /**
083         * Returns a string representation of the composite command that would be
084         * returned by {@link #build()}. A composite command string looks for
085         * instance like this:
086         * 
087         * <pre>
088         * &quot;echo -messages [Hello WORLD] | grep -matchString world -ignoreCase&quot;
089         * </pre>
090         * 
091         * <p>
092         * Use {@link #toStringResult()} instead to execute the command and return
093         * the output as a string.
094         * 
095         * @return the composite command string with joined commands including
096         *         arguments and options
097         */
098        @Override
099        String toString();
100}