001package org.unix4j.io;
002
003import org.unix4j.line.Line;
004
005/**
006 * Output device writing to {@code /dev/null}, which means that all lines
007 * written to this device are ignored.
008 * <p>
009 * Two instances are available, the {@link #ABORT} instance which returns false
010 * when {@link #processLine(Line)} which usually causes the program execution to
011 * abort. The {@link #DEFAULT} instance does not abort program execution to make
012 * sure that no side effects are suppressed.
013 */
014public class NullOutput implements Output {
015
016        /**
017         * Default instance returning true when {@link #processLine(Line)} is
018         * called. This ensures that a command does not abort early and it is
019         * guaranteed that no (possibly important) side effects are missed.
020         */
021        public static final NullOutput DEFAULT = new NullOutput(false);
022        /**
023         * Aborting instance returning false when {@link #processLine(Line)} is
024         * called. Note that most commands will abort their execution early with
025         * this output device and some (possibly important) side effects could be
026         * missed.
027         */
028        public static final NullOutput ABORT = new NullOutput(true);
029
030        private final boolean processLines;
031
032        /**
033         * NOTE: application code should normally use the {@link #DEFAULT} or
034         * {@link #ABORT} constants instead of this constructor.
035         * <p>
036         * The {@code abort} flag passed to this constructor indicates whether the
037         * process can be aborted early or not; {@code abort=true} means that the
038         * method {@link #processLine(Line)} returns false indicating that this
039         * device does not expect any more input lines. Most commands will abort
040         * their execution early in this case, which means that (possibly important)
041         * side effects are missed.
042         * 
043         * @param abort
044         *            a flag indicating whether command execution can be aborted
045         *            early
046         */
047        public NullOutput(boolean abort) {
048                this.processLines = !abort;
049        }
050
051        @Override
052        public boolean processLine(Line line) {
053                return processLines;
054        }
055
056        @Override
057        public void finish() {
058                // ignore
059        }
060
061        @Override
062        public String toString() {
063                return processLines ? "/dev/null" : "/dev/null(abort)";
064        }
065}