Class Packages

  • public class Packages
extends java.lang.Object
    Decide which User-Provided Packages will be put through the various Build-Stages.



    Stateless Class:
    This class neither contains any program-state, nor can it be instantiated. The @StaticFunctional Annotation may also be called 'The Spaghetti Report'. Static-Functional classes are, essentially, C-Styled Files, without any constructors or non-static member fields. It is a concept very similar to the Java-Bean's @Stateless Annotation.

    • 1 Constructor(s), 1 declared private, zero-argument constructor
    • 3 Method(s), 3 declared static
    • 0 Field(s)


    • Method Detail

      • packagesInThisBuild

        🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static Ret2<ReadOnlyList<BuildPackage>,​ReadOnlyList<BuildPackage>> packagesInThisBuild​
            (CLI cli,
             BuildPackage[] usersBuildPackageList)
        Used in the Class Builder-Constructor to specify, exactly, which packages may or may not be processed during an invocation of that class' build method.
        Parameters:
        cli - The Object that represents / contains the switches and User-Requests that were obtained at the Command-Line from the Command-Line Parser Object CLI.
        usersBuildPackageList - The list of BuildPackage instances that were passed to the User-Configuration Class Config. The reference passed to this parameter is the exact same reference that is found in Config.packageList.
        Returns:
        This, essentially, returns the exact same input list, but after it has been divided into two sets - those packages that are going to be included in the Build, and any packages that are not part of the build.

        The packages that are 'removed' from the build are:

        • Early-Development Packages
          These are packages which are not completed yet, and are not ready for publication & distribution.

        • Skip-On-Quick-Build Packages
          These are packages which are aren't necessarily imperative for the proper functioning of JAR, and for speed and a faster development time can be eliminated from your '.jar' when focusing on other parts of the build.


        Inclusion Decisions:
        The decision that remove packages from the list of "Packages to Process in the Build" can be reversed at the Command-Line using the '-NQB' (No Quick Build) or the '-IEDP' (Include Early-Development Packages.)

        Utlimately this method returns two lists, contained by an instance of Ret2. The instances of BuildPackage that are going to be processed during by Builder are in one list, and the BuildPackage instances to be skipped are in the second list.

        • Ret2.a: ReadOnlyList<BuildPackage>
          The list of packages to be processed in this build.

        • Ret2.b: ReadOnlyList<BuildPackage>
          The list of packages to that are being skipped in this build.
        Code:
        Exact Method Body:
         // This is a little complicated.  All this is doing is "merging" a suite of User-Provided
 // configurations from about three different places.
 // 
 // The class "BuildPackage" allows the user to configure settings for the packages.  One of
 // those settings allows a user to assert that a package is a "Skip if Quick Build."  In my
 // world all that is talking about is the "Torello.Browser" Package, which:
 //
 //      1) Takes for ever to compile
 //      2) Takes even longer to run the Java-Doc (and even longer for the upgrader)
 //      3) MOST-IMPORTANTLY: Never changes at all, because i'm not working on it right now.
 //         As a result, pretending it doesn't exist, except when compiling with -cb1
 //         "Complete Build 1" (The actual "Release Directory"), makes working a lot easier
 //
 // Class CLI also allows users to configure stuff by passing switches.  It's mechanisms
 // involve arguments passed to the "String[] argv" parameter via the
 // "public static void main" method.
 //
 // In Java-HTML, as of March 2024, the CSS Tokenizer (which is going to have extremely
 // limited use, since "parsing CSS" is several orders of magnitude less useful than parsing
 // HTML) - ... the "CSS Tokenizer" is an "Early Development" package.  Early Development
 // packages have almost the same behavior, they are left out completely (just like the
 // Quick-Build packages) - except when they are explicity requested.
 //
 // ========================================================================================
 // NOTE: "QUICK_BUILD" and "EARLY_DEVELOPMENT" packages are treated as if they just don't
 //       exist, unless the user has made specific requests for them at the command line CLI
 // ========================================================================================
 //
 // If a package isn't going to be processed during the build, it is placed into Ret2.b

 final boolean IS_FULL_COMPILE = (cli.userSpecifiedPackages == null);

 final Predicate<BuildPackage> FILT = (BuildPackage bp) ->
 {
     if (cli.QUICKER_BUILD) if (bp.skipIfQuickerBuild)

         return IS_FULL_COMPILE
             ? false
             : cli.userSpecifiedPackages.contains(bp);

     if (bp.earlyDevelopment)
     {
         if (cli.INCLUDE_EARLY_DEV_PACKAGES) return true;

         return IS_FULL_COMPILE
             ? false
             : cli.userSpecifiedPackages.contains(bp);
     }

     return true;
 };

 final ReadOnlyArrayList<BuildPackage> packagesIncluded =
     new ReadOnlyArrayList<BuildPackage>(FILT, usersBuildPackageList);

 final ReadOnlyArrayList<BuildPackage> packagesEliminated = 
     new ReadOnlyArrayList<BuildPackage>(FILT.negate(), usersBuildPackageList);

 return new Ret2<>(packagesIncluded, packagesEliminated);

      • packagesToCompile

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static ReadOnlyList<BuildPackage> packagesToCompile​
            (Builder builder)
        throws java.io.IOException
        This determines which packages should be re-compiled in the Stage 1 Build-Class S01_JavaCompiler.
        Parameters:
        builder - This instance contains all information obtained from the User via the User-Settings class Config, and information obtained via the Command-Line Interface CLI.
        Returns:
        The list of packages whose files are to be recompiled, based on the User-Settings provided class Config, and the User-Request that were made at the CLI, Command-Line Interface
        Throws:
        java.io.IOException
        Code:
        Exact Method Body:
         // It is important to "get" the BuildPackage Configuration-Flags.  
 //
 // The value of BuildPackge.mustReCompile is defined in (surprise) class BuildPackage, as
 // follows, here:
 //
 // this.earlyDevelopment   = (flags & EARLY_DEVELOPMENT) >= 1;
 // this.skipIfQuickerBuild = (flags & QUICKER_BUILD_SKIP)  >= 1;
 // 
 // this.mustReCompile =
 //         (! this.earlyDevelopment)
 //     &&  (! this.skipIfQuickerBuild)
 //     &&  ((flags & DO_NOT_RECOMPILE) == 0); // == 0 implies the "NOT" of the flag
 //
 // FINALLY: The cli.userSpecifiedPackages is literally just the Package-NickNames tht are
 //          provided to class CLI via the "public static void main" method that gets it.

 final boolean IS_FULL_COMPILE = (builder.cli.userSpecifiedPackages == null);

 final Predicate<BuildPackage> FILT = (builder.cli.INCLUDE_EARLY_DEV_PACKAGES)
     ? (BuildPackage bp) -> bp.mustReCompile || bp.earlyDevelopment
     : (BuildPackage bp) -> bp.mustReCompile;

 final ReadOnlyList<BuildPackage> packagesToCompile = IS_FULL_COMPILE
     ? new ReadOnlyArrayList<>(builder.packageList, FILT, builder.packageList.size())
     : builder.cli.userSpecifiedPackages;

 return packagesToCompile;

      • packagesToJavaDoc

        🡅  ⇈  ⮫ 🗕  🗗  🗖 
        public static ReadOnlyList<BuildPackage> packagesToJavaDoc​
            (Builder builder)
        This determines which packages should be run through 'javadoc', in the Stage 2 Build-Class S02_JavaDoc.
        Parameters:
        builder - This instance contains all information obtained from the User via the User-Settings class Config, and information obtained via the Command-Line Interface CLI.
        Returns:
        The list of packages whose files are to be sent to the javadoc Tool, based on the User-Settings provided class Config, and the User-Request that were made at the CLI, Command-Line Interface.
        Code:
        Exact Method Body:
         // Copied from the class `BuildPackage
 //
 // this.mustDocument        = (flags & DO_NOT_DOCUMENT)     == 0; // The "NOT" of the flag
 // this.earlyDevelopment    = (flags & EARLY_DEVELOPMENT)   >= 1;
 // this.skipIfQuickerBuild  = (flags & QUICKER_BUILD_SKIP)  >= 1;

 final Predicate<BuildPackage> FILT = (BuildPackage pkg) -> pkg.mustDocument;

 final ReadOnlyList<BuildPackage> ret = new ReadOnlyArrayList<>
     (builder.packageList, FILT, builder.packageList.size());

 return ret;