Class CLI

  • public class CLI
extends java.lang.Object
    This data class is instantiated by parsing the Command-Line Input. It contains the settings that were extrapolated by the Apache CLI Parser.

    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.
    Retrieving an Instance:
    With the above provided notice, if you still wish to view the contents of this class, the Object-Reference that is used by RunBuild is one of the myriad field's that are made available within the class BuilderRecord.

    A BuilderRecord instance is generated as follows, and the CLI instance is obtained by referencing the field cli, as below:

    Example:
     public static void main(String[] argv)
 {
      Config config = new Config();
 
      // Perform as many assignments to the Configuration-Fields as is necessary!
      // ... [Configurations Here] ...
      //see class Config to learn about all available Config-Fields]
 
      BuilderRecord brec = config.createBuilder(argv);
 
      // Print's out the contents of this class...
      System.out.println(brec.cli);
 
      // Run's the Build, using all User-Provided Configurations obtained from class Config,
      // along with all User-Specified Options provided at the OS Command-Prompt
 
      RunBuild.run(brec);
 }


    The datum contained as fields of this class are all declared public and also ReadOnly or final. The instance generated from the Command-Line Input (CLI) parser is available as a public and final field of the Builder instance field Torello.Java.Build.Builder.cli;

    This class does not offer any public constructors, nor any public methods. It is automatically built by class Builder, which has package-level access to this class' sole constructor.

    The menu option printed by this class looks similar to this one: 

    
	Primary Build Steps / Stages:
		-1   -> Compile [Optional: Package-Nicknames]
		-2   -> JavaDoc
		-3   -> Upgrader [Optional:  Package-Nicknames]
		-4   -> Archive & Compress: Build 2 TAR's & 1 JAR

	Cloud-Synchronization Primary Build Steps / Stages:
		-5   -> Transfer: 'javadoc/' directory to Cloud
		-6   -> Transfer: '.tar' and '.jar' files to Cloud
		-7   -> Transfer: logs to Cloud
		-8   -> Set Cloud-Files' Browser-Cache Meta-Data to 150 seconds

	Composite-Stage Complete-Build (-cb) Options:
		-cb1 -> STEPS 2 through 7.    [Push-To: RT-DEV]
		-cb2 -> STEPS 2 through 8.    [Push-To: RT-DEV]
		-cb3 -> STEPS 2 through 7.    [Push-To: RT-DEV-2]
		-cb4 -> STEPS 2 through 8.    [Push-To: RT-DEV-2]
		-cb5 -> STEPS 2 through 7.    [Push-To: Java-HTML]

	Composite-Stage Partial-Build (-pb) Options:
		-pb1 -> SETPS 2 and 3.        [Doc Only, Optional: Pkg-Nicknames]
		-pb2 -> STEPS 2 through 4.
		-pb3 -> STEPS 2, 3, 5 and 8.  [Push-To: RT-DEV, Optional: Pkg-Nicknames]
		-pb4 -> STEPS 2, 3, 5 and 8.  [Push-To: RT-DEV-2, Optional: Pkg-Nicknames]

	Links-Checker:
		-LC  -> STEPS 2 and 3, WITH-LINKS-CHECK

	Auxiliary Options:
		-NQB,--noQuickBuild         Prevent a Quick Build during Partial-Build's
		-JCP,--putJarInCP           Include the '.jar' File in the Class-Path
		-SRG,--skipRemoveGCSFiles   Skip the removal-step of all Java-Doc GCS Files, when synchronizing.
		-TXL,--toggleDefaultXlint   Toggle whatever the default setting is for applying -Xlint:all
		-TXD,--toggleDefaultXdiags  Toggle whatever the default setting is for applying -Xdiags:verbose
		-IEDP,--includeEarlyDev     Include Packages still Under Early Development in the Build
		-JFO,--jarFileOnly          Only generate a '.jar' File during the Stage-4 Build-Step

