001package org.unix4j.builder;
002
003import java.io.File;
004import java.io.OutputStream;
005import java.io.Writer;
006import java.util.List;
007
008import org.unix4j.command.Command;
009import org.unix4j.command.ExitValueException;
010import org.unix4j.io.Output;
011import org.unix4j.line.Line;
012
013/**
014 * Interface defining command execution and output redirection methods.
015 */
016public interface To {
017        /**
018         * Executes the composite command and writes the result to the standard
019         * output.
020         */
021        void toStdOut();
022
023        /**
024         * Executes the composite command and returns the result as string. Line
025         * ending characters are inserted between lines if the result contains
026         * multiple lines. Note that the last line is NOT terminated with a line
027         * ending.
028         * <p>
029         * To return a representation of the command with its arguments without
030         * executing the command, {@link Command#toString() toString()} can be used
031         * instead.
032         * 
033         * @return the result as a string, possibly a multiline string with newline
034         *         characters between the lines but not after the last line
035         */
036        String toStringResult();
037
038        /**
039         * Executes the composite command and returns the result as a list
040         * containing the output lines.
041         * 
042         * @return the result as a list of line strings
043         */
044        List<Line> toLineList();
045
046        /**
047         * Executes the composite command and returns the result as a list
048         * containing the output lines without line ending.
049         * 
050         * @return the result as a list of line strings
051         */
052        List<String> toStringList();
053
054        /**
055         * Executes the composite command and writes the result to the given file.
056         * 
057         * @param file
058         *            the target output file
059         */
060        void toFile(String file);
061
062        /**
063         * Executes the composite command and does not write the result anywhere.
064         */
065        void toDevNull();
066
067        /**
068         * Executes the composite command and writes the result to the given file.
069         * 
070         * @param file
071         *            the target output file
072         */
073        void toFile(File file);
074
075        /**
076         * Executes the composite command and writes the result to the given stream.
077         * 
078         * @param stream
079         *            the target output stream
080         */
081        void toOutputStream(OutputStream stream);
082
083        /**
084         * Executes the composite command and writes the result using the given
085         * writer.
086         * 
087         * @param writer
088         *            the writer used to write the output
089         */
090        void toWriter(Writer writer);
091
092        /**
093         * Executes the composite command and writes the result to the given output.
094         */
095        void toOutput(Output output);
096        
097        /**
098         * Executes the composite command returns its exit value, 0 if the command
099         * completes successfully and another command specific error value different
100         * from zero if the command throws an {@link ExitValueException}.
101         * 
102         * @return the exit value returned by the command, 0 for success
103         */
104        int toExitValue();
105
106}