Package Torello.Java

Class OSExtras

  • All Implemented Interfaces:
    java.lang.Cloneable
    public class OSExtras
extends java.lang.Object
implements java.lang.Cloneable
    This class allows for the user to provide redirects, environment variables, and output/error unification (meaning the Standard-Output and Error-Output Streams are printed together, as if they were being printed to the terminal).

    File Redirects:
    This class can handle redirected input or output from files located on the file-system. As long as a instance-object of Java class java.io.File can be created, then input or output to any UNIX Operating-System process may be redirected to or from that file using the methods in this class.

    Other Pipes:
    In the days of yore, a UNIX programmer would often find himself piping the input of one command into the output of another. Here, if the input or output of a method is not going to be an, actual, physical file located on disk (the file-system), then the method's in this class will not be of any help. The reality is that since this method is largely a wrapper around Java's java.lang.ProcessBuilder class, the amount of complexity increases so dramatically trying to 'wrap' a Java A.P.I. that already works just fine (so I didn't write it).

    Below is an example that uses this class 'TAR' function to create an archive of all '.java' files in the NodeSearch package of this jar-library's source-file directory. Please note, at the UNIX command terminal, a simple wild-card expression would suffice, but when invoking a shell command from Java, the wild-card expression(s) would not be expanded - that is unless code as seen in the example below is used.

    Example using TAR:
    NOTE: The value of using the Shell.XL version of UNIX TAR command (over the standard Shell.TAR(...)) is that the current working directory in which this script is executed may be changed. This means that the when the script runs, the files that are included in the output .tar will not have all of the annoying parent-directory string's prepended to their file-names in the .tar that's created.

    Example:
    import Torello.Java.*;
import static Torello.Java.FileNode.RetTypeChoice.*;

import java.util.stream.*;

import java.io.IOException;
import java.io.File;
import java.lang.ProcessBuilder.Redirect;

public class t
{
    public static void main(String[] argv) throws IOException
    {
        // Build a new instance of Shell.XL
        Shell shell = new Shell.XL(System.out, System.err);

        // This uses the 'FileNode' class to retrieve all '.java' source-files that are
        // found in the 'searchLoops/' sub-directory.

        Stream<String> fileNames = FileNode
            .createRoot("Torello/HTML/NodeSearch/")
            .loadTree()
            .pollDir("searchLoops")
            .flattenJustFiles(FULLPATH_STREAM, -1, (FileNode fn) -> fn.name.endsWith(".java"));

        // These are the rest of the parameters for the UNIX 'tar' (file-archive) command
        Stream<String> command = Stream.of("-cvf", "MySourceFiles.tar");

        // Concat the Streams, here, for readability
        String[] args = Stream.concat(command, fileNames).toArray(String[]::new);

        // Creates a '.tar' of all java source files that were found.
        //
        // NOTE: The value of using the "OSExtras" is that the root working directory is set to
        //       "Torello/HTML/NodeSearch" - which means that none of the parent-directories will be
        //       prepended to the files in the '.tar' that is generated!

        OSExtras osExtras = new OSExtras();

        osExtras.currentWorkingDirectory = new File("Torello/HTML/NodeSearch/");
        shell.odExtras = osExtras;

        shell.TAR(args);
    }
}

    The above code prints the following output to a file named 'out.txt'. Note that for brevity, the text printed to terminal is not included in this sample output text. Below is merely the text left in the output file 'out.txt' Also, the 'tar' command, itself, will leave a tar-file named 'MySourceFiles.tar' in the NodeSearch directory.

    UNIX or DOS Shell Command:
    $ cat out.txt searchLoops/TNRemove.java searchLoops/ITFind.java searchLoops/CmtNPoll.java searchLoops/ITGetIncl.java searchLoops/ITFindIncl.java searchLoops/TNFindL1Incl.java searchLoops/TNGetL1Incl.java searchLoops/TNPeekL1Incl.java searchLoops/ITGet.java searchLoops/TxNPeek.java searchLoops/TNPeek.java searchLoops/TxNGet.java searchLoops/TNCount.java searchLoops/TNPoll.java searchLoops/TNGetIncl.java searchLoops/TNFindIncl.java searchLoops/CmtNFind.java searchLoops/TxNFind.java searchLoops/TNFind.java searchLoops/TxNCount.java searchLoops/TNGet.java searchLoops/TNRemoveIncl.java searchLoops/ITPeek.java searchLoops/ITCount.java searchLoops/TNPeekIncl.java searchLoops/ITPeekIncl.java searchLoops/TxNPoll.java searchLoops/ITPollIncl.java searchLoops/TNPollIncl.java searchLoops/ITRemoveIncl.java searchLoops/TxNRemove.java searchLoops/CmtNRemove.java searchLoops/CmtNGet.java searchLoops/CmtNCount.java searchLoops/ITPoll.java searchLoops/CmtNPeek.java searchLoops/ITRemove.java


    • Constructor Summary

      Constructors 
      Constructor Description
      OSExtras()
      Builds a new instance of this class, and keeps the default values assigned.
      OSExtras​(File currentWorkingDirectory, boolean mergeStdErrorAndStdOut, ProcessBuilder.Redirect outputRedirect, ProcessBuilder.Redirect inputRedirect, ProcessBuilder.Redirect errorRedirect, Consumer<Map<String,​String>> environmentVariableUpdater)
      Constructs an instance of this class

    • Method Summary

       
      Methods: interface java.lang.Cloneable
      Modifier and Type Method
      OSExtras clone()
       
      Methods: class java.lang.Object
      Modifier and Type Method
      boolean equals​(Object other)
      String toString()

      • Methods inherited from class java.lang.Object

        finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

    • Field Detail

      • currentWorkingDirectory

        🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public java.io.File currentWorkingDirectory
        This UNIX Shell command will be run with 'currentWorkingDirectory' set as the directory from whence this command is initiated. null may be passed to this parameter. If it is, it will be ignored, and the process will be run in the whatever directory the O/S has asserted is the current working directory.

      • mergeStdErrorAndStdOut

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public boolean mergeStdErrorAndStdOut
        If this boolean is TRUE, both Standard Output and Error Output will be merged into a single stream of text. This can be helpful since error messages are usually printed adjacent-to or immediately-after relevant text from the standard output stream.

        NOTE: The value of this boolean supersedes any redirect reference passed to parameter outputRedirect. When TRUE is passed here, the error stream will be empty, and the error redirect file or pipe will also remain empty. (And vice-versa, when FALSE, Standard Output and Error Output are printed to independent output streams, and both heed the redirect parameters).

      • outputRedirect

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public java.lang.ProcessBuilder.Redirect outputRedirect
        Read the Java-Doc information for Java class java.lang.ProcessBuilder.Redirect to learn how to redirect this Process' STANDARD OUTPUT to a file on the file-system. null may be passed to this parameter. If it is, it will be ignored.

      • inputRedirect

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public java.lang.ProcessBuilder.Redirect inputRedirect
        Read the Java-Doc information for Java class java.lang.ProcessBuilder.Redirect to learn how to redirect file-system files as INPUT to this Process. This parameter may receive 'null'.

      • errorRedirect

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public java.lang.ProcessBuilder.Redirect errorRedirect
        Read the Java-Doc information for Java class java.lang.ProcessBuilder.Redirect to learn how to redirect this Process' ERROR OUTPUT to a file on the file-system. null may be passed to this parameter. If it is, it will be ignored.

      • environmentVariableUpdater

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public java.util.function.Consumer<java.util.Map<java.lang.String,​java.lang.String>> environmentVariableUpdater
        This java.util.function.Consumer shall recieve a java.util.Map<String, String> containing all relevant environment variables, and their values. It may be modified to suit the purposes of this UNIX command. Any implementing class, or a lambda expression, is acceptable here. null may be passed to this parameter. If it is, it will be ignored - and no environment-variable modifications shall occur.

    • Constructor Detail

      • OSExtras

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public OSExtras​
            (java.io.File currentWorkingDirectory,
             boolean mergeStdErrorAndStdOut,
             java.lang.ProcessBuilder.Redirect outputRedirect,
             java.lang.ProcessBuilder.Redirect inputRedirect,
             java.lang.ProcessBuilder.Redirect errorRedirect,
             java.util.function.Consumer<java.util.Map<java.lang.String,​java.lang.String>> environmentVariableUpdater)
        Constructs an instance of this class
        Parameters:
        currentWorkingDirectory - This UNIX Shell command will be run with 'currentWorkingDirectory' set as the directory from whence this command is initiated. null may be passed to this parameter. If it is, it will be ignored, and the process will be run in the whatever directory the O/S has asserted is the current working directory.
        mergeStdErrorAndStdOut - If this boolean is TRUE, both Standard Output and Error Output will be merged into a single stream of text. This can be helpful since error messages are usually printed adjacent-to or immediately-after relevant text from the standard output stream.

        NOTE: The value of this boolean supersedes any redirect reference passed to parameter outputRedirect. When TRUE is passed here, the error stream will be empty, and the error redirect file or pipe will also remain empty. (And vice-versa, when FALSE, Standard Output and Error Output are printed to independent output streams, and both heed the redirect parameters).
        outputRedirect - Read the Java-Doc information for Java class java.lang.ProcessBuilder.Redirect to learn how to redirect this Process' STANDARD OUTPUT to a file on the file-system. null may be passed to this parameter. If it is, it will be ignored.
        inputRedirect - Read the Java-Doc information for Java class java.lang.ProcessBuilder.Redirect to learn how to redirect file-system files as INPUT to this Process. This parameter may receive 'null'.
        errorRedirect - Read the Java-Doc information for Java class java.lang.ProcessBuilder.Redirect to learn how to redirect this Process' ERROR OUTPUT to a file on the file-system. null may be passed to this parameter. If it is, it will be ignored.
        environmentVariableUpdater - This java.util.function.Consumer shall recieve a java.util.Map<String, String> containing all relevant environment variables, and their values. It may be modified to suit the purposes of this UNIX command. Any implementing class, or a lambda expression, is acceptable here. null may be passed to this parameter. If it is, it will be ignored - and no environment-variable modifications shall occur.
        Code:
        Exact Constructor Body:
         this.currentWorkingDirectory    = currentWorkingDirectory;
 this.mergeStdErrorAndStdOut     = mergeStdErrorAndStdOut;
 this.outputRedirect             = outputRedirect;
 this.inputRedirect              = inputRedirect;
 this.errorRedirect              = errorRedirect;
 this.environmentVariableUpdater = environmentVariableUpdater;

    • Method Detail

      • toString

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public java.lang.String toString()
        Generates a String this class. The returned String merely encodes the class-names of the non-null fields.
        Overrides:
        toString in class java.lang.Object
        Returns:
        A simple representation of this class, as a java.lang.String
        Code:
        Exact Method Body:
         // private static String toStrApp(Appendable a)
 // { return (a == null) ? "null\n" : (a.getClass().getName() + '\n'); }

 return
     "currentWorkingDirectory:    " + toStrApp(this.currentWorkingDirectory) +
     "mergeStdErrorAndStdOut:     " + this.mergeStdErrorAndStdOut + '\n' +
     "outputRedirect:             " + toStrApp(this.outputRedirect) +
     "inputRedirect:              " + toStrApp(this.inputRedirect) +
     "errorRedirect:              " + toStrApp(this.errorRedirect) +
     "environmentVariableUpdater: " + toStrApp(this.environmentVariableUpdater);

      • equals

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public boolean equals​(java.lang.Object other)
        Checks for equality based on whether two instances have identical references.
        Overrides:
        equals in class java.lang.Object
        Parameters:
        other - Any Java Object. Only a valid sub-class of OSExtras could possibly produce a TRUE return value
        Returns:
        TRUE if and only if each of the OSExtras fields are identical references in both 'this' and 'other'.
        Code:
        Exact Method Body:
         if (other == null) return false;

 if (! OSExtras.class.isAssignableFrom(other.getClass())) return false;

 OSExtras o = (OSExtras) other;

 return 
         (this.currentWorkingDirectory       == o.currentWorkingDirectory)
     &&  (this.mergeStdErrorAndStdOut        == o.mergeStdErrorAndStdOut)
     &&  (this.outputRedirect                == o.outputRedirect)
     &&  (this.inputRedirect                 == o.inputRedirect)
     &&  (this.errorRedirect                 == o.errorRedirect)
     &&  (this.environmentVariableUpdater    == o.environmentVariableUpdater);

      • clone

        🡅  ⇈  ⮫ 🗕  🗗  🗖 
        public OSExtras clone()
        Makes a copy of 'this' instance and returns it.
        Overrides:
        clone in class java.lang.Object
        Returns:
        a clone of 'this' instance
        Code:
        Exact Method Body:
         return new OSExtras(
     this.currentWorkingDirectory,
     this.mergeStdErrorAndStdOut,
     this.outputRedirect,
     this.inputRedirect,
     this.errorRedirect,
     this.environmentVariableUpdater
 );