Class AuxiliaryOptRecord

  • public class AuxiliaryOptRecord
extends java.lang.Object
    This class contains an internally used boolean-Flag field corresponding to each of the Auxiliary Command-Line Options / Switches available by this Build-Tool.

    Internally-Used Class: The exposed API here is not needed to the End-User.

    This class is generated, internally, as a Configuration-Class to be passed to the 8 Build-Stages which are executed by this Build-Tool. The contents of this class have been thoroughly documented and explained, solely for the purpose of explaining, exactly, the steps this Tool is taking during a Build!

    This class is not declared Package-Private in order to facilitate providing a more detailed explanation of what this Build-Tool entails, and not because it is important to the End-User when running a build.

    Obtaining a Reference:
    A reference to the Object-Instance being used in your build for this Class may be obtained by referencing the BuilderRecord Field named 'cli', and then referencing that class 'aor' Field.

    Here is an example of how to run a build, and view the contents of this class before after the Command-Line Options have all been processed, but before the actual building steps have begun:

    Example:
    public static void main(String[] argv) throws Exception
{
    Config config = new Config();


    // There are dozens of possible configurations to make in this class.  Suffice it to say
    // some are more important than others.  Providing a long list of example configurations
    // inside this particular method would, sort-of, obfuscate this particular explanation.
    // Configuring an instance of class 'config' merely involves assigning values to any or
    // all of it's public fields.

    makeMyConfigurations(config);


    // Once configured, you may now initiate a build.  Make sure the accept the actual 
    // command-line arguments that were passed by the user to the 'argv' parameter.

    BuilderRecord brec = config.createBuilder(argv);


    // At this point, a class' reference to this class is now available
    // Here you may print, or even view the view the public-fields

    System.out.println(brec.cli.aor.toString());

    // You may run the build, if you like, using the command:
    // RunBuild.run(brec);
}


    This record is used to help convert Command-Line Switches into boolean-Constants. These final-boolean fields are used inside:

    • Inside class CLI's Constructor
    • The class BuilderRecord's constructor
    • Inside of the 8 various stages of this Build-Tool


    This Record does help "keep clear" which Auxiliary-Switches are offered. There is also an Error-Checking class for this record. The class (ErrorCheckAuxOpts) checks each of the field in this class corresponds to EXACTLY ONE of the available "Auxiliary Options" that may be entered into the Command-Line or "Terminal Window".

    This class will do nothing more than copy these switches into a Read-Only Record. Since the new JDK-21 Records are, indeed, "ReadOnly" - this class will possibly be converted into a JDK-Record (instead of class), but not today. Right now, JDK-11 has its benefits too. I am stuck in Java 11, and I'm not exactly sure when I will be able to transition. Certainly this year, though.
    See Also:
    SelectedOptionsRecord


    • Field Detail

      • NO_QUICK_BUILD_SWITCH

        🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final boolean NO_QUICK_BUILD_SWITCH
        To-Do: Create a detailed explanation of this sick little bugger.

        Internally-Used, Declared Public
        Class CLI is part of this Build-Package's Publicly-Exposed API, primarily for conveying how the Tool works, rather than for utility. This field is used internally, but is declared public primarily for scenario's where a further investigation for this Tool's internal operations is needed.

        The value assigned to this field is determined by the selections and values that where assigned to class Config's Configuration-Fields, when "juxtaposed and analyzed" with respect to User-Selected Command-Line Switches which have been passed (at the command line) to the user's 'public static void main(String[] argv)' argv (String[]-Array) parameter.
        See Also:
        BuildPackage.QUICKER_BUILD_SKIP
        Code:
        Exact Field Declaration Expression:
         public final boolean NO_QUICK_BUILD_SWITCH;

      • INCLUDE_JAR_IN_CP_SWITCH

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final boolean INCLUDE_JAR_IN_CP_SWITCH
        One of the Primary Build-Goals for this Build-Package is to generate a standard Java '.jar'-File from your Source-Code. If you feel you have changed something in your code, and need to use the classes that are contained within your previously constructed '.jar'-File in your class-path, there is an Auxiliary-Menu Option for this.

        How it's Used:
        If the user has passed the '-JCP' Parameter at the Command-Line, then this boolean-Field will be assigned TRUE, and the Stage-01 'javac' invocation will include whatever '.jar'-File in the Class-Path when it executes / runs 'javac' on your '.java' Source-Code Files.

        Internally-Used, Declared Public
        Class CLI is part of this Build-Package's Publicly-Exposed API, primarily for conveying how the Tool works, rather than for utility. This field is used internally, but is declared public primarily for scenario's where a further investigation for this Tool's internal operations is needed.

        The value assigned to this field is determined by the selections and values that where assigned to class Config's Configuration-Fields, when "juxtaposed and analyzed" with respect to User-Selected Command-Line Switches which have been passed (at the command line) to the user's 'public static void main(String[] argv)' argv (String[]-Array) parameter.

      • SKIP_REMOVE_GCS_FILES_SWITCH

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final boolean SKIP_REMOVE_GCS_FILES_SWITCH
        One of the really powerful advantages to using this Build-Tool, is that re-compiling and updating your doc-files to your web-site can all be done with one single Command-Line invocation. This means your development process moves along nearly as fast the JDK's 'javac'-Command.

        In all honesty, the slowest part of the Java-HTML Build Process is copying 10,000 Java-Doc '.html' Files to the appropriate Google Storage-Bucket. If you have a Web-Address that is used for making your Source-Documentation Publicly-Visibly where it is not mission-critical to first remove all of the older documentation pages that are already present inside the Storage-Bucket's directories - you may pass the Command-Line switch '-SRG' to your build, and the "Remove the Old Files" procedure will be skipped.

        In Java-HTML, compiling, documenting and synchronizing all of the generated JavaDoc-Files to the Web can take upwards of 2.5 minutes. Passing the '-SRG' switch can shave off up to 30 seconds of Command-Line Wait-Time.

        How it's Used:
        This field will be assigned TRUE precisely when the '-SRG' Command-Line Switch has been passed to the String[] argv String[]-Array Parameter.

        When this Configuration-Field has been assigned FALSE, it will be comletel ignored, and the standard routine of deleting the old 'html'-Files from your Web-Domain's Storage-Buckets (your "original"), will be removed before the new '.html'-Files are copied.

        However, when this field is assigned TRUE, the Stage-5 Build-Logic will skip the removal of old '.html'-Files from your Bucket-Directories.

        As your '.jar'-File grows in size, this can save you several seconds of wating and staring at your Command-Line / Terminal Text-Output (waiting for you Build to finish, so you can see what the doc's look like).

        Internally-Used, Declared Public
        Class CLI is part of this Build-Package's Publicly-Exposed API, primarily for conveying how the Tool works, rather than for utility. This field is used internally, but is declared public primarily for scenario's where a further investigation for this Tool's internal operations is needed.

        The value assigned to this field is determined by the selections and values that where assigned to class Config's Configuration-Fields, when "juxtaposed and analyzed" with respect to User-Selected Command-Line Switches which have been passed (at the command line) to the user's 'public static void main(String[] argv)' argv (String[]-Array) parameter.

      • OVERRIDE_TOGGLE_USE_XLINT_SWITCH

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final boolean OVERRIDE_TOGGLE_USE_XLINT_SWITCH
        This Build-Package's Command-Line Interface, as explained at the top of this '.html' Page, will accept the flag '-TXL'.

        The class Config has a User-Assignable Boolean-Field called, simply, Config.USE_XLINT_SWITCH. When this Build-Tool is configured such that this Configuration-Field is assigned TRUE, the Stage-1 Compilation 'javac' Stage will be executed with the included switch '-Xlint:all,-processing'.

        This can often help spot bugs which, according the JDK are not errors, just warnings (for instance), by halting the build when they occur. If you have a preference, then simply assigned TRUE or FALSE to the Config instance that is passed to class Builder.

        Now, in the event that this 'javac' switch is forcing your Build too fail, and you would like compile with such warnings anyway, you may pass the switch '-TXL' at the Command-Line, at it will 'toggle' whatever assigned Boolean-Value was provided to class Config in your '.java' Source-File.

        Note that this also means that if you have this Compiler-Flag turned off by default, it may be temporarily "activated" at the Command-Line by passing the switch '-TXL' when you invoke class Builder.

        How it's Used:
        The value of this particular Boolean-Field will be TRUE when the switch was identified by the Apache-CLI Options-Processing code. It will be assigned FALSE (in this class, CLI, constructor) - when the switch is not present.

        The Build Stage-1 'javac' Build-Step will decide whether or not to employ the '-Xlint:all,-processing' switch based on the value assigned to BOTH the Config.USE_XLINT_SWITCH AND the value assigned this field, as well.

        Again, when this field is TRUE, it just requests that the value stored to Config.USE_XLINT_SWITCH be toggled before being interpreted by the Stage 01 Build-Step ('javac').

        Internally-Used, Declared Public
        Class CLI is part of this Build-Package's Publicly-Exposed API, primarily for conveying how the Tool works, rather than for utility. This field is used internally, but is declared public primarily for scenario's where a further investigation for this Tool's internal operations is needed.

        The value assigned to this field is determined by the selections and values that where assigned to class Config's Configuration-Fields, when "juxtaposed and analyzed" with respect to User-Selected Command-Line Switches which have been passed (at the command line) to the user's 'public static void main(String[] argv)' argv (String[]-Array) parameter.
        See Also:
        Config.USE_XLINT_SWITCH
        Code:
        Exact Field Declaration Expression:
         public final boolean OVERRIDE_TOGGLE_USE_XLINT_SWITCH;

      • OVERRIDE_TOGGLE_USE_XDIAGS_SWITCH

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final boolean OVERRIDE_TOGGLE_USE_XDIAGS_SWITCH
        This Build-Package's Command-Line Interface, as explained at the top of this '.html' Page, will accept the flag '-TXD'.

        This field is nearly identical to the final Boolean-Field, above, OVERRIDE_TOGGLE_USE_XLINT_SWITCH. This field is used to 'toggle' the User-Provided setting, passed by to class Config, assigned to the field Config.USE_XDIAGS_SWITCH.

        In the exact same fashion as Config.USE_XLINT_SWITCH, when the field Config.USE_XDIAGS_SWITCH is TRUE, it means that the Stage-1 Build-Logic should include the Command-Line switch '-Xdiags:verbose' when executing 'javac'. Quite a bit of useful information can, occasionally, be made available by the 'javac' command (by passing this switch to 'javac' at its Command-Line).

        However, when it is spitting out warnings, it also means your compilation stage will be prematurely halted.

        How it's Used:
        The value of this particular Boolean-Field will be TRUE when the switch was identified by the Apache-CLI Options-Processing code. It will be assigned FALSE (in this class, CLI, constructor) - when the switch is not present.

        The Build Stage-1 'javac' Build-Step will decide whether or not to employ the '-Xdiags:verbose' switch based on the value assigned to BOTH the Config.USE_XDIAGS_SWITCH AND the value assigned this field, as well.

        Again, when this field is TRUE, it just requests that the value stored to Config.USE_XDIAGS_SWITCH be toggled before being interpreted by the Stage 01 Build-Step ('javac').

        Internally-Used, Declared Public
        Class CLI is part of this Build-Package's Publicly-Exposed API, primarily for conveying how the Tool works, rather than for utility. This field is used internally, but is declared public primarily for scenario's where a further investigation for this Tool's internal operations is needed.

        The value assigned to this field is determined by the selections and values that where assigned to class Config's Configuration-Fields, when "juxtaposed and analyzed" with respect to User-Selected Command-Line Switches which have been passed (at the command line) to the user's 'public static void main(String[] argv)' argv (String[]-Array) parameter.
        See Also:
        Config.USE_XDIAGS_SWITCH
        Code:
        Exact Field Declaration Expression:
         public final boolean OVERRIDE_TOGGLE_USE_XDIAGS_SWITCH;

      • INCLUDE_EARLY_DEV_PACKAGES_SWITCH

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final boolean INCLUDE_EARLY_DEV_PACKAGES_SWITCH
        Adding a new Java-Package to a CI/CD: Continuous-Integraton / Continuous-Delivery Build-System can be somewhat un-nerving. If you would like to add a new Package - but occasionally want to leave it out of the Publicly-Visible Synchronization-Stages, then mark your packages (in class BuildPackage) with the BuildPackage.EARLY_DEVELOPMENT Flag.

        Using the Command-Line Switch "-IED", you will be able to include or exclude such appropriately flagged Java-Packages as you see fit.

        How it's Used:
        The value assigned to this field will be TRUE precisely when the Build Switch "-IED" has been passed at the Command-Line.

        When this field has been assigned FALSE, it will be ignored, completely by the Build-Logic. However, when it is assigned TRUE, any of your Java-Packages that have been configured with the BuildPackage.EARLY_DEVELOPMENT-Flag will be 'elided' (to use a new, JDK-21+ term) or 'eliminated' completely from your Build-Process.

        Internally-Used, Declared Public
        Class CLI is part of this Build-Package's Publicly-Exposed API, primarily for conveying how the Tool works, rather than for utility. This field is used internally, but is declared public primarily for scenario's where a further investigation for this Tool's internal operations is needed.

        The value assigned to this field is determined by the selections and values that where assigned to class Config's Configuration-Fields, when "juxtaposed and analyzed" with respect to User-Selected Command-Line Switches which have been passed (at the command line) to the user's 'public static void main(String[] argv)' argv (String[]-Array) parameter.
        See Also:
        BuildPackage.EARLY_DEVELOPMENT
        Code:
        Exact Field Declaration Expression:
         public final boolean INCLUDE_EARLY_DEV_PACKAGES_SWITCH;

      • JAR_FILE_ONLY_SWITCH

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final boolean JAR_FILE_ONLY_SWITCH
        For Menu-Option #4, "Run Archive-Stage - generate '.tar' and '.jar' Files", the user amy provided a Command-Line Switch "-JFO". This switch allows a user to request that only a Java '.jar'-File be generated, and that the Java-Doc 'tar'-File and the Project Source-Code Archive '.tar'-File be skipped.

        This Auxiliary-Switch can only be applied if the Main-Menu Choice that has been provided is Command-Line Option "-4", or the Composite-Stage Command-Line Option for Stages "-1" through "-4" has been entered.

        If neither of these two Menu-Options were entered at the termainal / Command-Line Interface, then this Build-Tool will print the Help-Menu and report that an error has occurred.

        Internally-Used, Declared Public
        Class CLI is part of this Build-Package's Publicly-Exposed API, primarily for conveying how the Tool works, rather than for utility. This field is used internally, but is declared public primarily for scenario's where a further investigation for this Tool's internal operations is needed.

        The value assigned to this field is determined by the selections and values that where assigned to class Config's Configuration-Fields, when "juxtaposed and analyzed" with respect to User-Selected Command-Line Switches which have been passed (at the command line) to the user's 'public static void main(String[] argv)' argv (String[]-Array) parameter.

    • Method Detail

      • toString

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public java.lang.String toString()
        Converts 'this' instance to a java.lang.String
        Overrides:
        toString in class java.lang.Object
        Returns:
        This class represented as a String.
        Code:
        Exact Method Body:
         return 
     BCYAN + "this.NO_QUICK_BUILD_SWITCH                 " + RESET +
         NO_QUICK_BUILD_SWITCH + "\n" +

     BCYAN + "this.INCLUDE_JAR_IN_CP_SWITCH              " + RESET +
         INCLUDE_JAR_IN_CP_SWITCH + "\n" +

     BCYAN + "this.SKIP_REMOVE_GCS_FILES_SWITCH:         " + RESET +
         SKIP_REMOVE_GCS_FILES_SWITCH + "\n" +

     BCYAN + "this.OVERRIDE_TOGGLE_USE_XLINT_SWITCH:     " + RESET +
         OVERRIDE_TOGGLE_USE_XLINT_SWITCH + "\n" +

     BCYAN + "this.OVERRIDE_TOGGLE_USE_XDIAGS_SWITCH:    " + RESET +
         OVERRIDE_TOGGLE_USE_XDIAGS_SWITCH + "\n" +

     BCYAN + "this.INCLUDE_EARLY_DEV_PACKAGES_SWITCH:    " + RESET +
         INCLUDE_EARLY_DEV_PACKAGES_SWITCH + "\n" +

     BCYAN + "this.JAR_FILE_ONLY_SWITCH:                 " + RESET +
         JAR_FILE_ONLY_SWITCH + "\n";

      • equals

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public boolean equals​(java.lang.Object o)
        Check's for equality between 'this' instance, and any other instance of java.lang.Object
        Overrides:
        equals in class java.lang.Object
        Parameters:
        o - Any Java Object-Reference. Only an instance of class AuxiliaryOptRecord will generate a return-value of TRUE, and particularly only one whose fields are all equal to the corresponding fields in 'this' instance.
        Returns:
        TRUE if and only if 'o' and 'this' are equal, as explained above.
        Code:
        Exact Method Body:
         if (! (o instanceof AuxiliaryOptRecord)) return false;

 AuxiliaryOptRecord other = (AuxiliaryOptRecord) o;

 return 
         (this.NO_QUICK_BUILD_SWITCH ==
             other.NO_QUICK_BUILD_SWITCH)
    
     &&  (this.INCLUDE_JAR_IN_CP_SWITCH ==
             other.INCLUDE_JAR_IN_CP_SWITCH)

     &&  (this.SKIP_REMOVE_GCS_FILES_SWITCH ==
             other.SKIP_REMOVE_GCS_FILES_SWITCH)

     &&  (this.OVERRIDE_TOGGLE_USE_XLINT_SWITCH ==
             other.OVERRIDE_TOGGLE_USE_XLINT_SWITCH)

     &&  (this.OVERRIDE_TOGGLE_USE_XDIAGS_SWITCH ==
             other.OVERRIDE_TOGGLE_USE_XDIAGS_SWITCH)

     &&  (this.INCLUDE_EARLY_DEV_PACKAGES_SWITCH ==
             other.INCLUDE_EARLY_DEV_PACKAGES_SWITCH)

     &&  (this.JAR_FILE_ONLY_SWITCH ==
             other.JAR_FILE_ONLY_SWITCH);

      • hashCode

        🡅  ⇈  ⮫ 🗕  🗗  🗖 
        public int hashCode()
        Generates a Hash-Code for use with Standard-Java Hashtable's etc...
        Overrides:
        hashCode in class java.lang.Object
        Returns:
        A (somewhat) unique Hash-Code, to be used for placing an instance of this class into any variant of Hash-Table.
        Code:
        Exact Method Body:
         return 
     (this.NO_QUICK_BUILD_SWITCH                 ? 1         : 0) +
     (this.INCLUDE_JAR_IN_CP_SWITCH              ? 10        : 0) +
     (this.SKIP_REMOVE_GCS_FILES_SWITCH          ? 100       : 0) +
     (this.OVERRIDE_TOGGLE_USE_XLINT_SWITCH      ? 1_000     : 0) +
     (this.OVERRIDE_TOGGLE_USE_XDIAGS_SWITCH     ? 10_000    : 0) +
     (this.INCLUDE_EARLY_DEV_PACKAGES_SWITCH     ? 100_000   : 0) +
     (this.JAR_FILE_ONLY_SWITCH                  ? 1_000_000 : 0);