Class SelectedOptionsRecord

  • public class SelectedOptionsRecord
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 'sor' 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.sor.toString());

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


    This record is how used to preserve the User's Command-Line input at a higher level. The switches that the user has entered are all stored inside this record - except the switches that correspond to Auxiliary Menu-Options.
    See Also:
    AuxiliaryOptRecord


    • Field Detail

      • MENU_CHOICE

        🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final java.lang.String MENU_CHOICE
        This field contains the end User-Selected Command-Line Main-Menu Option/Choice (as a java.lang.String).

        Some common examples of routinely passed CLI switches that are ultimately assigned to this field include:

        • "-1" - signifying that the 'javac' Compiler-Stage be run (a.k.a. "Please Compile my Files, or some of my files").

        • "-cb1" - requesting that the Composite-Step Option of a "Complete Build" be executed. All '.java' Source-Files will be Java-Doc'd, those '.html' Documentation-Pages will be ugraded, and then archived/tar'ed. Afterwards, the generted '.jar'-File will be placed on your Domain-Website's Storage-Bucket, as will all of your Documentation-Pages for your Source-Code.

        • "-pb1" - requesting that some subset of packages in your source need to be re-compiled, documented, and possibly synchronized to your Cloud Storage Space.



        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.

      • userSpecifiedPackages

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final ReadOnlyList<BuildPackage> userSpecifiedPackages
        This ReadOnlyList will, after constructing an instance of this class, contain the exact list of Java-Packages that have been included in this build.

        Most Build-Options will "Build" all Java Packages provided to the Config class' Config.packageList array. However, there are a few Main Menu-Options that allow for specifying, explicity, which Java Packages are to be included.

        This is another option whose primary use is for speeding up your interactive "builds". If documenting your pages is important to you, and re-building and re-publishing your documentation to your Web-Domain's Storage-Space, then requesting that just a small sub-set of your packages' '.html'-Files need to be udating can speed things up tremendously.

        How it's Used:
        Usually, this list will be identical to the list contained in BuildPackage-Array Config.packageList. The list of packages contained by this list will be "abridged", if a list of Package Nick-Names were provided at the Command-Line.

        Please review, at the top of this class, precisely which Main Menu-Options allow for specifying a list of "Package Nick-Names." It is for those precise Menu Choices that this particular field will be somewhat shorter than the User-Provided array contained within class Config Array-Field Config.packageList.

        Steps / Stages Affected:

        • S01_JavaCompiler - This list is utilized to decide which Java-Packages actually need to be compiled by 'javac'.

        • S03_Upgrade - Employed to decide which Java-Doc '.html'-Files require upgrading, by the Java-Doc Upgrader.

        • S05_SyncJavaDoc - Used to decide which '.html'-Files must be re-copied to your Web-Domain's Storage-Bucket directories, so that your Java-Doc based Web-Site contains your latest changes.



        Note that many of the stages, (Stage-2, for instance) ignore completely the contents of this ReadOnlyList. The original 'javadoc' program will always rebuild your entire Java-Doc Site, because it is the source of many, many URL-Anchor ('<A HREF=...>') links.

        Furthermore your Archive-Files (your '.jar' and '.tar') files will never "leave out" any '.class'-Files or Source-Code.

        The Steps within this Build-Tool that allow for Package Nick-Name's to be passed at the Command-Line are only their for quickly, and efficiently, upgrading your Java-Doc Web-Site so that you may quickly inspect how your latest round of changes actually look on the web.


        How it's Populated: 

         final ArrayList<String> l = new ArrayList<>();
 
 if (nickNamesProvided)
      for (String pkgNickName : nickNames) l.add(pkgNickName);
 
 if (EXTRA_PACKAGE_NICKNAMES)
      for (String pkgNickName : extraneousArgs) l.add(pkgNickName);
 
 this.userProvidedNickNames = nickNamesProvided
      ? new ReadOnlyArrayList<String>(l)
      : null;
 
 this.userSpecifiedPackages = nickNamesProvided
      ? BuildPackage.nickNameArgVPackages(packageList, this.userProvidedNickNames)
      : null;


        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.packageList, userProvidedNickNames
        Code:
        Exact Field Declaration Expression:
         public final ReadOnlyList<BuildPackage> userSpecifiedPackages;

      • userProvidedNickNames

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final ReadOnlyList<java.lang.String> userProvidedNickNames
        Please see the documentation for the field userSpecifiedPackages, since this field contains nearly identical information.

        This field is populated by extracting the actual User-Provided Nick-Name from each of the BuildPackage instances that are stored within the userSpecifiedPackages list.

        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.packageList, userProvidedNickNames
        Code:
        Exact Field Declaration Expression:
         public final ReadOnlyList<String> userProvidedNickNames;

    • 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:
         final String upnn = (this.userProvidedNickNames != null)
     ? this.userProvidedNickNames.toString()
     : "null, meaning none-provided";

 final Function<Option, String> PRINTER = (Option opt) ->
     "\n\t" + opt.toString();

 return 
     BCYAN + "this.MENU_CHOICE:            " + RESET + this.MENU_CHOICE + "\n" +
     BCYAN + "this.userProvidedNickNames:  " + RESET + upnn + "\n" +
     BCYAN + "this.userSpecifiedPackages:  " + RESET + "[See Above List]\n\n" +
     BCYAN + "this.optList: " + RESET +
         "**Apache.CLI.Option instances, toString()-invocation**" +
         StrCSV.toCSV(this.optList, PRINTER, true, null) + '\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 SelectedOptionRecord 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 SelectedOptionsRecord)) return false;
 SelectedOptionsRecord other = (SelectedOptionsRecord) o;

 return
         Objects.equals(this.MENU_CHOICE, other.MENU_CHOICE)
     &&  Objects.equals(this.userProvidedNickNames, other.userProvidedNickNames)
     &&  Objects.equals(this.userSpecifiedPackages, other.userSpecifiedPackages)
     &&  Objects.equals(this.optList, other.optList);

      • 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.MENU_CHOICE.hashCode() + this.userProvidedNickNames.hashCode();