Package Torello.Java

Class MSDOS

  • All Implemented Interfaces:
    java.lang.Cloneable
    public class MSDOS
extends OSCommands
implements java.lang.Cloneable
    This Class Extends OSCommands:
    Class OSCommands is the parent class for all classes which invoke Operating-System Processes using the Java-Standard java.lang.Process Object-Utility.

    OSCommands has several constructors inherited by this class which allow a user to configure this class for sending its output in any number of ways to Appendable instances / loggers of your choice. Read this class documentation about invoking a constructor using any number of log-configurations, for sending text-output to any neccessary destination.

    All Methods Return OSResponse:
    In addition to real-time process-output printing, this class will collect any all text sent to Standard-Output and Error-Output and save the String-data for return to the user. All Operating-System calls in this class (which are all invoked by these methods, below) will always return an instance of OSResponse.

    Class OSResponse also contains the field response, which signals what the OS-Process' return-value was. Operating-Systems, generally, return a '0' to indicate the process ran to completion without errors, and some other value to signal an error occurred.

    Class OSExtras has All Additional java.lang.Process Features:
    java.lang.Process allows a user to redirect output, and collect-input to and from any number of additional sources. There is copious documentation about OSExtras, explaining these features.

    To specialize an Operating-System call with an OSExtras instance, just call this class' setOSExtras(...) method, with any neccessary configurations.
    A great tool for invoking commands to an MS-DOS operating-system. Allows a straight-forward way to make simple command-line / operating-system calls to an Microsoft DOS terminal.

    WORA:
    In its inception, Java made the "Write Once, Run Anywhere" (WORA) pledge. The methods in this class are not in any way "Java-ized" versions of the Operating System Calls. Rather, they are just wrappers around java.lang.Process allowing a user to BOTH make Operating System calls easily AND to efficiently retrieve the generated text-output produced by the calls.

    The bulk-work of the classes in this JAR Library were written and tested in a UNIX environment. While everything in the HTML Package of Java HTML JAR is indeed, O/S Independent (adhering to 'WORA'), this class and all classes which extend OSCommands are highly O/S dependent. The methods in these classes are (for all intents and purposes) a set of hooks into native Operating System calls.

    This means that an invocation of these methods while running in the wrong Operating System will just return a bunch of error-output results and thrown exceptions.

    Synchronized Methods:
    The vast majority of the methods in class OSCommands are synchronized. Specifically, the methods are declared using the Java Key-Word synchronized (even though Java Doc doesn't output that particular word into its method declarations). This also means that all classes extending and inheriting OSCommands will all have Thread-Safe and synchronized methods.

    Whenever a command is issued to this class, execution control for the current thread will not proceed / continue until the external operating system process has finished What that does mean, is that if this class were used by two different threads inside of a multi-threaded application, only one thread would ever be allowed to use this class. If you have a program that needs more than one thread making O/S calls, simply construct a second instance of this class (one for each thread), and any 'locking problems' should be resolved.

    Wild Cards:
    The behavior of expanding an '*' or '?' is another somewhat Operating-System Dependent phenomenon. It may be the case that Wild-Cards are expanded by the Operating-System, before the call. In such scenarios, when Java makes a call to the O/S it must have expanded its Wild-Cards.
    See Also:
    OSCommands, OSResponse


    • Constructor Detail

      • MSDOS

        🡇  ⇈  ⮫ 
        public MSDOS()
        Default constructor for instances inheriting this class. This constructor assigns the default values to all of the output logging Appendable's. This constructor's "See Also" section has a link to each of the logging Appendable's provided by this class.

        Note that all of them are assigned 'null' - meaing their output will not be logged - except for the primary field this.appendable. This field is assigned System.out, meaning that all text output by a process will be sent to the terminal window.

        Description copied in entirety from: OSCommands()
        See Also:
        OSCommands()
        Code:
        Exact Constructor Body:
         super();

      • MSDOS

        🡅  🡇  ⇈  ⮫ 
        public MSDOS​(java.lang.Appendable appendable,
             boolean cmdOrCmdAndOutput,
             java.lang.Appendable printCmdAppendable)
        This constructor allows a user to assign the Appendable's: appendable & printCmdAppendable.

        The first collects all text-output generated by the processes and prints it using the Appendable's printing methods. This includes text generated for BOTH Standard-Output AND Error-Output. This text is collected in real time as it is output by the underlying process.

        The second Appendable merely accepts the requested command, itself, as an output String. This String is printed using the Appendable's append(...) methods.

        NOTE: Either of these Appendable's may be assigned null, and if they are, they are simply ignored. NullPointerException won't throw, and the output text will simply not be printed.

        Description copied in entirety from: OSCommands(Appendable, boolean, Appendable)
        Parameters:
        appendable - This parameter's reference is assigned directly to the OSCommands field: appendable. To clearly understand the use of this field, please review the documentation linked for that field. To summarize, the java.lang.Appendable that is synonymously named appendable simply collects all output text generated by a processes as it executes, and sends it to the reference's append(...) method. This text will include that sent to BOTH Standard-Output AND text sent to Error-Output. The text that is printed is transmitted in the order it is received from the reader-threads that read the underlying process' text-pipes.

        By default this parameter is assigned System.out. When this default value is used, it means that as the process executes, any and all text it prints is sent to the UNIX or MS-DOS Operating System Terminal Window.

        This field may be assigned null, and when so it is just ignored. Assigning null to appendable. will not produce a NullPointerException.
        cmdOrCmdAndOutput - This boolean is assigned to the OSCommands field named cmdOrCmdAndOutput.

        Please review the documentation for that field to understand clearly the use of this parameter.
        printCmdAppendable - This java.lang.Appendable allows for yet another output mechanism when executing operating system commands. The sole purpose of this Appendable is to print the process command, itself, as a Java String - exactly as it was issued to the operating system.

        This allows a type of "Monitor Log" to store all commands being issued to the Operating-System, without having to include the full-text output that those process calls have produced. The value passed to this parameter is assigned to the OSCommands field named printCmdAppendable.

        This parameter may be null, and if it is, no such output will be generated.
        See Also:
        OSCommands.appendable, OSCommands.cmdOrCmdAndOutput, OSCommands.printCmdAppendable, OSCommands(Appendable, boolean, Appendable)
        Code:
        Exact Constructor Body:
         super(appendable, cmdOrCmdAndOutput, printCmdAppendable);

      • MSDOS

        🡅  🡇  ⇈  ⮫ 
        public MSDOS​(java.lang.Appendable appendable,
             boolean cmdOrCmdAndOutput,
             java.lang.Appendable printCmdAppendable,
             java.lang.Appendable standardOutput,
             java.lang.Appendable errorOutput)
        Constructor that allows for assigning all four text-collecting Appendable's. Please review the documentation for each of these fields to understand better how these Appendable's may be used.

        NOTE: Any of these Appendable's may be assigned null, and if they are, they are simply ignored. NullPointerException won't throw, and the relevant output text that would normally be appended to it, will simply not be appended.

        Description copied in entirety from: OSCommands(Appendable, boolean, Appendable, Appendable, Appendable)
        Parameters:
        appendable - This parameter's reference is assigned directly to the OSCommands field: appendable. To clearly understand the use of this field, please review the documentation linked for that field. To summarize, the java.lang.Appendable that is synonymously named appendable simply collects all output text generated by a processes as it executes, and sends it to the reference's append(...) method. This text will include that sent to BOTH Standard-Output AND text sent to Error-Output. The text that is printed is transmitted in the order it is received from the reader-threads that read the underlying process' text-pipes.

        By default this parameter is assigned System.out. When this default value is used, it means that as the process executes, any and all text it prints is sent to the UNIX or MS-DOS Operating System Terminal Window.

        This field may be assigned null, and when so it is just ignored. Assigning null to appendable. will not produce a NullPointerException.
        cmdOrCmdAndOutput - This boolean is assigned to the OSCommands field named cmdOrCmdAndOutput.

        Please review the documentation for that field to understand clearly the use of this parameter.
        printCmdAppendable - This java.lang.Appendable allows for yet another output mechanism when executing operating system commands. The sole purpose of this Appendable is to print the process command, itself, as a Java String - exactly as it was issued to the operating system.

        This allows a type of "Monitor Log" to store all commands being issued to the Operating-System, without having to include the full-text output that those process calls have produced. The value passed to this parameter is assigned to the OSCommands field named printCmdAppendable.

        This parameter may be null, and if it is, no such output will be generated.
        standardOutput - This Appendable is assigned to the internal OSCommands field: standardOutput. This Appendabe, as the name hopefully implies, allows a user to collect any / all text sent by the process to Standard-Output.

        Please review the documentation for that field to better understand it's use. Also, keep in mind that null may be passed to this parameter, and if / when it is the corresponding Appendable field will simply be ignored during the process execution.
        errorOutput - This Appendable is assigned to the internal OSCommands field: errorOutput. This Appendabe, as the name hopefully implies, allows a user to collect any / all text sent by the process to Error-Output.

        Please review the documentation for that field to better understand it's use. Also, keep in mind that null may be passed to this parameter, and if / when it is the corresponding Appendable field will simply be ignored during the process execution.
        See Also:
        OSCommands.appendable, OSCommands.cmdOrCmdAndOutput, OSCommands.printCmdAppendable, OSCommands.standardOutput, OSCommands.errorOutput, OSCommands(Appendable, boolean, Appendable, Appendable, Appendable)
        Code:
        Exact Constructor Body:
         super(appendable, cmdOrCmdAndOutput, printCmdAppendable, standardOutput, errorOutput);

      • MSDOS

        🡅  🡇  ⇈  ⮫ 
        public MSDOS​(java.lang.Appendable standardOutput,
             java.lang.Appendable errorOutput)
        This constructor retains all default values for the internal fields of this class, except for the two OSCommands Appendable fields listed, namely: standardOutput and errorOutput

        Description copied in entirety from: OSCommands(Appendable, Appendable)
        Parameters:
        standardOutput - This Appendable is assigned to the internal OSCommands field: standardOutput. This Appendabe, as the name hopefully implies, allows a user to collect any / all text sent by the process to Standard-Output.

        Please review the documentation for that field to better understand it's use. Also, keep in mind that null may be passed to this parameter, and if / when it is the corresponding Appendable field will simply be ignored during the process execution.
        errorOutput - This Appendable is assigned to the internal OSCommands field: errorOutput. This Appendabe, as the name hopefully implies, allows a user to collect any / all text sent by the process to Error-Output.

        Please review the documentation for that field to better understand it's use. Also, keep in mind that null may be passed to this parameter, and if / when it is the corresponding Appendable field will simply be ignored during the process execution.
        See Also:
        OSCommands.standardOutput, OSCommands.errorOutput, OSCommands(Appendable, Appendable)
        Code:
        Exact Constructor Body:
         super(standardOutput, errorOutput);

    • Method Detail

      • clone

        🡅  🡇  ⇈  ⮫ 
        public MSDOS clone()
        Creates a clone of 'this' instance. Though unlikely of much use, this could conceivably have some function if similar, but non-identical, output mechanisms were being used.
        Specified by:
        clone in class OSCommands
        Returns:
        An exact copy of 'this' instance of MSDOS - one in which all output Appendable's have had their references copied into the new instance.
        Code:
        Exact Method Body:
         return new MSDOS(
     this.appendable, this.cmdOrCmdAndOutput, this.printCmdAppendable, this.standardOutput,
     this.errorOutput
 );

      • COPY

        🡅  🡇  ⇈  ⮫ 
        public OSResponse COPY​(java.lang.String src,
                       java.lang.String target)
                throws java.io.IOException
        MS-DOS Command: COPY

        UNIX or DOS Shell Command:
        C:\>COPY <src> <target>
        Parameters:
        src - MS-DOS 'COPY' command's "source" argument
        target - The 'COPY' command's "target" argument
        Returns:
        Returns an instance of OSResponse. This response-Object (data-record) class holds three public, final fields:
        ① Process response-code
        ② Text sent to Standard-Output (as a java.lang.String)
        ③ Text sent to Error-Output (also as a String)

        This OSResponse instance may be discarded without any effect on Process Execution. It is only provided as a convenience in case more information is required about the results of the O/S command invocation.

        Process Status: Upon completion of this method, the Operating-System java.lang.Process is guaranteed to have run to completion.
        Throws:
        java.io.IOException - If there are problems while invoking the operating-system command
        See Also:
        OSCommands.printAndRun(String[])
        Code:
        Exact Method Body:
         String[] command = { "COPY", src, target };

 return printAndRun(command);

      • COPY

        🡅  🡇  ⇈  ⮫ 
        public OSResponse COPY​(java.util.Vector<java.lang.String> src,
                       java.lang.String target)
                throws java.io.IOException
        MS-DOS Command: COPY

        UNIX or DOS Shell Command:
        C:\>COPY <src.elementAt(0)> <src.elementAt(1)> ... <src.elementAt(src.size()-1)> <target>
        Parameters:
        src - This may be a list of files to be copied to a target directory
        target - This is the target directory for the files listed.
        Returns:
        Returns an instance of OSResponse. This response-Object (data-record) class holds three public, final fields:
        ① Process response-code
        ② Text sent to Standard-Output (as a java.lang.String)
        ③ Text sent to Error-Output (also as a String)

        This OSResponse instance may be discarded without any effect on Process Execution. It is only provided as a convenience in case more information is required about the results of the O/S command invocation.

        Process Status: Upon completion of this method, the Operating-System java.lang.Process is guaranteed to have run to completion.
        Throws:
        java.io.IOException - If there are problems while invoking the operating-system command
        See Also:
        OSCommands.printAndRun(String[])
        Code:
        Exact Method Body:
         String[] command = new String[src.size() + 2];
 command[0] = "COPY";
 command[src.size() + 1] = target;

 for (int i=0; i < src.size(); i++) command[1 + i] = src.elementAt(i);

 return printAndRun(command);

      • COPY

        🡅  🡇  ⇈  ⮫ 
        public OSResponse COPY​(java.lang.String[] src,
                       java.lang.String target)
                throws java.io.IOException
        MS-DOS Command: COPY

        UNIX or DOS Shell Command:
        C:\>COPY <src[0]> <src[1]> ... <src[src.length-1]> <target>
        Parameters:
        src - This may be a list of files to be copied to a target directory
        target - This is the target directory for the files listed.
        Returns:
        Returns an instance of OSResponse. This response-Object (data-record) class holds three public, final fields:
        ① Process response-code
        ② Text sent to Standard-Output (as a java.lang.String)
        ③ Text sent to Error-Output (also as a String)

        This OSResponse instance may be discarded without any effect on Process Execution. It is only provided as a convenience in case more information is required about the results of the O/S command invocation.

        Process Status: Upon completion of this method, the Operating-System java.lang.Process is guaranteed to have run to completion.
        Throws:
        java.io.IOException - If there are problems while invoking the operating-system command
        See Also:
        OSCommands.printAndRun(String[])
        Code:
        Exact Method Body:
         String[] command = new String[src.length + 2];
 command[0] = "COPY";
 command[src.length + 1] = target;

 for (int i=0; i < src.length; i++) command[1 + i] = src[i];

 return printAndRun(command);

      • DEL

        🡅  🡇  ⇈  ⮫ 
        public OSResponse DEL​(java.lang.String s1)
               throws java.io.IOException
        MS-DOS Command: DEL

        UNIX or DOS Shell Command:
        C:\>DEL <s1>
        Parameters:
        s1 - The item to be removed, using an MS-DOS command.
        Returns:
        Returns an instance of OSResponse. This response-Object (data-record) class holds three public, final fields:
        ① Process response-code
        ② Text sent to Standard-Output (as a java.lang.String)
        ③ Text sent to Error-Output (also as a String)

        This OSResponse instance may be discarded without any effect on Process Execution. It is only provided as a convenience in case more information is required about the results of the O/S command invocation.

        Process Status: Upon completion of this method, the Operating-System java.lang.Process is guaranteed to have run to completion.
        Throws:
        java.io.IOException - If there are problems while invoking the operating-system command
        See Also:
        OSCommands.printAndRun(String[])
        Code:
        Exact Method Body:
         String[] command = { "DEL", s1 };

 return printAndRun(command);

      • DEL

        🡅  ⇈  ⮫ 
        public OSResponse DEL​(java.lang.String[] sArr)
               throws java.io.IOException
        MS-DOS Command: DEL

        UNIX or DOS Shell Command:
        C:\>DEL <sArr[0]> <sArr[1]> ... <sArr[sArr.length-1]>
        Parameters:
        sArr - An String[] array which is added to the end of this MS-DOS command. These will be the item(s) removed by the 'DEL' command.
        Returns:
        Returns an instance of OSResponse. This response-Object (data-record) class holds three public, final fields:
        ① Process response-code
        ② Text sent to Standard-Output (as a java.lang.String)
        ③ Text sent to Error-Output (also as a String)

        This OSResponse instance may be discarded without any effect on Process Execution. It is only provided as a convenience in case more information is required about the results of the O/S command invocation.

        Process Status: Upon completion of this method, the Operating-System java.lang.Process is guaranteed to have run to completion.
        Throws:
        java.io.IOException - If there are problems while invoking the operating-system command
        See Also:
        OSCommands.printAndRun(String[])
        Code:
        Exact Method Body:
         String[] command = new String[sArr.length + 1];
 command[0] = "DEL";

 for (int i=0; i < sArr.length; i++) command[i + 1] = sArr[i];

 return printAndRun(command);