package Torello.Java;

import Torello.Java.StrIndent;

import static Torello.Java.C.*;

import java.util.*;
import java.util.stream.Stream;
import java.io.*;
import java.util.zip.*;

import com.google.cloud.storage.*;
import com.google.auth.oauth2.*;

/**
 * <B><CODE>Load File Exception Catch</CODE></B> provides an eloquent way for printing standardized
 * <I>(consistent-looking)</I> error messages to terminal if a data-file fails to load from the
 * file-system, and subsequently halting the JVM - immediately.
 * 
 * <EMBED CLASS='external-html' DATA-FILE-ID=LFEC>
 */
@Torello.JavaDoc.StaticFunctional
public class LFEC
{
    private LFEC() { }


    // ********************************************************************************************
    // ********************************************************************************************
    // These are error-printing methods.
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * This prints a message and a location and halts the current thread immediately.  (Halts the
     * program)  The entire rational behind the {@code class LFEC} is to facilitate loading
     * data-files, and forcing an immediate program halt if this operation fails.  Generally,
     * during development and debugging, failing to read from a data-file is serious enough to
     * warrant stopping the software until the issue is fixed.  "Hobbling along without reading
     * the data-files" makes little sense.
     *
     * <BR /><BR />When the software is being released or distributed, the philosophy turns to
     * loading mission critical data out of data-files in a java jar-file.  If the jar-file is
     * corrupted and those files are not present, generally <I>this situation would <B>also
     * warrant</B> halting the program execution immediately until the jar file is fixed.</I>
     *
     * @param t An exception, error or other {@code Throwable} that generated a problem when
     * attempting to read a data-file.
     * 
     * @param message This is an internally generated message explaining what has occurred.
     */
    protected static void ERROR_EXIT(Throwable t, String message)
    {
        System.out.println(
            '\n' +
            "There was an error loading a data-file, and program-execution is being halted " +
            "immediately.\n" +
            "Problem Encountered With:\n" + StrIndent.indent(message, 4) + "\n" +
            "Exception or Error Message:\n" +
            EXCC.toString(t) + "\n\n" +
            "Exiting Program, Fatal Error Loading Critical Data File."
        );

        System.exit(1);
    }

