001package org.unix4j.processor;
002
003import org.unix4j.line.Line;
004
005/**
006 * A {@code LineProcessor} is a program or device that processes line based
007 * data.
008 * <p>
009 * An simple example of a {@code LineProcessor} is an output device that writes
010 * the lines to a file; another more sophisticated {@code LineProcessor}
011 * performs algorithmic operations based on the line input, for instance a
012 * command that counts the lines and writes only the line count to the
013 * destination file or stream.
014 */
015public interface LineProcessor {
016        /**
017         * Processes a single line and returns true if this {@code LineProcessor} is
018         * ready to process more lines. Returning false indicates that the process
019         * can be {@link #finish() finished} because subsequent lines would not
020         * change the result anyway.
021         * 
022         * @param line
023         *            the line to process
024         * @return true if this {@code LineProcessor} is ready to process more
025         *         lines, and false if it does not require any more input lines
026         */
027        boolean processLine(Line line);
028
029        /**
030         * Indicates that this line processing task is complete and can finished.
031         * <p>
032         * Simple output devices usually perform a {@code flush} operation in this
033         * method. More complex commands may perform the real operation in this
034         * method, for instance write the total count of lines or words to the
035         * target file or stream.
036         */
037        void finish();
038}