package Torello.Java.Build;

import Torello.Java.Additional.AppendableSafe;

import Torello.Java.OSCommands;
import Torello.Java.OSResponse;
import Torello.Java.OSExtras;
import Torello.Java.GSUTIL;
import Torello.Java.StorageWriter;

import java.util.Objects;
import java.util.Vector;
import java.util.regex.Pattern;         // for the Nick-Name Checker
import java.util.function.Predicate;    // Convert Nick-Name Checker to a Prediate
import java.io.IOException;

/**
 * This interface contains all of the interactions that occur between a Cloud-Basked
 * Storage-Bucket, such as Google Cloud Platform or an Amazon-S3 Compatible Storage-System, and
 * this <B STYLE='color: red;'><CODE>'&#46;jar'</CODE> and Java-Doc Build Tools</B>.
 * 
 * <BR /><BR />Note it is somewhat difficult to delineate, exactly, what "Synchronize my
 * {@code '.jar'} Project-Files to the Cloud" actually means.  This particular Java-Interface lists
 * exactly what is copied over to your Storage / CDN Setup.  Furthermore, this Java-Interfaces 
 * delineates exactly what HTTP &amp; Bucket-Permission Meta-Data must be updated in order to
 * ensure that your Java-Doc Pages and archives are publicly visible.
 * 
 * <BR /><BR />This Jar-Project, specifically the Java-HTML {@code '.jar'} Library, was built using
 * Google-Cloud Storage-Buckets for the vast majority of this Project's lifetime.  Recently,
 * howeveer, a move to utilize the <B>Content Delivery Network</B> (CDN) named
 * <A HREF='https://CloudFlare.com' TARGET=_blank>CloudFlare</A> has taken place.  The four stages
 * of this Build-Tool that involve copying HTML-Files and Archive-Files (synchronizing) to a CDN or
 * Storage-System are all listed on this particular Package's Class-File-List Web-Page.  The four 
 * Build-Tool Stages are listed under "Cloud Synchronization Stage Classes".
 * 
 * <BR /><BR />The features they export do nothing more than what are listed inside the methods 
 * provided by this Java-Interface.
 * 
 * <BR /><BR />The contents of the class {@link CloudSync} simply contain several
 * "utilities" needed to make the whole Synchronization-Process work.  As was mentioned earlier,
 * this entire {@code '.jar'} Project (Java-HTML) was built using GCP.  For this reason, the simple
 * to use Python-Utility offered by Google know as {@link GSUTIL} was used to do perform all of the
 * interactions that are needed to sync files from a Terminal-Shell Window to a Cloud-Based
 * Storage-Bucket or Content-Delivery-Network
 * 
 * <BR /><BR />The recent addition of a CDN to host the Java-Doc Files generated by this project
 * has meant possibily adding other forms of "Cloud-Synchronization Code."  Amazon has a 
 * substantially well-know Storage-API called known as "Amazon S3", or simply "S3".  At the moment
 * build code that can run a Java-Based S3-API has not been written, although it is largely because
 * there is still work to be done on the Java-Doc Upgrader and the CSS Tokenizer &amp; Parser Code.
 * 
 * <BR /><BR />Likely it will either involve streamlining a simply Java Process Class that extends
 * {@link OSCommands} for the well-known utility
 * <A HREF='https://rclone.org' TARGET=_blank>rclone</A>, or it will mean streamlining Amazon's
 * giant plate of Java-Spaghetti known as the Java-API for S3 into something simple that is
 * imported into this Java-Project's API.  Eventually there will be a class named either
 * {@code RCloneCloudSync} or one named {@code S3CloudSync} (or both!).
 * 
 * @see GSUTIL
 * @see OSCommands
 */
public abstract class CloudSync
{
    // ********************************************************************************************
    // ********************************************************************************************
    // PACKAGE-PRIVATE: BuilderRecord Instance
    // ********************************************************************************************
    // ********************************************************************************************


