001/**
002 * Powerunit - A JDK1.8 test framework
003 * Copyright (C) 2014 Mathieu Boretti.
004 *
005 * This file is part of Powerunit
006 *
007 * Powerunit is free software: you can redistribute it and/or modify
008 * it under the terms of the GNU General Public License as published by
009 * the Free Software Foundation, either version 3 of the License, or
010 * (at your option) any later version.
011 *
012 * Powerunit is distributed in the hope that it will be useful,
013 * but WITHOUT ANY WARRANTY; without even the implied warranty of
014 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
015 * GNU General Public License for more details.
016 *
017 * You should have received a copy of the GNU General Public License
018 * along with Powerunit. If not, see <http://www.gnu.org/licenses/>.
019 */
020package ch.powerunit.rules;
021
022import java.io.PrintStream;
023
024import ch.powerunit.rules.impl.NullOutputStream;
025import ch.powerunit.rules.impl.SystemStreamRuleImpl;
026
027/**
028 * This is a test rule to change the system {@link java.lang.System#out out}/
029 * {@link java.lang.System#err err} stream.
030 * <p>
031 * This rule will replace the stream with the passed one ; In case it is not
032 * possible to change the stream (because of a
033 * {@link java.lang.SecurityException}) no change is done and the exception is
034 * ignored.
035 * 
036 * @author borettim
037 * @since 0.4.0
038 */
039public interface SystemStreamRule extends TestListenerRule {
040        /**
041         * Return the {@link java.lang.System#out system out} that was set before
042         * entering the rule.
043         * 
044         * @return the original {@link java.lang.System#out system out}.
045         */
046        PrintStream getRealSystemOut();
047
048        /**
049         * Return the {@link java.lang.System#err system err} that was set before
050         * entering the rule.
051         * 
052         * @return the original {@link java.lang.System#err system err}.
053         */
054        PrintStream getRealSystemErr();
055
056        /**
057         * Provide a test rule that suppress both {@link java.lang.System#err system
058         * err} and {@link java.lang.System#out system out}.
059         * 
060         * @see ch.powerunit.rules.SystemStreamRule The complete description of the
061         *      functionnality of the rule.
062         * 
063         * @return the test rule.
064         */
065        static SystemStreamRule disableBothStreams() {
066                return replaceBothStream(new PrintStream(new NullOutputStream()),
067                                new PrintStream(new NullOutputStream()));
068        }
069
070        /**
071         * Provide a test rule that replace both {@link java.lang.System#err system
072         * err} and {@link java.lang.System#out system out} with the provided one.
073         * 
074         * @param outReplacement
075         *            the replacement of the {@link java.lang.System#out system out}
076         *            stream.
077         * @param errRemplacement
078         *            the replacement of the {@link java.lang.System#err system err}
079         *            stream.
080         * 
081         * @see ch.powerunit.rules.SystemStreamRule The complete description of the
082         *      functionnality of the rule.
083         * 
084         * @return the test rule.
085         */
086        static SystemStreamRule replaceBothStream(PrintStream outReplacement,
087                        PrintStream errRemplacement) {
088                return new SystemStreamRuleImpl(outReplacement, errRemplacement);
089        }
090
091        /**
092         * Provide a test rule that suppress the {@link java.lang.System#out system
093         * out} stream.
094         * 
095         * @see ch.powerunit.rules.SystemStreamRule The complete description of the
096         *      functionnality of the rule.
097         * 
098         * @return the test rule.
099         */
100        static SystemStreamRule disableOutStream() {
101                return replaceOutStream(new PrintStream(new NullOutputStream()));
102        }
103
104        /**
105         * Provide a test rule that suppress the {@link java.lang.System#err system
106         * err} stream.
107         * 
108         * @see ch.powerunit.rules.SystemStreamRule The complete description of the
109         *      functionnality of the rule.
110         * 
111         * @return the test rule.
112         */
113        static SystemStreamRule disableErrStream() {
114                return replaceErrStream(new PrintStream(new NullOutputStream()));
115        }
116
117        /**
118         * Privde a test rule that replace the {@link java.lang.System#out system
119         * out} stream with the provided one
120         * 
121         * @param outReplacement
122         *            the replacement of the {@link java.lang.System#out system out}
123         *            stream.
124         * 
125         * @see ch.powerunit.rules.SystemStreamRule The complete description of the
126         *      functionnality of the rule.
127         * 
128         * @return the test rule.
129         */
130        static SystemStreamRule replaceOutStream(PrintStream outReplacement) {
131                return replaceBothStream(outReplacement, System.err);
132        }
133
134        /**
135         * Privde a test rule that replace the {@link java.lang.System#err system
136         * err} stream with the provided one
137         * 
138         * @param errReplacement
139         *            the replacement of the {@link java.lang.System#err system err}
140         *            stream.
141         * 
142         * @see ch.powerunit.rules.SystemStreamRule The complete description of the
143         *      functionnality of the rule.
144         * 
145         * @return the test rule.
146         */
147        static SystemStreamRule replaceErrStream(PrintStream errReplacement) {
148                return replaceBothStream(System.out, errReplacement);
149        }
150
151}