001package org.unix4j.processor;
002
003import org.unix4j.io.Input;
004import org.unix4j.line.Line;
005
006/**
007 * An {@code InputProcessor} is used by a {@link MultipleInputLineProcessor} to
008 * process line based data from multiple {@link Input} devices. It is very
009 * similar to a {@link LineProcessor} but has an extra
010 * {@link #begin(Input, LineProcessor) begin(..)} method and input and output is
011 * passed to every method.
012 */
013public interface InputProcessor {
014        /**
015         * Indicates that the line processing task is about to start for the
016         * specified {@code input} device.
017         * 
018         * @param input
019         *            the input device whose lines are about to be processed next
020         * @param output
021         *            the output to write to
022         */
023        void begin(Input input, LineProcessor output);
024
025        /**
026         * Processes a single line and returns true if this {@code InputProcessor}
027         * is ready to process more lines. Returning false indicates that the
028         * process can be {@link #finish(Input, LineProcessor) finished} because
029         * subsequent lines would not change the result anyway.
030         * 
031         * @param input
032         *            the input device, the source of the given {@code line}
033         * @param line
034         *            the line to process
035         * @param output
036         *            the output to write to
037         * @return true if this {@code InputProcessor} is ready to process more
038         *         lines, and false if it does not require any more input lines
039         */
040        boolean processLine(Input input, Line line, LineProcessor output);
041
042        /**
043         * Indicates that this line processing task is complete for the specified
044         * {@code input} device and can finished.
045         * <p>
046         * Simple output devices usually perform a {@code flush} operation in this
047         * method. More complex commands may perform the real operation in this
048         * method, for instance write the total count of lines or words to the
049         * target file or stream.
050         * 
051         * @param input
052         *            the input device whose lines have now all been processed
053         * @param output
054         *            the output to write to
055         */
056        void finish(Input input, LineProcessor output);
057}