    // This has not been declared final.  It cannot be because due to restrictions on the order of
    // constructor initializations, something has to be initialized after the constructor has
    // already run to completion.  This abstract-class "CloudSync" is always supposed to be 
    // instantiated by the end-user of Torello.Java.Build.  The actual-selected "BuilderRecord"
    // instance isn't created until after the user has passed the list of "CloudSync" instances to
    // the class Config.
    // 
    // Therefore this field cannot be instantiated by this class constructor.
    // 
    // Therefore this field cannot be declared final.
    // 
    // Since this field ins't final, it is not going to be public.  Luckily it is only used
    // internally by the classes inside this Torello.Java.Build package.
    // 
    // This field is set in exactly one location - on the last line of class BuilderRecord's
    // Constructor.  It cannot be set in this class constructor because this class is constructed
    // by the user, before any CLI processing has even occured.  It's a "Chicken or the Egg" 
    // type of thing.

    BuilderRecord brec = null;


    // ********************************************************************************************
    // ********************************************************************************************
    // Public-Final Fields
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * One of three archives generated during the Stage-4 / Tar-Jar Stage, an archive 
     * {@code '.tar'}-File of your Root Source-Code directory may be generated, and saved to a
     * discreet Storage-Bucket Directory in the Cloud.
     * 
     * <BR /><BR />This behavior may be controlled by this setting.  This field is initialized with
     * the value passed to the Constructor-Parameter of the exact same name
     * {@code 'shouldSyncMainTarGzFile'}
     */
    public final boolean shouldSyncMainTarGzFile;

    /**
     * Google Cloud Storage actually allows the files saved to it's Storage-Buckets to be
     * configured such that "all of them" are, by default, all public (or all private).
     * There is also a way to configure a Cloud Storage-Bucket to accept granular level
     * public / private settings for each file.
     * 
     * <BR /><BR />If the Cloud-Storage System you are configuring is set to enforce
     * "Bucket-Level Access-Decisions", then this field should be set {@code FALSE}.  If your
     * Storage-Service (S3, GCP or R2 to name a few) is configured to allow for individual
     * "Object-Level Access-Control", then this field should be assigned {@code TRUE}.
     * 
     * <BR /><BR />When this field is assigned {@code TRUE}, this Build-Tool will run a complete
     * "Make-Public" operation on all {@code '.html'}-Files which have been recently uploaded to
     * your Web-Domain / Storage-Bucket.
     */
    public final boolean shouldRunMakePublic;

    /**
     * A "Public-Release" Cloud Storage-Bucket Directory likely has no need for "Partial-Buids" 
     * (which can also be referred to as "Developer Builds").  A Partial-Build is where only some
     * of the Class-File Documentation {@code '.html'}-Pages are updated and synchronized to the
     * relevant Web-Page Directory.
     * 
     * <BR /><BR />A Partial-Build can speed up, tremendously, the process of writing code,
     * checking it, and then viewing the output on your Java-Doc Pages.  Target
     * "Source-Distribution" Web-Domains, on the other, have no need for this setting.
     * 
     * <BR /><BR />The current Web-Domain hosted at {@code https://JavaHTML.Torello.Directory}
     * is not configured to accept Partial-Builds.
     */
    public final boolean allowPartialBuilds;

    /**
     * This field determines whether a target Storage-Bucket should permit the Stage-8 
     * 'Set-Max-Age' (a.k.a. 'No-Browser-Cache') to run.  For a Public-Release Build-Target, such
     * as the Java-HTML Cloud-Flare Release target, the No-Browser-Cache option is not needed.
     * As a "Developer-Release" Target, it is updated much less frequently (more infrequently?),
     * and the Browser-Cache issue is completely irrelevant.
     * 
     * <BR /><BR />For Storage-Bucket Directories that are updated &amp; modified several times
     * during the course of a single day (because the software-developer is diligently working on
     * another fix), this <B>{@code Set-Max-Age}</B> option can be an invaluable tool to make sure
     * that updated Java-Doc Pages are, indeed, updated - <I>not stale!!</I>
     * 
     * <BR /><BR />The current Web-Domain hosted at {@code https://JavaHTML.Torello.Directory}
     * is not configured to set the HTTP Meta-Data {@code CACHE-CONTROL} setting at all, because it
     * is a "Release Target" Web-Domain.
     */
    public final boolean includeSetMaxAgeBuilds;