You must select exactly one of the Primary or Composite Build-Options listed above
Requesting that the Java-Doc Internal-URL Links-Checker be run is also allowed,
although currently, it has been disabled


    Main-Menu Options:
    The following Table lists the Primary Stage/Step Main-Menu CLI-Options for this Build Package. The options listed below are exclusive, and only one of them may be passed to the CLI (via the String[] argv parameters) on any single-invocation of RunBuild.run:
    CLI-SwitchPurpose
    -1, --javac Requests Stage-1: Invoke / Run `javac`.

    Allows for specifying which packages to compile, via a Package Nick-Names List.
    -2, --javadoc Requests Stage-2: Invoke / Run `javadoc`
    -3, --jdu Requests Stage-3: Invoke the JavaDoc Upgrader
    -4, --tarjar Requests Stage-4: Run `tar` & `jar`
    -5, --syncJavaDoc Requests Stage-5: Synchronize 'javadoc/' Directory-Content to the Cloud
    -6, --syncTarJar Requests Stage-6: Synchronize `tar` & `jar` Archive-Files to the Cloud
    -7, --syncLogs Requests Stage-7: Synchronize the Logs to the Cloud
    -8, --setMaxAge Requests Stage-8: Set the Cache-Control HTTP-Server Property 'max-age', on all synchronized 'javadoc/' Files.

    Additional Main-Menu Options:
    The following Table lists the Main-Menu CLI-Options that specify a Composite-Set of the previously listed Build-Step Options. As mentioned before, only one of these switches may be specified to the class CLI on any single Command-Line Invocation. These options perform a Complete, or near Complete Build process. The two Partial-Build Options help speed up the build process, when only small parts of the code or pacakges are actually being modified.
    CLI-SwitchPurpose
    -cbX, --completeX Requests Complete-Build, Steps #2 to #7 (or #8) Varying "Push-To Locations" are offered, depending upon the number of User-Provided CloudSync instances that have been inserted into class Config's Configurations, using method addCloudSync
    -pbX, --partialX Requests a Partial-Build, Steps #2, #3 and others: Runs a smaller subset of the Primary Stages.
    -LC, --linksCheck Requests Run the Internal Links-Checker: Runs the Java-Doc Upgrader Tool's Internal-Links Checker.

    Auxillary Options:
    None of these Command-Line switches are Main-Menu Options, and they would not meet the requirement that the 'argv' parameter String[]-Array passed at the Command-Line contain at least one Main-Menu Option.

    For each of these CLI Switches, the Main-Menu Option with which the switches may be utilized is listed at the top of the description. If an Auxillary-Switch is employed with a Main-Menu Option that isn't listed, the class will throw an exception, and print a thoughtfully worded error message.
    CLI-SwitchPurpose
    -NQB, --noQuickBuild Works Alongside: -pbX, --partialX During Partial-Builds, this switch prevents a "Quick Build." A Quick-Build means that Packages which are marked as "Skip on Partial-Build" are removed, completely, from the Build. All "--partial" build options are treated as Quick-Builds; however, this switch can be used to disable this default behavior.

    Package's may be designated as QUICKER_BUILD_SKIP packages via the BuildPackage class Configuration Flags.
    -JCP, --putJarInCP Works Alongside: -1, --javac Includes whatever '.jar' File which was created during the previous build, in the Class-Path, during the current 'javac' Stage-1 Compilation-Stage.
    -SRG, --skipRemoveGCSFiles Works Alongside: -cbX, --completeX When synchronizing Java-Doc '.html'-Files to the Cloud, this option asks the build to skip the removal / deletion of old '.html'-Files before synchronizing the new ones.

    Generally, this has the net-effect of "speeding things up" vis-a-vis the Cloud-Synchronization Stage, which is always the slowest part of the build process.
    -TXL, --toggleDefaultXlint Works Alongside: -1, --javac Toggle whatever the default setting is for applying -Xlint:all. This switch may be passed to the 'javac' Java-Oracle Binary by this Build-Tool during the (Stage-1) Build-Step.

    Note that the default behavior may be configured via the class Config Field USE_XLINT_SWITCH
    -TXD, --toggleDefaultXdiags Works Alongside: -1, --javac Toggle whatever the default setting is for applying -Xdiags:verbose This switch may be passed to the 'javac' Java-Oracle Binary by this Build-Tool during the (Stage-1) Build-Step.

    Note that the default behavior may be configured via the class Config Field USE_XDIAGS_SWITCH
    -IEDP, --includeEarlyDev Works Alongside: All Main-Menu Options, Except: -4, -6, -7 Packages which have been designed by the User as EARLYDEVELOPMENT (via the BuildPackage class configurations) will be included in this Build.

    Packages which are marked as still too early in the development life-cycle are, by default, ignored by this Build-Tool during a build.
    -JFO, --jarFileOnly Works Alongside: -4, --tarjar During the Stage-4 Archive-Stage, do not generate all Archive-Files; only generate the Project '.jar'-File.

    This Options also works alongside option "-pb2", which processes Steps #1 to #4. However in scenarios where the User-Provided class Config instance' list of CloudSync references is empty, this option will, instead, work along side "-cb1" (rather than "-pb2"), because that in such conditions, that's the option which executes Steps # to #4.


    • Field Detail

      • QUICKER_BUILD

        🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final boolean QUICKER_BUILD
        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 QUICKER_BUILD;

      • sma_NoBrowserCache_OptionSelected

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final boolean sma_NoBrowserCache_OptionSelected
        There is a way to request that your '.html'-Files have Meta-Data inside their File-Headers stating that they do not wish the user's Web-Browser to Cache their Java-Doc -Files.

        If you are including documentation pages as a part of your Build-Process, then "re-uploading" your Java-Doc '.html' Pages will be as important as re-compiling and testing your code.

        If you are intending to visit, and re-visit a particular Web-Address in whatever browser you are using to view your Java-Doc output, then making sure that your browser does not cache your Web-Pages will save you an endless amount of head-ache.

        Wiping your Google Chrome's Cache manually can be a real disaster when your saved Form-Field answers are erased, along with your saved Search-Requests or even your passwords!

        How it's Used:
        This field is manually populated by the internal CLI-Option Building-Class. All that is occuring is that, internally, a list of class CLI Main-Menu Options which indicate / necessitate that Stage 8, Set Max Age was entered, by the user, at the command line.

        If the User-Selected MENU_CHOICE is among the known Stage-8 options, then this field will contain TRUE.

        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.

      • partialWithSync_OptionSelected

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final boolean partialWithSync_OptionSelected
        This field is assigned TRUE when a "Partial Build" MENU_CHOICE has been selected by the user, at the Command-Line, and that choice is one of the choices that requests Step / Stage 5 (Synchronize all '.html' Files) be run.

        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.

      • compositeStep_RunStage1to4_OptionSelected

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final boolean compositeStep_RunStage1to4_OptionSelected
        This field is assigned TRUE if-and-only-if the Composite-Step Menu-Option associated with running Primary-Steps / Primary-Stages #1 to #4 has been selected by the user.

        This boolean is required by the RunBuild class in order to decide whether or not to run the Stage-4 (Archive / Tar / Jar) Process for a Composite-Build.

        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:
        RunBuild.run(BuilderRecord)
        Code:
        Exact Field Declaration Expression:
         public final boolean compositeStep_RunStage1to4_OptionSelected;

      • sor

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final SelectedOptionsRecord sor
        This record is generated based on the Terminal-Input from 'String[] argv'.

        As soon as the Apache-CLI Options are generated, they are compared against the User's String[] argv input, and this record is created.

      • aor

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final AuxiliaryOptRecord aor
        This Record contains exactly 7 final-boolean fields, each of which corresponds to exactly one of the available Command-Line Terminal Main-Menu Auxialiary-option Switches.

        Whenever a user passes a Command-Line Auxiliary Option / Switch at to the String[] argv parameter, it will be reflected inside this final class.
        See Also:
        ErrorCheckAuxOpts
        Code:
        Exact Field Declaration Expression:
         public final AuxiliaryOptRecord aor;

    • Method Detail

      • toString

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object
        Code:
        Exact Method Body:
         return 
     BCYAN + "this.QUICKER_BUILD:                             " + RESET +
         this.QUICKER_BUILD + '\n' +

     BCYAN + "this.sma_NoBrowserCache_OptionSelected:         " + RESET +
         this.sma_NoBrowserCache_OptionSelected + '\n' +

     BCYAN + "this.partialWithSync_OptionSelected:            " + RESET +
         this.partialWithSync_OptionSelected + '\n' +

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

     BCYAN + "this.sor: " + RESET + "[...]\n" +
     BCYAN + "this.aor: " + RESET + "[...]\n";

      • equals

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public boolean equals​(java.lang.Object other)
        Overrides:
        equals in class java.lang.Object
        Code:
        Exact Method Body:
         if (! (other instanceof CLI)) return false;
 CLI o = (CLI) other;

 return 
         (this.QUICKER_BUILD ==
         o.QUICKER_BUILD)

     &&  (this.sma_NoBrowserCache_OptionSelected ==
         o.sma_NoBrowserCache_OptionSelected)

     &&  (this.partialWithSync_OptionSelected ==
         o.partialWithSync_OptionSelected)

     &&  (this.compositeStep_RunStage1to4_OptionSelected ==
         o.compositeStep_RunStage1to4_OptionSelected)

     &&  Objects.equals(this.sor, o.sor)
     &&  Objects.equals(this.aor, o.aor);

      • hashCode

        🡅  ⇈  ⮫ 🗕  🗗  🗖 
        public int hashCode()
        Overrides:
        hashCode in class java.lang.Object
        Code:
        Exact Method Body:
         return
     (1      * (this.QUICKER_BUILD                               ? 1 : 0)) +
     (10     * (this.sma_NoBrowserCache_OptionSelected           ? 1 : 0)) +
     (100    * (this.partialWithSync_OptionSelected              ? 1 : 0)) + 
     (1_000  * (this.compositeStep_RunStage1to4_OptionSelected   ? 1 : 0));