Class CloudSync

  • Direct Known Subclasses:
    CloudSyncGSUTIL, CloudSyncRClone, CloudSyncS3
    public abstract class CloudSync
extends java.lang.Object
    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 '.jar' and Java-Doc Build Tools.

    Note it is somewhat difficult to delineate, exactly, what "Synchronize my '.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 & Bucket-Permission Meta-Data must be updated in order to ensure that your Java-Doc Pages and archives are publicly visible.

    This Jar-Project, specifically the Java-HTML '.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 Content Delivery Network (CDN) named CloudFlare 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".

    The features they export do nothing more than what are listed inside the methods provided by this Java-Interface.

    The contents of the class CloudSync simply contain several "utilities" needed to make the whole Synchronization-Process work. As was mentioned earlier, this entire '.jar' Project (Java-HTML) was built using GCP. For this reason, the simple to use Python-Utility offered by Google know as 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

    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 & Parser Code.

    Likely it will either involve streamlining a simply Java Process Class that extends OSCommands for the well-known utility rclone, 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 RCloneCloudSync or one named S3CloudSync (or both!).
    See Also:
    GSUTIL, OSCommands


    • Field Detail

      • shouldSyncMainTarGzFile

        🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final boolean shouldSyncMainTarGzFile
        One of three archives generated during the Stage-4 / Tar-Jar Stage, an archive '.tar'-File of your Root Source-Code directory may be generated, and saved to a discreet Storage-Bucket Directory in the Cloud.

        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 'shouldSyncMainTarGzFile'

      • shouldRunMakePublic

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final boolean shouldRunMakePublic
        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.

        If the Cloud-Storage System you are configuring is set to enforce "Bucket-Level Access-Decisions", then this field should be set 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 TRUE.

        When this field is assigned TRUE, this Build-Tool will run a complete "Make-Public" operation on all '.html'-Files which have been recently uploaded to your Web-Domain / Storage-Bucket.

      • allowPartialBuilds

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final boolean allowPartialBuilds
        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 '.html'-Pages are updated and synchronized to the relevant Web-Page Directory.

        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.

        The current Web-Domain hosted at https://JavaHTML.Torello.Directory is not configured to accept Partial-Builds.

      • includeSetMaxAgeBuilds

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final boolean includeSetMaxAgeBuilds
        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.

        For Storage-Bucket Directories that are updated & modified several times during the course of a single day (because the software-developer is diligently working on another fix), this Set-Max-Age option can be an invaluable tool to make sure that updated Java-Doc Pages are, indeed, updated - not stale!!

        The current Web-Domain hosted at https://JavaHTML.Torello.Directory is not configured to set the HTTP Meta-Data CACHE-CONTROL setting at all, because it is a "Release Target" Web-Domain.

      • nickName

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final java.lang.String nickName
        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.

        Note that this Nick-Name may not exceed 20 characters in length, or an IllegalArgumentException will be thrown by this class' constructor.

        This Nick-Name must ahere to the following Regular-Expression checker, or an IllegalArgumentException will be thrown by the constructor.

        Pattern.compile("\\w[\\w\\d-]*");

      • cloudRootStorageDir

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final java.lang.String cloudRootStorageDir
        The Cloud-Storage Target-Directory you intend to use.

        For Google-Cloud Storage-Buckets, this would be: gs://Your-Bucket-Name/You/Target/Directory/

    • Constructor Detail

      • CloudSync

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        protected CloudSync​(boolean shouldSyncMainTarGzFile,
                    boolean shouldRunMakePublic,
                    boolean allowPartialBuilds,
                    boolean includeSetMaxAgeBuilds,
                    java.lang.String nickName,
                    java.lang.String cloudRootStorageDir)
        Protected-Constructor.
        Parameters:
        shouldSyncMainTarGzFile - This is a boolean that identifies whether the Project's main Backup-'.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.

        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.
        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.

        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 '.html'-Filess that have been copied to your domain.

        This Constructor-Parameter is assigned to the field shouldRunMakePublic, and that field's documentation / explanation does contain more information about this setting. Please review the information provided there.
        allowPartialBuilds - Decides whether the -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.

        When this CloudSync configuration parameter is '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.

        This Constructor-Parameter is assigned to the field allowPartialBuilds, and that field's documentation / explanation does contain more information about this setting. Please review the information provided there.
        includeSetMaxAgeBuilds - The Build-Tool allows you to request that a particular Cloud-Storage Target be configured to expect that all Java-Doc '.html'-Files that are copied moved onto it have an HTTP Meta-Data 'CACHE-CONTROL' setting.

        When this boolean-Parameter is passed TRUE, the HTTP Configuration-Parameter 'CACHE-CONTROL' is assigned the value 'public' and 'max-age=150' to each an every Java-Doc '.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 will not be cached by your browser!.

        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.

        This Constructor-Parameter is assigned to the field includeSetMaxAgeBuilds, and that field's documentation / explanation does contain more information about this setting. Please review the information provided there.
        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.

        NOTE: Early on in your project, likely, you won't need more than one Storage-Synchronization 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 '.jar'-File.

        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.
        cloudRootStorageDir - This is the Cloud-Based "Root Directory" for your Project.
        Throws:
        java.lang.NullPointerException - If either nickName or cloudRootStorageDir are passed null.
        java.lang.IllegalArgumentException - If the rules for a valid Cloud-Storage Target are not properly adhered, as per the explanation in the documentation for field nickName, above.

    • Method Detail

      • removeCloudJavaDocDir

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public abstract OSResponse removeCloudJavaDocDir()
                                          throws java.io.IOException
        This method should delete all files in the Cloud's 'javadoc/'' directory.
        Returns:
        The output-text and O/S Response-Code generated by invoking this method.
        Throws:
        java.io.IOException - throws if there are any I/O Problems thrown by this method

      • copyJavaDocDirToCloudDir

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public abstract OSResponse copyJavaDocDirToCloudDir()
                                             throws java.io.IOException
        This method should copy all files from the Machine-Local 'javadoc/' directory to the 'javadoc/' directory in the cloud.
        Returns:
        The output-text and O/S Response-Code generated by invoking this method.
        Throws:
        java.io.IOException - throws if there are any I/O Problems thrown by this method

      • makePublicJavaDocDir

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public abstract OSResponse makePublicJavaDocDir()
                                         throws java.io.IOException
        This Method should be run if your Cloud-Storage Directory requires your recently copied / synchronized '.html' Documentation-Files to be explicity made public.
        Returns:
        The output-text and O/S Response-Code generated by invoking this method.
        Throws:
        java.io.IOException - throws if there are any I/O Problems thrown by this method

      • copySingleJDPackageToCloud

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public abstract OSResponse copySingleJDPackageToCloud​
            (java.lang.String pkgRootLocalDir,
             java.lang.String pkgRootCloudStorageDir)
        throws java.io.IOException
        Copy the primary Java-Doc Web-Page Files for a Single Java Package to the appropriate Cloud Storage Directory.
        Parameters:
        pkgRootLocalDir - The local package source-code directory to copy.
        pkgRootCloudStorageDir - The Cloud-Storage Target-Directory Location
        Returns:
        The output-text and O/S Response-Code generated by invoking this method.
        Throws:
        java.io.IOException - throws if there are any I/O Problems thrown by this method

      • copyOtherPackageDirsToCloudDir

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public abstract OSResponse copyOtherPackageDirsToCloudDir​
            (OSExtras ose,
             java.util.Vector<java.lang.String> copyDirs,
             java.lang.String pkgRootCloudStorageDir)
        throws java.io.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.

        • doc-files/
        • upgrade-files/stylesheets/
        • hilite-files/
        Parameters:
        ose - An instance of OSExtras that contains the path to the package's source-directory location on the File-System.
        copyDirs - The list of the package's sub-directories to copy.
        pkgRootCloudStorageDir - The Cloud-Storage Target-Directory Location
        Returns:
        The output-text and O/S Response-Code generated by invoking this method.
        Throws:
        java.io.IOException - throws if there are any I/O Problems thrown by this method

      • makePublicDirArr

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public abstract OSResponse makePublicDirArr​(java.lang.String[] dirArr)
                                     throws java.io.IOException
        This Method should be run if your Cloud-Storage Directory requires your recently copied / synchronized '.html' Documentation-Files to be explicity made public.
        Returns:
        The output-text and O/S Response-Code generated by invoking this method.
        Throws:
        java.io.IOException - throws if there are any I/O Problems thrown by this method

      • copyJDTarAndJarToCloud

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public abstract OSResponse copyJDTarAndJarToCloud()
                                           throws java.io.IOException
        This method should copy the following files to their relevant Cloud Storage Directory:

        • Project.jar
        • Project-JavaDoc.tar
        Returns:
        The output-text and O/S Response-Code generated by invoking this method.
        Throws:
        java.io.IOException - throws if there are any I/O Problems thrown by this method

      • makeJDTarAndJarPublic

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public abstract OSResponse makeJDTarAndJarPublic()
                                          throws java.io.IOException
        This Method should be run if your Cloud-Storage Directory requires your recently copied / synchronized '.tar' & '.jar' files to be explicity made public.
        Returns:
        The output-text and O/S Response-Code generated by invoking this method.
        Throws:
        java.io.IOException - throws if there are any I/O Problems thrown by this method

      • backupMainTarGzFile

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public abstract OSResponse backupMainTarGzFile()
                                        throws java.io.IOException
        This method should copy your Project-Backup.tar File to the appropriate date-based Cloud-Storage Backup-Directory.
        Returns:
        The output-text and O/S Response-Code generated by invoking this method.
        Throws:
        java.io.IOException - throws if there are any I/O Problems thrown by this method

      • copyLogDirToCloud

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public abstract OSResponse copyLogDirToCloud()
                                      throws java.io.IOException
        Copies all files in the User-Supplied 'logs/' Local-Directory to the Cloud Storage Log-Directory.
        Returns:
        The output-text and O/S Response-Code generated by invoking this method.
        Throws:
        java.io.IOException - throws if there are any I/O Problems thrown by this method

      • setCloudLogsContentType

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public abstract OSResponse setCloudLogsContentType()
                                            throws java.io.IOException
        If there is any need to modify the HTTP CONTENT-TYPE Meta-Data, this method should be the one for doing that.
        Returns:
        The output-text and O/S Response-Code generated by invoking this method.
        Throws:
        java.io.IOException - throws if there are any I/O Problems thrown by this method

      • makeLogsPublic

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public abstract OSResponse makeLogsPublic()
                                   throws java.io.IOException
        This Method should be run if your Cloud-Storage Directory requires your recently copied / synchronized Log-Files to be explicity made public.
        Returns:
        The output-text and O/S Response-Code generated by invoking this method.
        Throws:
        java.io.IOException - throws if there are any I/O Problems thrown by this method

      • setMaxAgeAll

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public abstract OSResponse setMaxAgeAll()
                                 throws java.io.IOException
        This method should set the Meta-Information '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.
        Returns:
        The output-text and O/S Response-Code generated by invoking this method.
        Throws:
        java.io.IOException - throws if there are any I/O Problems thrown by this method

      • setMaxAgeSome

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public abstract OSResponse setMaxAgeSome()
                                  throws java.io.IOException
        This does the same thing as setMaxAgeAll(), but it is only executed on the pages that are specified by the recently updated packages array.

        I am going to explain this simply little thing later on.
        Returns:
        The output-text and O/S Response-Code generated by invoking this method.
        Throws:
        java.io.IOException - throws if there are any I/O Problems thrown by this method

      • initStage

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        protected abstract void initStage​(java.lang.Appendable logOnly,
                                  java.lang.Appendable logAndScreen)
        Protected, Internal Method. Initiates a Build-Stage's Log-Output Printing Mechanism.