    /**
     * The Storage Service / Web-Domain that you are configuring must be given a short, brief
     * Nick-Name.  This Nick-Name will be printed in the Command-Line Help-Menu Options-List.
     * 
     * <BR /><BR />Note that this Nick-Name may not exceed 20 characters in length, or an
     * {@code IllegalArgumentException} will be thrown by this class' constructor.
     * 
     * <BR /><BR />This Nick-Name must ahere to the following Regular-Expression checker, or an
     * {@code IllegalArgumentException} will be thrown by the constructor.
     * 
     * <BR /><BR /><B STYLE='color: darkred;'>{@code Pattern.compile("\\w[\\w\\d-]*");}</B>
     */
    public final String nickName;

    /**
     * The Cloud-Storage Target-Directory you intend to use.
     * 
     * <BR /><BR />For Google-Cloud Storage-Buckets, this would be:
     * {@code gs://Your-Bucket-Name/You/Target/Directory/}
     */
    public final String cloudRootStorageDir;


    // ********************************************************************************************
    // ********************************************************************************************
    // Constructor
    // ********************************************************************************************
    // ********************************************************************************************


    private static final Pattern            checkNickNameRE = Pattern.compile("\\w[\\w\\d-]*");
    private static final Predicate<String>  checkNickName   = checkNickNameRE.asPredicate();

