Class Builder

    • Field Detail

      • HOME_DIR

        🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final java.lang.String HOME_DIR
        Used during the JAR-Build (Stage 4). TO BE EXPLAINED AT A LATER DATE.
        See Also:
        Config.HOME_DIR
        Code:
        Exact Field Declaration Expression:
         public final String HOME_DIR;

      • LOCAL_JAVADOC_DIR

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final java.lang.String LOCAL_JAVADOC_DIR
        This String contains either the absolute, or the relative, path to the on-disk location of the directory where javadoc has left its output.

        Validity-Checking:
        A Directory-Check is not performed by class Config's validate method. Often, when the Builder instance is constructed, the 'javadoc/' output directory does not exist as it hasn't yet been created by the Java-Doc Tool yet.

        'javadoc' isn't run / executed until Build-Stage 2.

        Class Config's validate method will throw NullPointerException if field Config.LOCAL_JAVADOC_DIR has been left null.

        Assigning this Field:
        As can seen in this class' constructor, the value of this constant field is set by directly copying the corresponding field from the Config class instance' field Config.LOCAL_JAVADOC_DIR. This Class' (Builder's) Constructor requires a Config instance as an input parameter.

        Java Line of Code:
        this.LOCAL_JAVADOC_DIR = config.LOCAL_JAVADOC_DIR;
        See Also:
        Config.LOCAL_JAVADOC_DIR
        Code:
        Exact Field Declaration Expression:
         public final String LOCAL_JAVADOC_DIR;

      • PROJECT_NAME

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final java.lang.String PROJECT_NAME
        This is a small name-String for the Project.

        Validity-Checking:
        This field's value is checked for validity by a Regular-Expression validator - publicly available in class Config.

        Class Config's validate method will throw NullPointerException if field Config.PROJECT_NAME has been left null.

        Assigning this Field:
        As can seen in this class' constructor, the value of this constant field is set by directly copying the corresponding field from the Config class instance' field Config.PROJECT_NAME. This Class' (Builder's) Constructor requires a Config instance as an input parameter.

        Java Line of Code:
        this.PROJECT_NAME = config.PROJECT_NAME;
        See Also:
        Config.PROJECT_NAME, Config.projectNameValidator
        Code:
        Exact Field Declaration Expression:
         public final String PROJECT_NAME;

      • VERSION_MAJOR_NUMBER

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final byte VERSION_MAJOR_NUMBER
        The Project must have a "Version Number". In this project - JavaHTML 1.8, at the writing of this JavaDoc Comment the "Major Version Number" is '1', while the "Minor Version Number" is '8'.

        Validity-Checking:
        This number must be a positive integer, and it is checked for validity by class Config's validate method.

        Assigning this Field:
        As can seen in this class' constructor, the value of this constant field is set by directly copying the corresponding field from the Config class instance' field Config.VERSION_MAJOR_NUMBER. This Class' (Builder's) Constructor requires a Config instance as an input parameter.

        Java Line of Code:
        this.VERSION_MAJOR_NUMBER = config.VERSION_MAJOR_NUMBER;
        See Also:
        VERSION_MINOR_NUMBER, Config.VERSION_MAJOR_NUMBER
        Code:
        Exact Field Declaration Expression:
         public final byte VERSION_MAJOR_NUMBER;

      • VERSION_MINOR_NUMBER

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final byte VERSION_MINOR_NUMBER
        The Project-Version Minor-Number.

        Validity-Checking:
        This number must be a positive integer, and it is checked for validity by class Config's validate method.

        Assigning this Field:
        As can seen in this class' constructor, the value of this constant field is set by directly copying the corresponding field from the Config class instance' field Config.VERSION_MINOR_NUMBER. This Class' (Builder's) Constructor requires a Config instance as an input parameter.

        Java Line of Code:
        this.VERSION_MINOR_NUMBER = config.VERSION_MINOR_NUMBER;
        See Also:
        VERSION_MAJOR_NUMBER, Config.VERSION_MINOR_NUMBER
        Code:
        Exact Field Declaration Expression:
         public final byte VERSION_MINOR_NUMBER;

      • JAVAC_BIN

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final java.lang.String JAVAC_BIN
        This must contain the direct path from the current working directory to the 'javac' binary-file. This String-Configuration names the executable used by Build-Stage 1.

        Validity-Checking:
        This parameter is not checked for validity, but the Java-Compiler Build-Stage Class, S01_JavaCompiler, will throw exceptions if this String doesn't point to a valid binary or executable file.

        Class Config's validate method will throw NullPointerException if field Config.JAVAC_BIN has been left null.

        Assigning this Field:
        As can seen in this class' constructor, the value of this constant field is set by directly copying the corresponding field from the Config class instance' field Config.JAVAC_BIN. This Class' (Builder's) Constructor requires a Config instance as an input parameter.

        Java Line of Code:
        this.JAVAC_BIN = config.JAVAC_BIN;
        See Also:
        Config.JAVAC_BIN, S01_JavaCompiler
        Code:
        Exact Field Declaration Expression:
         public final String JAVAC_BIN;

      • JAVADOC_BIN

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final java.lang.String JAVADOC_BIN
        This must contain the direct path from the current working directory to the 'javadoc' binary-file. This String-Configuration names the executable used by Build-Stage 1.

        Validity-Checking:
        This parameter is not checked for validity, but the Javadoc Build-Stage Class, S02_JavaDoc, will throw exceptions if this String doesn't point to a valid binary or executable file.

        Class Config's validate method will throw NullPointerException if field Config.JAVADOC_BIN has been left null.

        Assigning this Field:
        As can seen in this class' constructor, the value of this constant field is set by directly copying the corresponding field from the Config class instance' field Config.JAVADOC_BIN. This Class' (Builder's) Constructor requires a Config instance as an input parameter.

        Java Line of Code:
        this.JAVADOC_BIN = config.JAVADOC_BIN;
        See Also:
        Config.JAVADOC_BIN, S02_JavaDoc
        Code:
        Exact Field Declaration Expression:
         public final String JAVADOC_BIN;

      • JAVA_RELEASE_NUM_SWITCH

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final byte JAVA_RELEASE_NUM_SWITCH
        This Configuration-Field may be used to request that the Build-Tool insert the 'javac' Command-Line Switch '--release XX' to the 'javac' Command Invocation. The release switch asks that the Java-Compiler generate Java Byte-Code that is that is consistent with the Byte-Code for the JDK-Release 'X'.

        If 'X' were passed '11', the Java-Compiler would generate Java Byte-Code that is consistent with the JDK-11 LTS (Released in Year 2018).

        This parameter is not checked for validity, but the Java-Compiler will generate error messages (instead of compiling) if the Release-Number isn't valid. If you are using JDK-11, and pass '21' to this Configuration-Field, 'javac' will obviously complain.

        The default value for this field is '-1'. Any negative number (or zero) assigned to this field will implicitly tell the Stage 1 Builder-Class that using a '--release' switch is not necessary, and should be left off when compiling '.java' Files.

        Assigning this Field:
        As can seen in this class' constructor, the value of this constant field is set by directly copying the corresponding field from the Config class instance' field Config.JAVA_RELEASE_NUM_SWITCH. This Class' (Builder's) Constructor requires a Config instance as an input parameter.

        Java Line of Code:
        this.JAVA_RELEASE_NUM_SWITCH = config.JAVA_RELEASE_NUM_SWITCH;
        See Also:
        Config.JAVA_RELEASE_NUM_SWITCH, S01_JavaCompiler
        Code:
        Exact Field Declaration Expression:
         public final byte JAVA_RELEASE_NUM_SWITCH;

      • FAVICON

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final java.lang.String FAVICON
        Contains FAVICON Image File-Name, to be used by the Stage 3 Build-Class S03_Upgrade. When this Configuration-Field is non-null, the Upgrade-Stage will copy favicon file into the LOCAL_JAVADOC_DIR.

        This Configuration-Field may be null - which is the default value assigned to Config.FAVICON. When it is, no favicon file is copied to the root 'javadoc/' directory.

        Validity-Checking:
        This String-Field, when non-null, is checked whether or not it points to an actual Image-File, that both exists and is accessible on the File-System. Class Config's validate method will throw a FileNotFoundException if this check fails.

        If class IF is unable to properly guess the Image-Type based on its File-Name, then an UnrecognizedImageExtException is thrown by the validator method.

        Assigning this Field:
        As can seen in this class' constructor, the value of this constant field is set by directly copying the corresponding field from the Config class instance' field Config.FAVICON. This Class' (Builder's) Constructor requires a Config instance as an input parameter.

        Java Line of Code:
        this.FAVICON = config.FAVICON;
        See Also:
        Config.FAVICON, S03_Upgrade
        Code:
        Exact Field Declaration Expression:
         public final String FAVICON;

      • TAR_SOURCE_DIR

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final java.lang.String TAR_SOURCE_DIR
        This class specifies the Root Source-Code Directory containing all '.java' Files, '.class' Files, and any configurations needed for the build. The Stage 4 Builder-Class S04_TarJar invokes the OS Command 'tar' around this directory to create a Project Backup-File.

        The name given the Project Tar-Backup File will just be the String provided to PROJECT_NAME, followed by the VERSION_MAJOR_NUMBER and VERSION_MINOR_NUMBER.

        Validity-Checking:
        This String-Field may not be null, or NullPointerException throws. Furthermore the Config validate method will ensure that this String points to a valid and accessible File-System Directory-Name.

        If this isn't a valid directory, a FileNotFoundException will throw. Keep in mind that FileNotFoundException is a Java Checked-Exception which inherits IOException.

        Configuration-Field Use:
        This field is very simply used in the Stage 4 Build-Class S04_TarJar as follows. The following code snippet was copied on March 4th, 2024: 

         // Shell-Constructor Parameters used:
 // (outputAppendable, commandStrAppendable, standardOutput, errorOutput)
 
 Shell shell = new Shell(SB_TAR, new BiAppendable(SB_TAR, System.out), null, null);
 
 // JavaHTML-1.x.tar.gz
 CHECK(
     shell.COMMAND(
         "tar",
         new String[] { "-cvzf", builder.TAR_FILE, builder.TAR_SOURCE_DIR }
 ));


        Assigning this Field:
        As can seen in this class' constructor, the value of this constant field is set by directly copying the corresponding field from the Config class instance' field Config.TAR_SOURCE_DIR. This Class' (Builder's) Constructor requires a Config instance as an input parameter.

        Java Line of Code:
        this.TAR_SOURCE_DIR = config.TAR_SOURCE_DIR;
        See Also:
        Config.TAR_SOURCE_DIR, TAR_FILE, S04_TarJar, S06_SyncTarJar
        Code:
        Exact Field Declaration Expression:
         public final String TAR_SOURCE_DIR;

      • GCS_DIR_DEV

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final java.lang.String GCS_DIR_DEV
        This parameter is used by all four Build-Stages that involve Google Cloud Server / Platform. This parameter may, indeed, remain null and if or when it is, Build-Stages that pertain to GCS Storage-Buckets will not be performed. These stages include 5 through 8.

        This Configuration-Field is not checked for Validity. If it is non-null, but points to / indicates a Google Storage Bucket that isn't valid or isn't writeable, any and all GCP Synchronization Stages will throw exceptions and exit.

        By default, this field is assigned null.

        Amazon S3 & MSFT Azure Storage:
        There is currently no Build-Implementation that can capably synchronize the Build Java-Doc or Archive-File output with 'Amazon S3'. 'S3' is simply AWS' implementation of Network Based Storage, just like GCP Storage.

        The concept is, certainly, on the "To Do" List, but will not be implemented in the immediate future.

        Assigning this Field:
        As can seen in this class' constructor, the value of this constant field is set by directly copying the corresponding field from the Config class instance' field Config.GCS_DIR_DEV. This Class' (Builder's) Constructor requires a Config instance as an input parameter.

        Java Line of Code:
        this.GCS_DIR_DEV = config.GCS_DIR_DEV;
        See Also:
        Config.GCS_DIR_DEV, GCS_DIR_RELEASE, Config.GCS_DIR_RELEASE, S05_SyncJavaDoc, S06_SyncTarJar, S07_SyncLogs
        Code:
        Exact Field Declaration Expression:
         public final String GCS_DIR_DEV;

      • GCS_DIR_RELEASE

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final java.lang.String GCS_DIR_RELEASE
        This Configuration Field is nearly identical in function to GCS_DIR_DEV, but specifies a Storage-Bucket & Directory Location for a "Full Release Version" of the same Project's Documentation-HTML & Jar-Files.

        This Configuration-Field, by default is assigned null, and may remain null at the time that a Builder-Class instance is constructed. When this configuration is null, it is silently ignored. If null, the Upgrade Cloud Storage-Bucket Synchronization Stage for the Release-Directory isn't applied, and becomes "unavailable".

        In this project, Java-HTML, the "Full-Release" Storage-Bucket & Web-Address URL (GCS_DIR_RELEASE) is 'javahtml.torello.directory'.

        The Developer Storage-Bucket Web-Address (GCS_DIR_DEV) is 'developer.torello.directory/JavaHTML/Version' (followed by the Major & Minor Version Release Numbers).

        Having two separate output bucket-directories for copying the Java-Doc Output and Jar-Distribution allows for having a separate URL for daily Project Software Development, and a GCS directory which is updated less frequently for released, CI/CD Distribution.

        Assigning this Field:
        As can seen in this class' constructor, the value of this constant field is set by directly copying the corresponding field from the Config class instance' field Config.GCS_DIR_RELEASE. This Class' (Builder's) Constructor requires a Config instance as an input parameter.

        Java Line of Code:
        this.GCS_DIR_RELEASE = config.GCS_DIR_RELEASE;
        See Also:
        Config.GCS_DIR_RELEASE, GCS_DIR_DEV, Config.GCS_DIR_DEV, S05_SyncJavaDoc, S06_SyncTarJar, S07_SyncLogs
        Code:
        Exact Field Declaration Expression:
         public final String GCS_DIR_RELEASE;

      • RUN_MAKE_PUBLIC

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final boolean RUN_MAKE_PUBLIC
        When using GCP Storage-Buckets for hosting / serving Web & HTTP Content, Google provides an option to assign "Bucket-Level" or "Object-Level" access permissions. When an entire Storage-Bucket has been made public, there is no need to make each HTML-File that resides inside the bucket public. However, if "Object-Level" access permissions have been configured, then each HTML-File also needs to be made public, or Web-Browsers will not be able to see the HTML-Files.

        If you have opted for "Bucket-Level" permissions (everything in your bucket is publicly readable), then calling GSUTIL function Make Public will actually cause this builder to throw an exception. Therefore this boolean should be used to inform the builder whether or not the javadoc HTML Files are already public, as per the GCP Storage-Bucket settings.

        The Storage-Bucket directory to which the "Make Public" operations are precisely the directories listed in GCS_DIR_DEV and GCS_DIR_RELEASE. As per the User's selected target-build CLI Option, Java-Doc HTML-Files are copied to only one of these two bucket directories.

        Assigning this Field:
        This is how the value for this field is computed: 
         this.RUN_MAKE_PUBLIC = this.cli.toReleaseOrDeveloper
     ? config.RUN_MAKE_PUBLIC_RELEASE
     : config.RUN_MAKE_PUBLIC_DEV;
        See Also:
        Config.RUN_MAKE_PUBLIC_DEV, Config.RUN_MAKE_PUBLIC_RELEASE, GCS_DIR_DEV, GCS_DIR_RELEASE
        Code:
        Exact Field Declaration Expression:
         public final boolean RUN_MAKE_PUBLIC;

      • BACKUP_TAR_FILE_GCS_DIR

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final java.lang.String BACKUP_TAR_FILE_GCS_DIR
        This Project '.tar' File that is created out of the Project Root Directory can be automatically copied to a safe location in a Storage-Bucket so that Project-Files are automatically backed up every time they are compiled and documented.

        This Configuration-Field should contain the name of a valid Google Cloud Storage Bucket Directory-Name. When this field is non-null, Build-Stage 6 (S06_SyncTarJar) will automatically copy the Project-Backup '.tar' File to the directory structure indicated by this field.

        Note, first, that this field may be null. If it is null, then the Stage 6 Synchronization Effort to backup the Project-Files will simply be skipped.

        Also, note that the file is actually copied to a sub-directory whose name is created using today's date - the Year, Month & Day - of the running / execution of the Build Command.

        This field is not checked for validity. If a non-null but erroneous Google Cloud Storage-Bucket Directory-Name is provided (or one that exists, but is not writeable) - then the Tar-Synchronization Build-Stage (Stage 6) will fail and throw an exception.

        Visibility:
        If this feature is used, it's usually a good idea to make sure that the directory provided to this field is not publicly visible to 'AllUsers' - otherwise everybody will be capable of downloading the entirety of your development work.

        Full-Path Directory-Name:
        Also, as mentioned above, the backup mechanism actually copies the archive to a subdirectory of the form:

        gs://Some.GCP.Bucket/BACKUP_TAR_FILE_GCS_DIR/2024/03 - March/2024-03-05-JavaHTML-1.8.tar.gz
        Notice that only the date is included in the file-name. The actual system-time for this file is not included! This means that no more than one backup-file (the last file created on any given Calendar-Day) will actually remain in the directory. A file backed up at 3:00 PM will be overwritten if another backup is copied at 5:00 PM on the same day.

        This has turned out to be extremely valuable - as it has meant that all changes made over the course of a single day's work (& typing) are saved - while intermediate modifications are clobbered / overwritten whenever another Build is executed - on the same work-day as the previously executed build.

        Configuration-Field Use:
        The Stage 6 Builder-Class S06_SyncTarJar utilizes this field as follows: 

         final String CODE_DRIVE_BACKUP_FILE = (builder.BACKUP_TAR_FILE_GCS_DIR == null)
 
     ? null 
     :   builder.BACKUP_TAR_FILE_GCS_DIR +
         StringParse.ymDateStr('/', true) + '/' +
         StringParse.dateStr('-') + '-' + builder.TAR_FILE;
 
 // Portion of Code Block Omitted
 
 // Drive backup page
 if (CODE_DRIVE_BACKUP_FILE != null)
 {
     osr = gsutil.CP(builder.TAR_FILE, CODE_DRIVE_BACKUP_FILE);
     Util.HALT_ON_ERROR(osr);
     sw.println();
 }


        For a better understanding, please see:



        Assigning this Field:
        As can seen in this class' constructor, the value of this constant field is set by directly copying the corresponding field from the Config class instance' field Config.BACKUP_TAR_FILE_GCS_DIR. This Class' (Builder's) Constructor requires a Config instance as an input parameter.

        Java Line of Code:
        this.BACKUP_TAR_FILE_GCS_DIR = config.BACKUP_TAR_FILE_GCS_DIR;
        See Also:
        Config.BACKUP_TAR_FILE_GCS_DIR, S06_SyncTarJar
        Code:
        Exact Field Declaration Expression:
         public final String BACKUP_TAR_FILE_GCS_DIR;

      • preUpgraderScript

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final UpgradeProcessor preUpgraderScript
        In Java-HTML there are a few Upgrade-Stage (Stage 3) processes that need to be executed before the actual upgrade can run. All of the processes currently in the 'preUpgraderScript' are on a general "To Do List" for being moved into the actual Upgrade-API.

        This Configuration-Field may be null, and if it is, it is ignored. The Stage 3 Build-Class S03_Upgrade simply runs the following code, below. This snippet was block-copied directly from 'S03_Upgrade.upgrade'. 

         builder.timers.startStage03();
 
 Printing.startStep(3);
 
 // This is used as a Log-File Collector
 StringBuilder sb = new StringBuilder();
 
 // Check if there is a User-Provided "Pre-Upgrade Script", if so, then run it.
 if (builder.preUpgraderScript != null) builder.preUpgraderScript.accept(builder, sb);
 
 sb.append("... Note to Console about Starting Build ...");
 
 // And now start the actual Upgrade
 Stats result = builder.upgrader.upgrade();


        Clearly, a validity check on this Configuration-Field isn't possible.

        Assigning this Field:
        As can seen in this class' constructor, the value of this constant field is set by directly copying the corresponding field from the Config class instance' field Config.preUpgraderScript. This Class' (Builder's) Constructor requires a Config instance as an input parameter.

        Java Line of Code:
        this.preUpgraderScript = config.preUpgraderScript;
        See Also:
        Config.preUpgraderScript, postUpgraderScript, Config.postUpgraderScript, S03_Upgrade
        Code:
        Exact Field Declaration Expression:
         public final UpgradeProcessor preUpgraderScript;

      • extraSwitchesJAVAC

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final ReadOnlyList<java.lang.String> extraSwitchesJAVAC
        Setting values for this String[]-Array allows a user to provide extra or additional Command-Line switches to the Java-Compiler if it is invoked.

        Validity Checking:
        No validity checks are done for the contents of these 'javac' "Extra Switches". However, if any faulty or erroneous switch elements in the User-Provided String[]-Array are provided, then the Stage 1 Build-Class S01_JavaCompiler will likely through exceptions when if it is invoked.

        Copying Config.extraSwitchesJAVAC:
        The following is how this field is copied from the contents of class Config (a User-Provided class): 

         // Config.extraSwitchesJAVAC     ==> String[]
 // Builder.extraSwitchesJAVAC    ==> ReadOnlyList<String>
 
 this.extraSwitchesJAVAC =
     ((config.extraSwitchesJAVAC == null) || (config.extraSwitchesJAVAC.length == 0))
          ? null
          : ReadOnlyList.of(config.extraSwitchesJAVAC);
        See Also:
        Config.extraSwitchesJAVAC, ReadOnlyList, S01_JavaCompiler
        Code:
        Exact Field Declaration Expression:
         public final ReadOnlyList<String> extraSwitchesJAVAC;

      • extraSwitchesJAVADOC

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final ReadOnlyList<java.lang.String> extraSwitchesJAVADOC
        Setting values for this String[]-Array allows a user to provide extra or additional Command-Line switches to the 'javadoc' Tool if it is invoked.

        Validity Checking:
        No validity checks are done for the contents of these 'javadoc' "Extra Switches". However, if any faulty or erroneous switch elements in the User-Provided String[]-Array are provided, then the Stage 2 Build-Class S02_JavaDoc will likely through exceptions when if it is invoked.

        Copying Config.extraSwitchesJAVADOC:
        The following is how this field is copied from contents of User-Provided class Config: 

         // Config.extraSwitchesJAVADOC     ==> String[]
 // Builder.extraSwitchesJAVADOC    ==> ReadOnlyList<String>
 
 this.extraSwitchesJAVADOC =
     ((config.extraSwitchesJAVADOC == null) || (config.extraSwitchesJAVADOC.length == 0))
          ? null
          : ReadOnlyList.of(config.extraSwitchesJAVADOC);
        See Also:
        Config.extraSwitchesJAVADOC, ReadOnlyList, S02_JavaDoc
        Code:
        Exact Field Declaration Expression:
         public final ReadOnlyList<String> extraSwitchesJAVADOC;

      • TAR_FILE

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final java.lang.String TAR_FILE
        The Computed File-Name for the Project-Wide '.tar' Backup-File.

        This Configuration-Field is computed using other fields, and cannot be "supplied" by the User. Below is the code used to generate this File-Name / Field. 

         // For Java-HTML, this would be, (for example) - "1.8"
 final String NUM = VERSION_MAJOR_NUMBER + "." + VERSION_MINOR_NUMBER;
 
 // For Project "JavaHTML", this would be "JavaHTML-1.8.tar.gz"
 this.TAR_FILE = this.PROJECT_NAME + "-" + NUM + ".tar.gz";
        See Also:
        PROJECT_NAME, VERSION_MAJOR_NUMBER, VERSION_MINOR_NUMBER, S04_TarJar, S06_SyncTarJar
        Code:
        Exact Field Declaration Expression:
         public final String TAR_FILE;

      • JAR_FILE

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final java.lang.String JAR_FILE
        The Computed File-Name for the Project's Distribution '.jar' File.

        This Configuration-Field is computed using other fields, and cannot be "supplied" by the User. Below is the code used to generate this File-Name / Field. 

         // For Java-HTML, this would be, (for example) - "1.8"
 final String NUM = VERSION_MAJOR_NUMBER + "." + VERSION_MINOR_NUMBER;
 
 // For Project "JavaHTML", this would be "JavaHTML-1.8.jar"
 this.JAR_FILE = this.PROJECT_NAME + "-" + NUM + ".jar";
        See Also:
        PROJECT_NAME, VERSION_MAJOR_NUMBER, VERSION_MINOR_NUMBER, S04_TarJar, S06_SyncTarJar
        Code:
        Exact Field Declaration Expression:
         public final String JAR_FILE;

      • JAVADOC_TAR_FILE

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final java.lang.String JAVADOC_TAR_FILE
        The Computed File-Name for the Project's Javadoc Documentation '.tar.gz' File.

        This Configuration-Field is computed using other fields, and cannot be "supplied" by the User. Below is the code used to generate this File-Name / Field. 

         // For Java-HTML, this would be, (for example) - "1.8"
 final String NUM = VERSION_MAJOR_NUMBER + "." + VERSION_MINOR_NUMBER;
 
 // For Project "JavaHTML", this would be "JavaHTML-javadoc-1.8.tar"
 this.JAVADOC_TAR_FILE = this.PROJECT_NAME + "-javadoc-" + NUM + ".tar";
        See Also:
        PROJECT_NAME, VERSION_MAJOR_NUMBER, VERSION_MINOR_NUMBER, S04_TarJar, S06_SyncTarJar
        Code:
        Exact Field Declaration Expression:
         public final String JAVADOC_TAR_FILE;

      • CLASS_PATH_STR

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final java.lang.String CLASS_PATH_STR
        This is the classpath that is passed to the Stage 1 Build-Class S01_JavaCompiler.

        This field's value is computed and assigned by a package-only visible initializer method in class Config.
        See Also:
        S01_JavaCompiler
        Code:
        Exact Field Declaration Expression:
         public final String CLASS_PATH_STR;

      • USE_XLINT_SWITCH

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final boolean USE_XLINT_SWITCH
        The helps the Build-Logic decide whether to use the Java-Compiler Switch -Xlint:all. The default behavior is that the Java-Compiler will be invoked using that switch for all '.java' Files that are being compiled.

        The default behavior assigned in Configuration-Class Config can easily be changed by reassigning the necessary value to field Config.USE_XLINT_SWITCH. When this field is reassiged a new boolean, any invocation of the Builder's Java-Compiler Stage will check whether to use the -Xlint:all, based on this field's value.

        On top of Config.USE_XLINT_SWITCH, a user has the option of passing the Command-Line Wwitch -TXL when invoking the Java-Compiler Build-Stage which, in effect, toggles whatever value was set by the original Config.USE_XLINT_SWITCH setting. (This may be done when invoking 'Builder' from the CLI).

        This may be more clearly seen in the code used to assign this field's value: 

         this.USE_XLINT_SWITCH = this.cli.OVERRIDE_TOGGLE_USE_XLINT_SWITCH
     ? (! config.USE_XLINT_SWITCH)
     : config.USE_XLINT_SWITCH;
        See Also:
        Config.USE_XLINT_SWITCH, CLI.OVERRIDE_TOGGLE_USE_XLINT_SWITCH, S01_JavaCompiler
        Code:
        Exact Field Declaration Expression:
         public final boolean USE_XLINT_SWITCH;

      • USE_XDIAGS_SWITCH

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final boolean USE_XDIAGS_SWITCH
        The helps the Build-Logic decide whether to use the Java-Compiler Switch -Xdiags:verbose. The default behavior is that the Java-Compiler will be invoked using that switch for all '.java' Files that are being compiled.

        The default behavior assigned in Configuration-Class Config can easily be changed by reassigning the necessary value to field Config.USE_XDIAGS_SWITCH. When this field is reassiged a new boolean, any invocation of the Builder's Java-Compiler Stage will check whether to use the -Xdiags:verbose, based on this field's value.

        On top of Config.USE_XDIAGS_SWITCH, a user has the option of passing the Command-Line Wwitch -TXL when invoking the Java-Compiler Build-Stage which, in effect, toggles whatever value was set by the original Config.USE_XDIAGS_SWITCH setting. (This may be done when invoking 'Builder' from the CLI).

        This may be more clearly seen in the code used to assign this field's value: 

         this.USE_XDIAGS_SWITCH = this.cli.OVERRIDE_TOGGLE_USE_XDIAGS_SWITCH
     ? (! config.USE_XDIAGS_SWITCH)
     : config.USE_XDIAGS_SWITCH;
        See Also:
        Config.USE_XDIAGS_SWITCH, CLI.OVERRIDE_TOGGLE_USE_XDIAGS_SWITCH, S01_JavaCompiler
        Code:
        Exact Field Declaration Expression:
         public final boolean USE_XDIAGS_SWITCH;

      • NO_JAVADOC_FRAMES_SWITCH

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final boolean NO_JAVADOC_FRAMES_SWITCH
        Requests that the --frames switch, which by default is passed to the Stage 2 Build-Class S02_JavaDoc be omitted.

        By default, this Configuration-Field is assigned FALSE, which means that the --frames switch, by default, s passed to the javadoc stage.

        Make sure to remember that after the JDK 11 Release, the --frames switch was fully deprecated and removed from the tool. In such cases, make sure to assign TRUE to the field Config.NO_JAVADOC_FRAMES_SWITCH, or the Stage 2 Build-Class will throw an exception.

        Assigning this Field:
        As can seen in this class' constructor, the value of this constant field is set by directly copying the corresponding field from the Config class instance' field Config.NO_JAVADOC_FRAMES_SWITCH. This Class' (Builder's) Constructor requires a Config instance as an input parameter.

        Java Line of Code:
        this.NO_JAVADOC_FRAMES_SWITCH = config.NO_JAVADOC_FRAMES_SWITCH;
        See Also:
        Config.NO_JAVADOC_FRAMES_SWITCH, S02_JavaDoc
        Code:
        Exact Field Declaration Expression:
         public final boolean NO_JAVADOC_FRAMES_SWITCH;

      • packageList

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final ReadOnlyList<BuildPackage> packageList
        This Configuration is largely copied, directly, from the User-Provided Config class instance received. This Configuration-Field simply contains the list of packages that comprise the Java Project being built, compiled, documented & sychronized.

        Class Config-Field Config.packageList contains a User-Provided list of packages, as instances of BuildPackage.

        There isn't any validation done on the input array, other than that it must be non-null, and contain at least Java Package.

        Quick Build Note:
        The option to eliminate certain packages when doing a build is provided by class BuildPackage. The BuildPackage Static-Flag BuildPackage.QUICKER_BUILD_SKIP lets a user convey that, during development time, the compilation and documentation stages can skip certain packages altogether.

        Note that if class CLI has specified its CLI.QUICKER_BUILD field, then and only then, are packages designed as BuildPackage.skipIfQuickerBuild actually removed.

        Under Development Note:
        The option to eliminate certain packages because they are still under development is an option also provided by the class BuildPackage (via the EARLY_DEVELOPMENT flag, and by the earlyDevelopment field), and by the class CLI (via the INCLUDE_EARLY_DEV_PACKAGES field).

        Assigning this Field:
        This field's reference/value is assigned in this class constructor as in the code included below. The value is generated by the class / method: packagesInThisBuild. 

         // This eliminates any packages that are irrelevant, as per the specifications
 // by the User at the Command-Line Interface 'argv' parameter.
 // 
 // The included packages are in:    "Ret2.a"
 // The eliminated packages are in:  "Ret2.b"
 
 Ret2<ReadOnlyList<BuildPackage>, ReadOnlyList<BuildPackage>> ret2 =
     Packages.packagesInThisBuild(this.cli, config.packageList);
 
 // This is used in S01_JavaCompiler, S02_JavaDoc and S04_TarJar
 this.packageList = ret2.a;
        See Also:
        Packages.packagesInThisBuild(CLI, BuildPackage[]), Config.packageList, CLI.QUICKER_BUILD, BuildPackage.QUICKER_BUILD_SKIP, BuildPackage.skipIfQuickerBuild
        Code:
        Exact Field Declaration Expression:
         public final ReadOnlyList<BuildPackage> packageList;

      • jarIncludes

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final ReadOnlyList<Torello.Java.Build.JarInclude.Descriptor> jarIncludes
        Additional & Miscellaneous Files that must be incorporated into the Project's '.jar' File.

        This Configuration-Field's value is computed by using package-private initializer code, as follows: 

         this.jarIncludes = (config.jarIncludes != null)
     ? config.jarIncludes.getAllDesriptors()
     : null;
        See Also:
        Config.jarIncludes, S04_TarJar
        Code:
        Exact Field Declaration Expression:
         public final ReadOnlyList<JarInclude.Descriptor> jarIncludes;

      • cli

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final CLI cli
        This is generated by parsing the Command-Line Arguments passed to this class constructor. Class CLI's constructor accepts an 'argv' parameter, which should have been obtained from an invocation of any public static void main method.

    • Constructor Detail

      • Builder

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public Builder​(Config config,
               java.lang.String... argv)
        throws java.io.FileNotFoundException,
               java.io.IOException
        Run this class constructor, and afterwards the build() method can be invoked.
        Parameters:
        config - Any instance of class Config
        argv - Any String[]-Array instance that has been obtained from any invocation of a public static void main method.
        Throws:
        java.io.FileNotFoundException - Throw by the class Config validate method if there are problems with the user's provided configurations.
        java.io.IOException

    • Method Detail

      • build

        🡅  ⇈  ⮫ 🗕  🗗  🗖 
        public void build()
           throws java.io.IOException
        Runs the build. Uses all configurations that were passed to this class constructor.
        Throws:
        java.io.IOException - There are many, many wonderful opportunities for this exception to throw
        Code:
        Exact Method Body:
         // Timers.start[0] is how the "Total Timer Count" is computed.  So 'touch it', and things
 // can start counting right from here.

 this.timers.touch();

 // Pushing it out to JavaHTML shouldn't happen all the time, only once in a while
 if (this.cli.toReleaseOrDeveloper) if (! Q.YN("Are You Sure?")) System.exit(0);

 switch (cli.MENU_CHOICE)
 {
     // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
     // COMPILER STEP
     // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

     case "1"    :   S01_JavaCompiler.compile(this);
                     break;


     // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
     // MAIN STEPS
     // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

     case "2"    :   S02_JavaDoc.javaDoc(this);      break;
     case "3"    :   S03_Upgrade.upgrade(this);      break;
     case "4"    :   S04_TarJar.compress(this);      break;
     case "5"    :   S05_SyncJavaDoc.sync(this);     break;
     case "6"    :   S06_SyncTarJar.sync(this);      break;
     case "7"    :   S07_SyncLogs.sync(this);        break;
     case "8"    :   S08_SetMaxAge.set(this);        break;


     // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
     // COMPOSITE STEPS - Complete Build's  (composed from the 8 steps above)
     // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

     // [Standard Build] - Steps #2 - #7
     case "cb1"  :   S02_JavaDoc.javaDoc(this);
                     S03_Upgrade.upgrade(this);
                     S04_TarJar.compress(this);
                     S05_SyncJavaDoc.sync(this);
                     S06_SyncTarJar.sync(this);
                     S07_SyncLogs.sync(this);
                     break;

     // [Standard Build, Set Max-Age] - Steps #2 - #8
     case "cb2" :    S02_JavaDoc.javaDoc(this);
                     S03_Upgrade.upgrade(this);
                     S04_TarJar.compress(this);
                     S05_SyncJavaDoc.sync(this);
                     S06_SyncTarJar.sync(this);
                     S07_SyncLogs.sync(this);
                     S08_SetMaxAge.set(this);
                     break;

     // [Standard Build] - Steps #2 - #7
     case "cb3" :    S02_JavaDoc.javaDoc(this);
                     S03_Upgrade.upgrade(this);
                     S04_TarJar.compress(this);
                     S05_SyncJavaDoc.sync(this);
                     S06_SyncTarJar.sync(this);
                     S07_SyncLogs.sync(this);
                     break;


     // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
     // COMPOSITE STEPS - Debug-Build's  (composed from the 8 steps above)
     // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

     // [Build Only, No GCS Copying] - Steps #2, #3
     case "pb1"  :   S02_JavaDoc.javaDoc(this);
                     S03_Upgrade.upgrade(this);
                     break;

     // [Build, Copy Docs Only, Set Max-Age] - Steps #2, #3, #5, #8
     case "pb2"  :   S02_JavaDoc.javaDoc(this);
                     S03_Upgrade.upgrade(this);
                     S05_SyncJavaDoc.syncPart(this);
                     S08_SetMaxAge.set(this);
                     break;


     // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
     // Run one of the special cases
     // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

     // Links-Checker Steps #2, #3
     case "lc"   :   if (1 == 1) throw new Torello.Java.ToDoException();
                     S02_JavaDoc.javaDoc(this);
                     // S03_Upgrade.upgradeWLC(U, ES, OS);
                     break;


     // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
     // DEFAULT - PRINT HELP AND EXIT
     // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

     default :   throw new UnreachableError();
 }

 this.timers.PRINT_TIMES();