    /**
     * This prints a message and a location and halts the current thread immediately.  (Halts the
     * program)  The entire rational behind the {@code class LFEC} is to facilitate loading
     * data-files, and forcing an immediate program halt if this operation fails.  Generally,
     * during development and debugging, failing to read from a data-file is serious enough to
     * warrant stopping the software until the issue is fixed.  "Hobbling along without reading
     * the data-files" makes little sense.
     *
     * <BR /><BR />When the software is being released or distributed, the philosophy turns to
     * loading mission critical data out of data-files in a java jar-file.  If the jar-file is
     * corrupted and those files are not present, generally <I>this situation would <B>also
     * warrant</B> halting the program execution immediately until the jar file is fixed.</I>
     *
     * @param message This is an internally generated message explaining what has occurred.
     */
    protected static void ERROR_EXIT(String message)
    {
        System.out.println(
            '\n' +
            "There was an error loading a data-file, and program-execution is being halted " +
            "immediately.\n" +
            "Problem Encountered With:\n" + message + "\n\n" +
            "Exiting Program, Fatal Error Loading Critical Data File."
        );

        System.exit(1);
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // These are the data-loading methods.
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Loads a file directly into a java-{@code String.}  If this file fails to load, it halts the
     * run-time environment.
     * 
     * @param f This is a {@code java.lang.String} that contains the filename.
     * 
     * @return The returned {@code String} contains the entire contents of the file.
     * 
     * @see FileRW#loadFileToString(String)
     * @see #ERROR_EXIT(Throwable, String)
     */
    public static String loadFile(String f)
    {
        try
            { return FileRW.loadFileToString(f); }

        catch (Throwable t)
            { ERROR_EXIT(t, "FileRW.loadFileToString(\"" + f + "\")");  }

        throw new UnreachableError(); // Should not be possible to reach this statement
    }

    /**
     * Loads a file directory to a string <I>from a java jar-file</I>.  It halts the program, and
     * prints a detailed message if any {@code Error's} or {@code Exception's} were thrown.  The
     * directory inside the jar-file where this file may be located identified by parameter
     * {@code class 'classLoaderClass'}.
     *
     * @param classLoaderClass <EMBED CLASS='external-html' DATA-FILE-ID=LFEC_CLASS_LOAD_C>
     * <EMBED CLASS='external-html' DATA-FILE-ID=RAWTYPES>
     *
     * @param f This is a {@code String} that contains the filename of the data-file that needs
     * to be loaded.  It is a 'relative file-name' that is relative to the jar-file / directory pair
     * location that the class loader identifies using the {@code Class} from parameter
     * {@code 'classLoaderClass'}
     *
     * @return The returned string contains the entire contents of the file.
     * 
     * @see #ERROR_EXIT(Throwable, String)
     */
    public static String loadFile_JAR(Class<?> classLoaderClass, String f)
    {
        // These are 'java.lang.AutoCloseable', and java handles them automatically
        // if there is an exception

        try (
            InputStream     is  = classLoaderClass.getResourceAsStream(f);
            BufferedReader  br  = new BufferedReader(new InputStreamReader(is));
        )
        {
            String          s   = "";
            StringBuffer    sb  = new StringBuffer();

            while ((s = br.readLine()) != null) sb.append(s + "\n");

            return sb.toString();
        }

        catch (Throwable t)
        {
            ERROR_EXIT(
                t,
                "Error loading text-file [" + f + "] from jar-file.\n" +
                "Class loader attempted to use information in class " +
                "[" + classLoaderClass.getCanonicalName() + "], but failed."
            );
        }

        throw new UnreachableError(); // Should NOT be possible to reach this statement...
    }

    /**
     * Loads a file <I>from a java jar-file</I> using an {@code InputStream} and copies that file,
     * byte-for-byte, to {@code 'targetFileName'}.  A detailed message is printed if any
     * {@code Error's} or {@code Exception's} were thrown.  The directory inside the jar-file
     * where this file may be located identified by parameter {@code class 'classLoaderClass'}.
     *
     * @param classLoaderClass <EMBED CLASS='external-html' DATA-FILE-ID=LFEC_CLASS_LOAD_C>
     * <EMBED CLASS='external-html' DATA-FILE-ID=RAWTYPES>
     *
     * @param fileName This is a {@code String} that contains the filename of the data-file that
     * needs to be copied.  It is a 'relative file-name' that is relative to the jar-file /
     * directory pair location that the class loader identifies using the {@code Class} from
     * parameter {@code 'classLoaderClass'}.
     * 
     * @param targetFileName This is the file and directory that contains the target location
     * (as a {@code String}) to where the file should be copied.
     * 
     * @see #ERROR_EXIT(Throwable, String)
     */
    public static void copyFile_JAR
        (Class<?> classLoaderClass, String fileName, String targetFileName)
    {
        // These are 'java.lang.AutoCloseable', and java handles them automatically
        // if there is an exception

        try (
            InputStream         is  = classLoaderClass.getResourceAsStream(fileName);
            FileOutputStream    fos = new FileOutputStream(targetFileName);
        )
        {
            byte[]  b       = new byte[5000];
            int     result  = 0;
    
            while ((result = is.read(b)) != -1) fos.write(b, 0, result);
        }

        catch (Throwable t)
        {
            ERROR_EXIT(
                t,
                "Error copying file [" + fileName + "] from jar-file to " +
                "[" + targetFileName + "].\n" +
                "Class loader attempted to use information in class " +
                "[" + classLoaderClass.getCanonicalName() + "]."
            );
        }
    }

    /**
     * This loads a file to a {@code Vector} of {@code String's}.  It halts the program, and prints
     * a detailed message if any errors or exceptions occur.
     *
     * @param f The name of the file to load
     *
     * @param includeNewLine States whether the {@code '\n'} (new-line) character should be appended
     * to each element of the returned {@code Vector<String>}.
     *
     * @return a {@code Vector} of {@code String's}, where each element in the {@code Vector} is a
     * line retrieved from the text-file.
     *
     * @see #ERROR_EXIT(Throwable, String)
     */
    public static Vector<String> loadFileToVector(String f, boolean includeNewLine)
    {
        try
            { return FileRW.loadFileToVector(f, includeNewLine); }

        catch (Throwable t)
        {
            ERROR_EXIT(
                t, 
                "Attempting to Invoke this Load-Method with these Arguments:\n" +
                "FileRW.loadFileToVector(\"" + f + "\", " + includeNewLine + ");"
            );
        }

        throw new UnreachableError(); // Should NOT be possible to reach this statement...
    }


    /**
     * This loads a file to a {@code Stream} of {@code String's}.  It halts the program, and prints
     * a detailed message if any errors or exceptions occur.
     *
     * @param f The name of the file to load
     *
     * @param includeNewLine States whether the {@code '\n'} (new-line) character should be appended
     * to each element of the returned {@code Vector<String>}.
     *
     * @return a {@code Stream} of {@code String's}, where each element in the {@code Stream} is a
     * line retrieved from the text-file.
     *
     * @see #ERROR_EXIT(Throwable, String)
     */
    public static Stream<String> loadFileToStream(String f, boolean includeNewLine)
    {
        try
            { return FileRW.loadFileToStream(f, includeNewLine); }

        catch (Throwable t)
        {
            ERROR_EXIT(
                t, 
                "Attempting to Invoke this Load-Method with these Arguments:\n" +
                "FileRW.loadFileToStream(\"" + f + "\", " + includeNewLine + ");"
            );
        }

        throw new UnreachableError(); // Should NOT be possible to reach this statement...
    }

    /**
     * This loads a file to a {@code Vector} of {@code String's}.  It halts the program, and prints
     * a detailed message if any {@code Error's} or {@code Exception's} occur.  The directory inside
     * the jar-file where this file may be located identified by parameter
     * {@code 'classLoaderClass'}.
     *
     * @param classLoaderClass <EMBED CLASS='external-html' DATA-FILE-ID=LFEC_CLASS_LOAD_C>
     * <EMBED CLASS='external-html' DATA-FILE-ID=RAWTYPES>
     *
     * @param f This is a {@code String} that contains the filename of the data-file that needs to
     * be loaded.  It is a 'relative file-name' that is relative to the jar-file / directory pair
     * location that the class loader identifies using the {@code Class} from parameter
     * {@code 'classLoaderClass'}.
     *
     * @param includeNewLine States whether the {@code '\n'} (newline) character should be appended
     * to each element of the {@code Vector}.
     *
     * @return a {@code Vector} of {@code String's}, where each element in the {@code Vector} is a
     * line retrieved from the text-file.
     *
     * @see #ERROR_EXIT(Throwable, String)
     */
    public static Vector<String> loadFileToVector_JAR
        (Class<?> classLoaderClass, String f, boolean includeNewLine)
    {
        // These are 'java.lang.AutoCloseable', and java handles them automatically
        // if there is an exception

        try (
            InputStream     is  = classLoaderClass.getResourceAsStream(f);
            BufferedReader  br  = new BufferedReader(new InputStreamReader(is));
        )
        {
            String          s   = "";
            Vector<String>  ret = new Vector<>();

            if (includeNewLine)
                while ((s = br.readLine()) != null)
                    ret.addElement(s + '\n');

            else
                while ((s = br.readLine()) != null)
                    ret.addElement(s);

            return ret;
        }

        catch (Throwable t)
        {
            ERROR_EXIT(
                t,
                "Error loading text-file [" + f + "] from jar-file.\n" +
                "Parameter includeNewLine was: " + includeNewLine + "\n" +
                "Class loader attempted to use information in class " +
                "[" + classLoaderClass.getCanonicalName() + "], but failed."
            );
        }

        throw new UnreachableError(); // Should NOT be possible to reach this statement...
    }

    /**
     * This loads a {@code java.lang.Object} from a data-file.
     * <EMBED CLASS='external-html' DATA-FILE-ID=LFEC_CONTAINER>
     *
     * @param f The name of the file containing a serialized {@code java.lang.Object} to load
     *
     * @param zip This should be <I>TRUE</I> if, when serialized, the {@code Object} was compressed
     * too, and <I>FALSE</I> if compression was not used.
     *
     * @param returnClass <EMBED CLASS='external-html' DATA-FILE-ID=LFEC_RET_CLASS>
     *
     * @param <T> This type parameter is simply provided for convenience, to allow the user to
     * specify the return class, without having to cast the object and suppress warnings, or catch
     * exceptions.
     *
     * @return A de-serialized {@code java.lang.Object} present in the data-file passed by-name
     * through file-name parameter {@code 'f'}, and cast to the type denoted by parameter
     * {@code returnClass}.
     *
     * @see FileRW#readObjectFromFile(String, boolean)
     * @see #ERROR_EXIT(Throwable, String)
     */
    public static <T> T readObjectFromFile(String f, boolean zip, Class<T> returnClass)
    {
        try
        {
            Object ret = FileRW.readObjectFromFile(f, zip);

            if (! returnClass.isInstance(ret))

                ERROR_EXIT(
                    "Serialized Object from file: " + f + "\n" +
                    "Using expected (" + (zip ? "zip-compression" : "no-compression") + ")\n" +
                    "Didn't have an object with class-name: [" + returnClass + "]\n" +
                    "but rather with class-name: [" + ret.getClass().getName() + "]"
                );

            return returnClass.cast(ret);
        }

        catch (Throwable t)
        {
            ERROR_EXIT(
                t,
                "Exception reading Serialized Object from file: " + f + "\n" +
                "With intended read class-name of: " + returnClass + "\n" +
                "Using expected (" + (zip ? "zip-compression" : "no-compression") + ")\n"
            );
        }

        throw new UnreachableError(); // Should NOT be possible to reach this statement...
    }

    /**
     * This loads a {@code java.lang.Object} from a data-file located in a JAR File.
     * <EMBED CLASS='external-html' DATA-FILE-ID=LFEC_CONTAINER>
     *
     * @param classLoaderClass <EMBED CLASS='external-html' DATA-FILE-ID=LFEC_CLASS_LOAD_C>
     * <EMBED CLASS='external-html' DATA-FILE-ID=RAWTYPES>
     *
     * @param f The name of the file containing a serialized {@code java.lang.Object} to load
     *
     * @param zip This should be <I>TRUE</I> if, when serialized, the {@code Object} was compressed
     * too, and <I>FALSE</I> if compression was not used.
     *
     * @param returnClass <EMBED CLASS='external-html' DATA-FILE-ID=LFEC_RET_CLASS> 
     *
     * @param <T> This type parameter is simply provided for convenience, to allow the user to
     * specify the return class, without having to cast the object and suppress warnings, or catch
     * exceptions.
     *
     * @return a de-serialized {@code java.lang.Object} present in the data-file passed by-name
     * through file-name parameter {@code 'f'}, and cast to the type denoted by parameter
     * {@code 'returnClass'}.
     *
     * @see #ERROR_EXIT(Throwable, String)
     */
    public static <T> T readObjectFromFile_JAR
        (Class<?> classLoaderClass, String f, boolean zip, Class<T> returnClass)
    {
        // These are 'java.lang.AutoCloseable', and java handles them automatically
        // if there is an exception

        try (
            InputStream is = classLoaderClass.getResourceAsStream(f);

            // The user may or may not have asked for reading a *COMPRESSED* file
            ObjectInputStream ois = zip
                ? new ObjectInputStream(new GZIPInputStream(is))
                : new ObjectInputStream(is);
        )
        {
            Object ret = ois.readObject();

            if (! returnClass.isInstance(ret)) ERROR_EXIT(
                "Serialized Object from jar-file loading-using class: " +
                classLoaderClass.getCanonicalName() + "\n" +
                "Looking for data-file named: " + f + "\n" +
                "Using expected (" + (zip ? "zip-compression" : "no-compression") + ")\n" +
                "Didn't have an object with class-name: [" + returnClass + "]\n" +
                "but rather with class-name: [" + ret.getClass().getName() + "]"
            );

            return returnClass.cast(ret);
        }

        catch (Throwable t)
        {
            ERROR_EXIT(
                t,
                "Exception reading Serialized Object from jar-file, loading-using class: " +
                classLoaderClass.getCanonicalName() + "\n" +
                "Looking for data-file named: " + f + "\n" +
                "And attempting to retrieve an object having class-name: " + returnClass + "\n" +
                "Using expected (" + (zip ? "zip-compression" : "no-compression") + ")\n"
            );

            throw new UnreachableError(); // Should NOT be possible to reach this statement...
        }
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // Google Cloud Server - Public Static Inner Class
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * The Google Cloud Server Storage Bucket extension of "Load File Exception Catch" does the
     * work that <CODE>LFEC</CODE> does, but for GCS Storage Buckets, rather than operating 
     * system files.
     * 
     * <EMBED CLASS='external-html' DATA-FILE-ID=LFEC_GCSSB>
     */
    @Torello.JavaDoc.StaticFunctional
    public static class GCSSB
    {
        private GCSSB() { }

        /**
         * This will read a Java Serialized {@code java.lang.Object} from a location in a Google
         * Cloud Server {@code Storage Bucket}.
         *
         * @param storage <EMBED CLASS='external-html' DATA-FILE-ID=GCSSB_STORAGE>
         *
         * @param bucket The {@code bucket} name of the {@code bucket} from a Google Cloud Server
         * account.
         *
         * @param completeFileName <EMBED CLASS='external-html' DATA-FILE-ID=GCSSB_CMPL_FNAME>
         *
         * @param zip <EMBED CLASS='external-html' DATA-FILE-ID=GCSSB_ZIP>
         *
         * @param returnClass This is the type expected to be found by Java in the Serialized
         * {@code Object} Data-File.  If an {@code Object} is read from this location, but it does
         * not have the type indicated by this parameter, the program will also halt, and an
         * explanatory exception message will be printed to the console/terminal.
         *
         * @param <T> This type parameter is simply provided for convenience, to allow the user
         * to specify the return class, without having to cast the object and suppress warnings,
         * or catch exceptions.
         *
         * @return A de-serialized java {@code java.lang.Object} that has been read from a GCS
         * {@code Storage Bucket}, and cast to the type denoted by parameter
         * {@code 'returnClass'}.
         *
         * @see FileRW#readObjectFromFile(String, boolean)
         * @see FileRW#readObjectFromFileNOCNFE(String, boolean)
         * @see #readObjectFromFile(String, boolean, Class)
         * @see #ERROR_EXIT(String)
         */
        public static <T> T readObjectFromFile(
                Storage storage, String bucket, String completeFileName,
                boolean zip, Class<T> returnClass
            )
        {
            try
            {
                // Read Storage Bucket Data into a byte[] array
                byte[] bArr = storage.get(bucket, completeFileName).getContent();

                // Build an Input Stream, using that byte[] array as input
                ByteArrayInputStream bis = new ByteArrayInputStream(bArr);

                // Build an Object Input Stream, using the byte-array input-stream as input
                ObjectInputStream ois = zip
                    ? new ObjectInputStream(new GZIPInputStream(bis))
                    : new ObjectInputStream(bis);

                // Use Java's Object Serialization method to read the Object
                Object ret = ois.readObject();

                if (! returnClass.isInstance(ret)) ERROR_EXIT(
                    "Serialized Object read from GCS Storage Bucket: " + bucket + "\n" +
                    "And file-name: " + completeFileName + "\n" +
                    "Using expected (" + (zip ? "zip-compression" : "no-compression") + ")\n" +
                    "Didn't have an object with class-name: " + returnClass + "\n" +
                    "But rather with className: " + ret.getClass().getName()
                );

                ois.close(); bis.close();

                return returnClass.cast(ret);
            }

            catch (Throwable t)
            {
                ERROR_EXIT(
                    t,
                    "Serialized Object read from GCS Storage Bucket: " + bucket + "\n" +
                    "And file-name: " + completeFileName + "\n" +
                    "Using expected (" + (zip ? "zip-compression" : "no-compression") + ")\n" +
                    "And Expected class-name: " + returnClass + "\n"
                );

                throw new UnreachableError(); // Cannot reach this statement
            }
        }

        /**
         * This merely loads a text-file from Google's Storage Bucket infrastructure into a
         * {@code String.}  Make sure to check that the file you are loading does indeed have
         * text-content.
         *
         * @param storage <EMBED CLASS='external-html' DATA-FILE-ID=GCSSB_STORAGE>
         *
         * @param bucket The {@code bucket} name of the {@code bucket} from a Google Cloud Server
         * account.
         *
         * @param completeFileName <EMBED CLASS='external-html' DATA-FILE-ID=GCSSB_CMPL_FNAME>
         *
         * @return The text file on Google Cloud Server's Storage Bucket file/directory returned as
         * a {@code java.lang.String}
         */
        public static String loadFileToString
            (Storage storage, String bucket, String completeFileName)
        { return new String(storage.get(bucket, completeFileName).getContent()); }

        /**
         * This merely loads a text-file from Google's Storage Bucket infrastructure into a
         * {@code String}.  Make sure to check that the file you are loading does indeed have
         * text-content.
         *
         * @param storage <EMBED CLASS='external-html' DATA-FILE-ID=GCSSB_STORAGE>
         *
         * @param bucket The {@code bucket} name of the {@code bucket} from a Google Cloud Server
         * account.
         *
         * @param completeFileName <EMBED CLASS='external-html' DATA-FILE-ID=GCSSB_CMPL_FNAME>
         *
         * @param includeNewLine This tells the method to include, or not-include, a {@code '\n'}
         * (newline) character to each {@code String}.
         *
         * @return The text file on Google Cloud Server's {@code Storage Bucket} file/directory
         * stuff as a {@code Vector} of {@code String's}.
         *
         * @see #loadFileToString(Storage, String, String)
         */
        public static Vector<String> loadFileToVector
            (Storage storage, String bucket, String completeFileName, boolean includeNewLine)
        {
            String          s   = loadFileToString(storage, bucket, completeFileName);
            Vector<String>  ret = new Vector<>();

            int pos     = 0;
            int delta   = includeNewLine ? 1 : 0;
            int lastPos = 0;

            while ((pos = s.indexOf('\n')) != -1)
            {
                ret.add(s.substring(lastPos, pos + delta));
                lastPos = pos + 1;
            }

            if (lastPos < s.length()) ret.add(s.substring(lastPos));

            return ret;
        }
    
        /**
         * This will write the contents of a java {@code 'CharSequence'}  - includes
         * {@code String, StringBuffer & StringBuilder} to a
         * file on Google Cloud Server's storage bucket system.
         *
         * @param storage <EMBED CLASS='external-html' DATA-FILE-ID=GCSSB_STORAGE>
         *
         * @param bucket The {@code bucket} name of the {@code bucket} from a Google Cloud Server
         * account.
         * @param completeFileName <EMBED CLASS='external-html' DATA-FILE-ID=GCSSB_CMPL_FNAME>
         *
         * @param ASCIIorUTF8  When writing java {@code String's} the file-system, it is generally
         * not to important to worry about whether java has stored an {@code 'ASCII'} encoded
         * {@code String}, or a {@code String} encoded using {@code 'UTF-8'}.  Most
         * foreign-language news-sites require the latter ({@code 'UTF-8'}), but any site that is
         * strictly English can get by with plain old ASCII.
         *
         * <BR /><BR /><B><SPAN STYLE="color: red">IMPORTANT:</B></SPAN> When this boolean is
         * {@code TRUE}, this method will attempt to presume the character-sequence you have passed
         * is in ASCII, and write it that way.  When this boolean is set to {@code FALSE},
         * this method will attempt to write the {@code String} of {@code byte's} as a
         * {@code 'UTF-8'} encoded character-set.
         *
         * <BR /><BR /><B>ALSO:</B> I have not made any allowance for Unicode or Unicode little
         * endian, because I have never used them with either the Chinese or Spanish sites I
         * scrape.  UTF-8 has been the only other character set I encounter.
         */
        public static void writeFile(
                CharSequence fileAsStr, Storage storage, String bucket,
                String completeFileName, boolean ASCIIorUTF8
            )
        {
            BlobInfo blobInfo = BlobInfo.newBuilder
                (BlobId.of(bucket, completeFileName)).setContentType("text/plain").build();

            byte[] file = ASCIIorUTF8
                ? fileAsStr.toString().getBytes()
                : fileAsStr.toString().getBytes(java.nio.charset.Charset.forName("UTF-8"));

            Blob blob = storage.create(blobInfo, file);
        }

        /**
         * This will write a Java {@code Serializable Object} to a location in a Google Cloud
         * Server Storage Bucket.
         * 
         * @param storage <EMBED CLASS='external-html' DATA-FILE-ID=GCSSB_STORAGE>
         * 
         * @param o This may be any {@code Serializable Java Object}.  {@code Serializable Java
         * Objects} are ones which implement the {@code interface java.io.Serializable}.
         * 
         * @param bucket The {@code bucket} name of the {@code bucket} from a Google Cloud Server
         * account.
         * 
         * @param completeFileName <EMBED CLASS='external-html' DATA-FILE-ID=GCSSB_CMPL_FNAME>
         * 
         * @param zip <EMBED CLASS='external-html' DATA-FILE-ID=GCSSB_ZIP>
         */
        public static void writeObjectToFile(
                Object o, Storage storage, String bucket,
                String completeFileName, boolean zip
            )
            throws IOException
        {
            // Retrieves a file-name object using a GCS BUCKET-NAME, and the FILE-NAME (in
            // the bucket)            

            BlobId blobId = BlobId.of(bucket, completeFileName);

            // This BlobInfo is GCS version of "java.io.File".  It points to a specific file
            // inside a GCS Bucket (which was specified earlier)

            BlobInfo blobInfo = BlobInfo
                .newBuilder(blobId)
                // .setContentType("text/plain")
                .build();

            // This will save the Serialized Object Data to a Stream (and eventually an array)
            ByteArrayOutputStream baos = new ByteArrayOutputStream();

            // This stream writes serialized Java-Objects to the Storage Bucket
            ObjectOutputStream oos = zip
                ? new ObjectOutputStream(new GZIPOutputStream(baos))
                : new ObjectOutputStream(baos);

            oos.writeObject(o);

            oos.flush(); baos.flush(); oos.close();

            // Convert that BAOS to a Byte-Array
            byte[]  bArr = baos.toByteArray();

            // Write the BYTE-ARRAY to the GCS Bucket and file using the "BlobInfo" that was built
            // a few lines ago.

            Blob blob = storage.create(blobInfo, bArr);
        }
    }
}