    /**
     * Protected-Constructor.
     * 
     * @param shouldSyncMainTarGzFile This is a boolean that identifies whether the Project's main
     * Backup-{@code '.tar'} File should be synchronized to a Cloud-Storage "Backup" Directory.
     * Note that this addition can be an invaluable means for ensuring that your code is never lost
     * or deleted (once, each and every day), without actually resorting to using Monolithic Tools
     * like GitHub.
     * 
     * <BR /><BR />I am not "opposed" to Git-Hub, but I simply cannot, in good conscious, use it.
     * This HTML Project has been extended into a Code-Documentation Tool, and that means Git-Hub's
     * features that expose your code, without including Java-Doc, make it untennable for this
     * project.
     * 
     * @param shouldRunMakePublic This boolean should be used to indicate whether or not the
     * Cloud-Synchronization Stages need to ensure that your Java-Doc HTML Web-Page Files are made
     * publicly visible.
     * 
     * <BR /><BR />In GCP, whenever Object-Level Permissions are selected for a Storage-Bucket, it 
     * is imperative to set the "Access-Control" settings for each of the Java-Doc Web-pages are
     * updated to allow "Read Access."  However, in GCP (and other Web-Domain Storage-Services), it
     * is also possible to assign "Bucket-Level Permissions".  In such cases, there is no need to 
     * assign "Public Visible" to each of the Java-Doc {@code '.html'}-Filess that have been copied
     * to your domain.
     * 
     * <BR /><BR />This Constructor-Parameter is assigned to the field {@link #shouldRunMakePublic},
     * and that field's documentation / explanation does contain more information about this
     * setting.  Please review the information provided there.
     * 
     * @param allowPartialBuilds Decides whether the {@code -pb} CLI Options are permitted.  This
     * configuration was formerly known as "Release or Developer", and only Developer
     * Storage-Buckets allowed Partial-Builds to happen on their Storage-Space.
     * 
     * <BR /><BR />When this {@code CloudSync} configuration parameter is {@code 'false'}, none of
     * the CLI-Command-Line options for specifying a partial Package-List are included within the
     * Main-Menu for this Cloud-Storage Target.
     * 
     * <BR /><BR />This Constructor-Parameter is assigned to the field {@link #allowPartialBuilds},
     * and that field's documentation / explanation does contain more information about this
     * setting.  Please review the information provided there.
     * 
     * @param includeSetMaxAgeBuilds The Build-Tool allows you to request that a particular
     * Cloud-Storage Target be configured to expect that all Java-Doc {@code '.html'}-Files that
     * are copied moved onto it have an HTTP Meta-Data {@code 'CACHE-CONTROL'} setting.
     * 
     * <BR /><BR />When this {@code boolean}-Parameter is passed {@code TRUE}, the HTTP 
     * Configuration-Parameter {@code 'CACHE-CONTROL'} is assigned the value {@code 'public'}
     * and {@code 'max-age=150'} to each an every Java-Doc {@code '.html'}-File that is copied
     * to your Storage-Buckets.  When you view those files in your Web-Browser (like Google Chrome
     * for instance), the pages you view <B STYLE='color: red;'><I>will not be cached by your
     * browser!</I></B>.
     * 
     * <BR /><BR />This can make it worlds easier for checking, re-compiling, and re-updating
     * your pages without having to go and erase everything you have out of your Browser-Cache.
     * 
     * <BR /><BR />This Constructor-Parameter is assigned to the field
     * {@link #includeSetMaxAgeBuilds}, and that field's documentation / explanation does contain
     * more information about this setting.  Please review the information provided there.
     * 
     * @param nickName This is a required parameter that is used to facilitate your making
     * selections at the Command-Line Interface regarding which Cloud-Build Sychronization setup
     * you would like to use.
     * 
     * <BR /><BR /><B STYLE='color: red;'>NOTE:</B> Early on in your project, likely, you won't
     * need more than one Storage-Synchronization {@link CloudSync}-Instance.  As your project
     * grows, you will likely want to have a Storage-Bucket for you Java-Doc Pages that contain
     * some recently stable-version of your {@code '.jar'}-File.
     * 
     * <BR /><BR />Then, adding a second Web-Site, or Site-Sub-Directory for serving up pages that
     * are still under development (not working yet) will likely reduce your stress levels and 
     * (hopefully) the impact on your blood-pressure.
     * 
     * @param cloudRootStorageDir This is the Cloud-Based "Root Directory" for your Project.
     * 
     * @throws NullPointerException If either {@code nickName} or {@code cloudRootStorageDir} are
     * passed null.
     * 
     * @throws IllegalArgumentException If the rules for a valid Cloud-Storage Target are not 
     * properly adhered, as per the explanation in the documentation for field {@link #nickName},
     * above.
     */
    protected CloudSync(
            final boolean   shouldSyncMainTarGzFile,
            final boolean   shouldRunMakePublic,
            final boolean   allowPartialBuilds,
            final boolean   includeSetMaxAgeBuilds,
            final String    nickName,
            final String    cloudRootStorageDir
        )
    {
        Objects.requireNonNull(nickName);
        Objects.requireNonNull(cloudRootStorageDir);

        this.shouldSyncMainTarGzFile    = shouldSyncMainTarGzFile;
        this.shouldRunMakePublic        = shouldRunMakePublic;
        this.allowPartialBuilds         = allowPartialBuilds;
        this.includeSetMaxAgeBuilds     = includeSetMaxAgeBuilds;
        this.nickName                   = nickName;
        this.cloudRootStorageDir        = cloudRootStorageDir;

        if (nickName.length() > 20) throw new IllegalArgumentException
            ("The Target Storage-Bucket Nick-Name provided is too long: " + nickName);

        if (! checkNickName.test(nickName)) throw new IllegalArgumentException(
            "The  Target Storage-Bucket Nick-Name provided [" + nickName + "] does not pass the " +
            "Name Regular-Expression Checker: " + checkNickNameRE.toString()
        );
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // public class S05_SyncJavaDoc - SYNCHRONIZE ENTIRE PROJECT
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * This method should delete all files in the Cloud's {@code 'javadoc/''} directory.
     * 
     * @return The output-text and O/S Response-Code generated by invoking this method.
     * @throws IOException throws if there are any I/O Problems thrown by this method
     */
    public abstract OSResponse removeCloudJavaDocDir() throws IOException;

