001package Torello.Java;
002
003import java.io.File;
004import java.util.Map;
005import java.util.function.Consumer;
006
007/**
008 * This class allows for the user to provide redirects, environment variables, and output/error
009 * unification (meaning the Standard-Output and Error-Output Streams are printed together, as if
010 * they were being printed to the terminal).
011 * 
012 * <EMBED CLASS='external-html' DATA-FILE-ID=OSEXTRAS>
013 */
014@SuppressWarnings("overrides") // The 'equals(other) causes a warning about hashCode
015public class OSExtras implements Cloneable
016{
017    /** <EMBED CLASS='external-html' DATA-FILE-ID=OSE_CUR_WDIR> */
018    public File currentWorkingDirectory = null;
019
020    /** <EMBED CLASS='external-html' DATA-FILE-ID=OSE_MERGE_IE> */
021    public boolean mergeStdErrorAndStdOut = false;
022
023    /** <EMBED CLASS='external-html' DATA-FILE-ID=OSE_OUT_REDIR> */
024    public ProcessBuilder.Redirect outputRedirect = null;
025
026    /** <EMBED CLASS='external-html' DATA-FILE-ID=OSE_INP_REDIR> */
027    public ProcessBuilder.Redirect inputRedirect = null;
028
029    /** <EMBED CLASS='external-html' DATA-FILE-ID=OSE_ERR_REDIR> */
030    public ProcessBuilder.Redirect errorRedirect = null;
031
032    /** <EMBED CLASS='external-html' DATA-FILE-ID=OSE_ENV_UPDT> */
033    public Consumer<Map<String, String>> environmentVariableUpdater = null;
034
035    /** Builds a new instance of this class, and keeps the default values assigned. */
036    public OSExtras() { }
037
038    /**
039     * Constructs an instance of this class
040     * @param currentWorkingDirectory <EMBED CLASS='external-html' DATA-FILE-ID=OSE_CUR_WDIR>
041     * @param mergeStdErrorAndStdOut <EMBED CLASS='external-html' DATA-FILE-ID=OSE_MERGE_IE>
042     * @param outputRedirect <EMBED CLASS='external-html' DATA-FILE-ID=OSE_OUT_REDIR>
043     * @param inputRedirect <EMBED CLASS='external-html' DATA-FILE-ID=OSE_INP_REDIR>
044     * @param errorRedirect <EMBED CLASS='external-html' DATA-FILE-ID=OSE_ERR_REDIR>
045     * @param environmentVariableUpdater <EMBED CLASS='external-html' DATA-FILE-ID=OSE_ENV_UPDT>
046     */
047    public OSExtras(
048           File                            currentWorkingDirectory,
049           boolean                         mergeStdErrorAndStdOut,
050           ProcessBuilder.Redirect         outputRedirect,
051           ProcessBuilder.Redirect         inputRedirect,
052           ProcessBuilder.Redirect         errorRedirect,
053           Consumer<Map<String, String>>   environmentVariableUpdater
054        )
055    {
056        this.currentWorkingDirectory    = currentWorkingDirectory;
057        this.mergeStdErrorAndStdOut     = mergeStdErrorAndStdOut;
058        this.outputRedirect             = outputRedirect;
059        this.inputRedirect              = inputRedirect;
060        this.errorRedirect              = errorRedirect;
061        this.environmentVariableUpdater = environmentVariableUpdater;
062    }
063
064
065    // ********************************************************************************************
066    // ********************************************************************************************
067    // Object & Cloneable Methods
068    // ********************************************************************************************
069    // ********************************************************************************************
070
071
072    private static String toStrApp(Object a)
073    { return (a == null) ? "null\n" : (a.getClass().getName() + '\n'); }
074
075    /**
076     * Generates a {@code String} this class.  The returned {@code String} merely encodes the
077     * class-names of the non-null fields.
078     *     
079     * @return A simple representation of this class, as a {@code java.lang.String}
080     */
081    public String toString()
082    {
083        // private static String toStrApp(Appendable a)
084        // { return (a == null) ? "null\n" : (a.getClass().getName() + '\n'); }
085
086        return
087            "currentWorkingDirectory:    " + toStrApp(this.currentWorkingDirectory) +
088            "mergeStdErrorAndStdOut:     " + this.mergeStdErrorAndStdOut + '\n' +
089            "outputRedirect:             " + toStrApp(this.outputRedirect) +
090            "inputRedirect:              " + toStrApp(this.inputRedirect) +
091            "errorRedirect:              " + toStrApp(this.errorRedirect) +
092            "environmentVariableUpdater: " + toStrApp(this.environmentVariableUpdater);
093    }
094
095    /**
096     * Checks for equality based on whether two instances have identical references.
097     *
098     * @param other Any Java Object.  Only a valid sub-class of {@code OSExtras} could possibly
099     * produce a {@code TRUE} return value
100     *
101     * @return {@code TRUE} if and only if each of the {@code OSExtras} fields are <I>identical
102     * references in both {@code 'this'} and {@code 'other'}</I>.
103     */
104    public boolean equals(Object other)
105    {
106        if (other == null) return false;
107
108        if (! OSExtras.class.isAssignableFrom(other.getClass())) return false;
109
110        OSExtras o = (OSExtras) other;
111
112        return 
113                (this.currentWorkingDirectory       == o.currentWorkingDirectory)
114            &&  (this.mergeStdErrorAndStdOut        == o.mergeStdErrorAndStdOut)
115            &&  (this.outputRedirect                == o.outputRedirect)
116            &&  (this.inputRedirect                 == o.inputRedirect)
117            &&  (this.errorRedirect                 == o.errorRedirect)
118            &&  (this.environmentVariableUpdater    == o.environmentVariableUpdater);
119    }
120
121    /**
122     * Makes a copy of {@code 'this'} instance and returns it.
123     * @return a clone of {@code 'this'} instance
124     */
125    public OSExtras clone()
126    {
127        return new OSExtras(
128            this.currentWorkingDirectory,
129            this.mergeStdErrorAndStdOut,
130            this.outputRedirect,
131            this.inputRedirect,
132            this.errorRedirect,
133            this.environmentVariableUpdater
134        );
135    }
136}