001package Torello.Java;
002
003/**
004 * Class Operating-System Response does is used as a return record class for the Java HTML classes
005 * {@link Shell}, {@link GSUTIL} & {@link MSDOS}.
006 * 
007 * <EMBED CLASS='external-html' DATA-FILE-ID=OSRES>
008 */
009public class OSResponse implements java.io.Serializable
010{
011    // ********************************************************************************************
012    // ********************************************************************************************
013    // Fields
014    // ********************************************************************************************
015    // ********************************************************************************************
016
017
018    /** <EMBED CLASS='external-html' DATA-FILE-ID=SVUID> */
019    protected static final long serialVersionUID = 1;
020
021    /**
022     * This integer-value is used as a response code indicating that the process that was called
023     * was interrupted, not completed.  This should not be a common occurrence.
024     */
025    public static final int INTERRUPTED = Integer.MIN_VALUE;
026
027    /**
028     * This {@code public, final, int} field will hold the "response code" reported by the
029     * operating-system. The response-code is a number returned by the invocation of the
030     * command to the OS.  A value of {@code -1} usually signifies that the process 
031     * <I>terminated with errors</I>.  If this field contains a value of
032     * {@code Shell.INTERRUPTED}, it will mean that the process was interrupted.
033     */
034    public final int response;
035
036    /**
037     * This {@code public, final, String} field will contain a transcript of the 
038     * text-{@code character} data that the Operating-System process sent to
039     * {@code Standard-Output}.
040     */
041    public final String standardOutput;
042
043    /**
044     * This {@code public, final, String} field will contain a transcript of the 
045     * text-{@code character} data that the Operating-System process sent to
046     * {@code Standard-Error}.
047     */
048    public final String errorOutput;
049
050    /** Maintains a copy of the command (as a {@code String}) that produced this instance */
051    public final String commandStr;
052
053
054    // ********************************************************************************************
055    // ********************************************************************************************
056    // Constructor
057    // ********************************************************************************************
058    // ********************************************************************************************
059
060
061    /**
062     * Builds an instance of this short return class
063     * 
064     * @param commandStr The command which was issued that has produced this response, as a Java
065     * {@code String}
066     *
067     * @param response The integer returned by the O/S command invocation.
068     *
069     * @param standardOutput The text/character data (as a {@code String}) sent to
070     * {@code Standard-Output}.
071     *
072     * @param errorOutput The text/character data (as a {@code String}) sent to
073     * {@code Standard-Error}.
074     */
075    protected OSResponse
076        (String commandStr, int response, String standardOutput, String errorOutput)
077    {
078        this.commandStr     = commandStr;
079        this.response       = response;
080        this.standardOutput = standardOutput;
081        this.errorOutput    = errorOutput;
082    }
083
084
085    // ********************************************************************************************
086    // ********************************************************************************************
087    // java.lang.Object and java.lang.Cloneable 
088    // ********************************************************************************************
089    // ********************************************************************************************
090
091
092    /**
093     * Convert the information in this class into a {@code java.lang.String}
094     * 
095     * @return A Java {@code String} representation of this class, containing
096     * <I><B STYLE='color:red;'>abbreviated</B></I> output-data
097     */
098    public String toString()
099    {
100        String s1 = (this.standardOutput == null)
101            ? "null"
102            : ((this.standardOutput.length() == 0)
103                ? "[Zero-Length-String]"
104                : StrPrint.abbrevEndRDSF(this.standardOutput, 80, true));
105
106        String s2 = (this.errorOutput == null)
107            ? "null"
108            : ((this.errorOutput.length() == 0)
109                ? "[Zero-Length-String]"
110                : StrPrint.abbrevEndRDSF(this.errorOutput, 80, true));
111
112        return
113            "Command:         " + StrPrint.abbrevEndRDSF(commandStr, 80, true) + '\n' +
114            "Response:        " + response + '\n' +
115            "Standart-Output: " + s1 + '\n' +
116            "Error-Output:    " + s2;
117    }
118
119    /**
120     * Convert the information in this class into a {@code java.lang.String}
121     * 
122     * @return A Java {@code String} representation of this class, containing
123     * <I><B STYLE='color:red;'>complete</B></I> output-data
124     */
125    public String toStringComplete()
126    {
127        String s1 = (this.standardOutput == null)
128            ? "null"
129            : ((this.standardOutput.length() == 0)
130                ? "[Zero-Length-String]"
131                : StrIndent.indentAfter2ndLine(this.standardOutput, 4, true, true));
132
133        String s2 = (this.errorOutput == null)
134            ? "null"
135            : ((this.errorOutput.length() == 0)
136                ? "[Zero-Length-String]"
137                : StrIndent.indentAfter2ndLine(this.errorOutput, 4, true, true));
138
139        return
140            "Command:         " + commandStr + '\n' +
141            "Response:        " + response + '\n' +
142            "Standart-Output: " + s1 + '\n' +
143            "Error-Output:    " + s2;
144    }
145
146    /**
147     * Creates and returns a copy of this object.
148     * @return a clone of this instance.
149     */
150    public OSResponse clone()
151    {
152        return new OSResponse
153            (this.commandStr, this.response, this.standardOutput, this.errorOutput);
154    }
155
156    /**
157     * Returns a hash code for this instance.  The hashcode produced simply invokes the 
158     * {@code hashCode()} method on the command (as a {@code String}) that was issued to produce
159     * this instance
160     * 
161     * @return a hash code value for this object.
162     */
163    public int hashCode() { return commandStr.hashCode(); }
164
165    /**
166     * Checks whether {@code 'this'} is equal to another possible instance of {@code OSResponse},
167     * or a subclass of it.
168     * 
169     * @param other This may be any Java Object, but only an instance or subclass of this class
170     * could possibly have fields that would make an identical match to {@code 'this'} instance.
171     * 
172     * @return {@code TRUE} if and only if the contents of the fields inside {@code 'this'}
173     * instance are identical to the fields in {@code 'other'}
174     */
175    public boolean equals(Object other)
176    {
177        if (other == null) return false;
178
179        if (! OSResponse.class.isAssignableFrom(other.getClass())) return false;
180
181        OSResponse o = (OSResponse) other;
182
183        return
184                (this.response == o.response)
185            &&  (this.commandStr.equals(o.commandStr))
186            &&  (this.standardOutput.equals(o.standardOutput))
187            &&  (this.errorOutput.equals(o.errorOutput));
188    }
189}