    /**
     * This method should copy all files from the Machine-Local {@code 'javadoc/'} directory to 
     * the {@code 'javadoc/'} directory in the cloud.
     * 
     * @return The output-text and O/S Response-Code generated by invoking this method.
     * @throws IOException throws if there are any I/O Problems thrown by this method
     */
    public abstract OSResponse copyJavaDocDirToCloudDir() throws IOException;

    /**
     * This Method should be run if your Cloud-Storage Directory requires your recently copied /
     * synchronized {@code'.html'} Documentation-Files to be explicity made public.
     * 
     * @return The output-text and O/S Response-Code generated by invoking this method.
     * @throws IOException throws if there are any I/O Problems thrown by this method
     */
    public abstract OSResponse makePublicJavaDocDir() throws IOException;


    // ********************************************************************************************
    // ********************************************************************************************
    // public class S05_SyncJavaDoc - SYNCHRONIZE SPECIFIED LIST OF PROJECT PACKAGES
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Copy the primary Java-Doc Web-Page Files for a Single Java Package to the appropriate
     * Cloud Storage Directory.
     * 
     * @param pkgRootLocalDir The local package source-code directory to copy.
     * @param pkgRootCloudStorageDir The Cloud-Storage Target-Directory Location
     * @return The output-text and O/S Response-Code generated by invoking this method.
     * @throws IOException throws if there are any I/O Problems thrown by this method
     */
    public abstract OSResponse copySingleJDPackageToCloud
        (String pkgRootLocalDir, String pkgRootCloudStorageDir)
        throws IOException;

    /**
     * Copy additional Package Sub-Directories to the Cloud.  The directories that are copied are
     * the sub-directories for a single Java-Package Sub-Directory in the Java-Doc Directory
     * File-System Tree.
     * 
     * <BR /><BR /><UL CLASS=JDUL>
     * <LI>{@code doc-files/}</LI>
     * <LI>{@code upgrade-files/stylesheets/}</LI>
     * <LI>{@code hilite-files/}</LI>
     * </UL>
     * 
     * @param ose An instance of {@link OSExtras} that contains the path to the package's
     * source-directory location on the File-System.
     * 
     * @param copyDirs The list of the package's sub-directories to copy.
     * @param pkgRootCloudStorageDir The Cloud-Storage Target-Directory Location
     * @return The output-text and O/S Response-Code generated by invoking this method.
     * @throws IOException throws if there are any I/O Problems thrown by this method
     */
    public abstract OSResponse copyOtherPackageDirsToCloudDir
        (OSExtras ose, Vector<String> copyDirs, String pkgRootCloudStorageDir)
        throws IOException;

    /**
     * This Method should be run if your Cloud-Storage Directory requires your recently copied /
     * synchronized {@code'.html'} Documentation-Files to be explicity made public.
     * 
     * @return The output-text and O/S Response-Code generated by invoking this method.
     * @throws IOException throws if there are any I/O Problems thrown by this method
     */
    public abstract OSResponse makePublicDirArr(String[] dirArr) throws IOException;


    // ********************************************************************************************
    // ********************************************************************************************
    // public class S06_SyncTarJar
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * This method should copy the following files to their relevant Cloud Storage Directory:
     * 
     * <BR /><BR /><UL CLASS=JDUL>
     * <LI>{@code Project.jar}</LI>
     * <LI>{@code Project-JavaDoc.tar}</LI>
     * </UL>
     * 
     * @return The output-text and O/S Response-Code generated by invoking this method.
     * @throws IOException throws if there are any I/O Problems thrown by this method
     */
    public abstract OSResponse copyJDTarAndJarToCloud() throws IOException;

    /**
     * This Method should be run if your Cloud-Storage Directory requires your recently copied /
     * synchronized {@code '.tar'} &amp; {@code '.jar'} files to be explicity made public.
     * 
     * @return The output-text and O/S Response-Code generated by invoking this method.
     * @throws IOException throws if there are any I/O Problems thrown by this method
     */
    public abstract OSResponse makeJDTarAndJarPublic() throws IOException;

    /**
     * This method should copy your {@code Project-Backup.tar} File to the appropriate 
     * date-based Cloud-Storage Backup-Directory.
     * 
     * @return The output-text and O/S Response-Code generated by invoking this method.
     * @throws IOException throws if there are any I/O Problems thrown by this method
     */
    public abstract OSResponse backupMainTarGzFile() throws IOException;


    // ********************************************************************************************
    // ********************************************************************************************
    // public class S07_SyncLogs
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Copies all files in the User-Supplied {@code 'logs/'} Local-Directory to the Cloud
     * Storage Log-Directory.
     * 
     * @return The output-text and O/S Response-Code generated by invoking this method.
     * @throws IOException throws if there are any I/O Problems thrown by this method
     */
    public abstract OSResponse copyLogDirToCloud() throws IOException;

    /**
     * If there is any need to modify the HTTP {@code CONTENT-TYPE} Meta-Data, this method should
     * be the one for doing that.
     * 
     * @return The output-text and O/S Response-Code generated by invoking this method.
     * @throws IOException throws if there are any I/O Problems thrown by this method
     */
    public abstract OSResponse setCloudLogsContentType() throws IOException;

    /**
     * This Method should be run if your Cloud-Storage Directory requires your recently copied /
     * synchronized Log-Files to be explicity made public.
     * 
     * @return The output-text and O/S Response-Code generated by invoking this method.
     * @throws IOException throws if there are any I/O Problems thrown by this method
     */
    public abstract OSResponse makeLogsPublic() throws IOException;


    // ********************************************************************************************
    // ********************************************************************************************
    // public class S08_SetMaxAge
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * This method should set the Meta-Information {@code 'CACHE-CONTROL'} setting for the 
     * User's Browser-Cache to zero or something very low.  When writing Java-Code, if your
     * javadoc pages are fequently being updated, tested and evaluated, making sure that the 
     * Web-Browser is not caching stale HTML-Pages from you JavaDoc Web-Page Web-Server really
     * needs to be a very high priority thing to worry about.
     * 
     * @return The output-text and O/S Response-Code generated by invoking this method.
     * @throws IOException throws if there are any I/O Problems thrown by this method
     */
    public abstract OSResponse setMaxAgeAll() throws IOException;

    /**
     * This does the same thing as {@link setMaxAgeAll}, but it is only executed on the pages
     * that are specified by the recently updated packages array.
     * 
     * <BR /><BR />I am going to explain this simply little thing later on.
     * 
     * @return The output-text and O/S Response-Code generated by invoking this method.
     * @throws IOException throws if there are any I/O Problems thrown by this method
     */
    public abstract OSResponse setMaxAgeSome() throws IOException;


    // ********************************************************************************************
    // ********************************************************************************************
    // Protected Log-Printing Stuff
    // ********************************************************************************************
    // ********************************************************************************************


    /** Protected, Internal Method.  Initiates a Build-Stage's Log-Output Printing Mechanism. */
    protected abstract void initStage(Appendable logOnly, Appendable logAndScreen);

    /**
     * Protected, Internal Method.  Initiates "Synchronie Logs" Build-Stage Output-Printing
     * Mechanism
     */
    protected abstract void initStageLogSync();

    /** Finalizes the a particular Build-Stages Log Printing Output. */
    protected abstract void endStage();
}