Class BuildPackage

  • public class BuildPackage
extends java.lang.Object
    This User-Data class is used to describe the Java-Packages included inside of a Java Project.

    Java-HTML JAR BuildPackage instances:
    You may view the list of packages that are used to build the Java-HTML JAR-Library here, in the link below:

    MyPackages.java


    • Field Detail

      • DO_NOT_RECOMPILE

        🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static final byte DO_NOT_RECOMPILE
        This flag may be attached to one of your BuildPackage instances to signify that the package being flagged should not ever be re-compiled when Build-Stage 1 ('javac') is executing - unless the package's nick-name has been explicity specified at the Command Line Interface.

        This flag can be an invaluable tool for speeding up build times be eliminating the compilation for Source-Files whose code is not changing and is not dependent on the Source-Files inside your project.

        For Instance, Java-HTML:
        In the Java-HTML '.jar' File, the external-imports that are included such as the Glass-Fish JSON Processor, and the Apache CLI Tools have Source-Files that do not ever need to be recompiled. Those packages are included in this '.jar' file's documentation, but when this project is built, the Compiler Build-Stage will skip the compilation of the Source-Files in those Packages.
        See Also:
        Constant Field Values
        Code:
        Exact Field Declaration Expression:
         public static final byte DO_NOT_RECOMPILE = 1;

      • DO_NOT_DOCUMENT

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static final byte DO_NOT_DOCUMENT
        This flag may be attached to one of your BuildPackage instances to signify that the package being flagged should not ever be documented when Build-Stage 2 ('javadoc') is executing.

        When this flag is attached to a BuildPackage, there will simply be no documentation generated for that package.

        For Instance, Java-HTML:
        This Project's '.jar' File includes several classes that act as Internal Processors for the Java-Doc Upgrader Tool. Those classes are all part of a root package known as JDUInternal.

        Because the Source-Code in these classes serves no purpose whatsoever as a part of any kind of "External API", the methods and fields of those classes are not documented. The BuildPackage instance for the JDUInternal Package has been flagged with this flag DO_NOT_DOCUMENT
        See Also:
        Constant Field Values
        Code:
        Exact Field Declaration Expression:
         public static final byte DO_NOT_DOCUMENT = DO_NOT_RECOMPILE << 1;

      • HAS_SUB_PACKAGES

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static final byte HAS_SUB_PACKAGES
        This is a special flag that may be used to signify that a particular BuildPackage instance actually refers to a tree of packages, rather than just a single package.

        This flag works very well with the DO_NOT_DOCUMENT Flag.

        For Instance, Java-HTML:
        Again, the internal Java-Doc Upgrader Classes, rooted in package JDUInternal, actually form a tree of packages that are ultimately included in the '.jar' File.
        See Also:
        Constant Field Values
        Code:
        Exact Field Declaration Expression:
         public static final byte HAS_SUB_PACKAGES = DO_NOT_DOCUMENT << 1;

      • QUICKER_BUILD_SKIP

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static final byte QUICKER_BUILD_SKIP
        This is a flag that can be used to boost Build-Times in a way quite similar to the DO_NOT_RECOMPILE flag. When a BuildPackage instance is flagged with QUICKER_BUILD_SKIP, if a user is performing a "Partial Build" using one of the Partial-Build Flags (-pb1 and -pb2), then that package will simply be eliminated from the Build.

        For packages that are not necessarily external and independent packages, but are disjoint enough such that they do not need to be recompiled or documented in most situations, then this flag can help boost Build-Speed during development.

        For Instance, Java-HTML:
        The Java-HTML '.jar' includes an Experimental Headless-Browser Package. The BuildPackage instance that models that package is flagged with the QUICKER_BUILD_SKIP. This means that during development, unless a Full Release Build has been invoked (Build-Switch '-cb1'), the Browser-Package is simply ignored.

        It is not compiled by Stage 1; it is not documented by the 'javadoc' stage, and its documentation pages are not upgraded. Because that package was generated by a Code-Generator, and is extremely lengthy and doesn't change, it doesn't need to be included in the Build-Process at all unless a Full-Release Build is being invoked.

        Note that the Build-Switch '-NQB' can override the elimination of packages that have been flagged in this way.
        See Also:
        Constant Field Values
        Code:
        Exact Field Declaration Expression:
         public static final byte QUICKER_BUILD_SKIP = HAS_SUB_PACKAGES << 1;

      • DO_NOT_JAR

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static final byte DO_NOT_JAR
        This can be used to request that the class files for a Java Package not be included in the '.jar' File generated for that package.

        For Instance, Java-HTML:
        There is a proprietary, internal, Builder Package Hierarchy that is only used for improving this particular package. The classes in package Torello.BuildJAR are, therefore, flagged with the 'DO_NOT_JAR' flag.

        A cursory inspection of the Java-HTML '.jar' File will reveal that there is not package named Torello.BuildJAR inside the '.jar' File. This is because that package contains proprietary and internal classes that serve no purpose whatsoever outside of the Build-Process.
        See Also:
        Constant Field Values
        Code:
        Exact Field Declaration Expression:
         public static final byte DO_NOT_JAR = QUICKER_BUILD_SKIP << 1;

      • EARLY_DEVELOPMENT

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static final byte EARLY_DEVELOPMENT
        Can be used to flag a package as "Under Development." Packages flagged as such will not be included in the Build unless explicity requested.

        For Instance, Java-HTML:
        The most recent addition to Java-HTML has been the package Torello.CSS. It is currently under development and therefore wholly eliminated from the Build except when it has been explicity requested.

        The elimination of packages flagged with the 'EARLY_DEVELOPMENT' flag can be overriden using the Build Command-Line Switch '-IEDP', which simply stands for "Include Early Development Packages".
        See Also:
        Constant Field Values
        Code:
        Exact Field Declaration Expression:
         public static final byte EARLY_DEVELOPMENT = DO_NOT_JAR << 1;

      • hasUpgradeFilesDir

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final boolean hasUpgradeFilesDir
        Indicates that this package's Source-Code Directory has an 'upgrade-files/' sub-directory. The 'upgrade-files/' directory stores myriad configurations that are utilized by the Java-Doc Upgrader Tool, which is executed in Build-Stage 3.

        This field is assigned as follows: 

         File f = new File(this.pkgRootDirectory + "upgrade-files" + FS);
 
 this.hasUpgradeFilesDir = f.exists() && f.isDirectory();

      • hasPackageSourceDir

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final boolean hasPackageSourceDir
        Indicates that this package's Source-Code Directory has a 'package-source/' sub-directory containing '.java' Files. The 'package-source/' directory can be used to organize and categorize '.java' Files within a single Java Package so that they are not all lumped together in a single Java-Package Directory.

        This field is assigned as follows: 

         f = new File(this.pkgRootDirectory + "package-source" + FS);
 
 this.hasPackageSourceDir = f.exists() && f.isDirectory();

      • mustReCompile

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final boolean mustReCompile
        This field indicates whether or not the DO_NOT_RECOMPILE flag was assigned to 'this' instance of BuildPackage. This field's value is assigned, in this class' constructor, as below: 

         this.mustReCompile = (flags & DO_NOT_RECOMPILE) == 0;
        See Also:
        DO_NOT_RECOMPILE
        Code:
        Exact Field Declaration Expression:
         public final boolean mustReCompile;

      • mustDocument

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final boolean mustDocument
        This field simply indicates whether or not the DO_NOT_DOCUMENT was assigned to 'this' instance of BuildPackage. This field's value is assigned, in this class' constructor, as below: 

         this.mustDocument = (flags & DO_NOT_DOCUMENT) == 0;
        See Also:
        DO_NOT_DOCUMENT
        Code:
        Exact Field Declaration Expression:
         public final boolean mustDocument;

      • doNotJAR

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final boolean doNotJAR
        This field simply indicates whether or not the DO_NOT_JAR was assigned to 'this' instance of BuildPackage. This field's value is assigned, in this class' constructor, as below: 

         this.doNotJAR = (flags & DO_NOT_JAR) >= 1;
        See Also:
        DO_NOT_JAR
        Code:
        Exact Field Declaration Expression:
         public final boolean doNotJAR;

      • hasSubPackages

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final boolean hasSubPackages
        This field simply indicates whether or not the HAS_SUB_PACKAGES was assigned to 'this' instance of BuildPackage. This field's value is assigned, in this class' constructor, as below: 

         this.hasSubPackages = (flags & HAS_SUB_PACKAGES) >= 1;
        See Also:
        HAS_SUB_PACKAGES
        Code:
        Exact Field Declaration Expression:
         public final boolean hasSubPackages;

      • skipIfQuickerBuild

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final boolean skipIfQuickerBuild
        This field simply indicates whether or not the QUICKER_BUILD_SKIP was assigned to 'this' instance of BuildPackage. This field's value is assigned, in this class' constructor, as below: 

         this.skipIfQuickerBuild = (flags & QUICKER_BUILD_SKIP) >= 1;
        See Also:
        QUICKER_BUILD_SKIP
        Code:
        Exact Field Declaration Expression:
         public final boolean skipIfQuickerBuild;

      • earlyDevelopment

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final boolean earlyDevelopment
        This field simply indicates whether or not the EARLY_DEVELOPMENT was assigned to 'this' instance of BuildPackage. This field's value is assigned, in this class' constructor, as below: 

         this.earlyDevelopment = (flags & EARLY_DEVELOPMENT) >= 1;
        See Also:
        EARLY_DEVELOPMENT
        Code:
        Exact Field Declaration Expression:
         public final boolean earlyDevelopment;

      • helperPackages

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final ReadOnlyList<java.lang.String> helperPackages
        Helper packages may be passed as parameters to the BuildPackage constructor. All a "Helper Package" is is a sub-directory of the Package-Directory that contains additional classes that are germaine to the classes in this package.

        The classes in a Helper-Package will not be documented by 'javadoc', nor will they be (obviously) be upgrader by the Stage 3 Build-Class performing the JavaDoc Upgrade.

        Instead, these classes will be compiled by the 'javac', and included, quietly, in the final '.jar' File produced by this Build. This can be a great way to add simple classes that are required for an API Class to fully function, but do not actually need to be documented and included in the API themselves.

        A cursory inspection of the contents of the Java-HTML '.jar' Distribution should reveal, for instance the HTML Helper-Package 'Torello.HTML.parse', which does the actual parsing for the HTML Parsing class HTMLPage. This class is fundamental and necessary to the operation of the HTML Package, but is largely useless in the API that's exported to the end user.

        This field's value is assigned by this class' constructor, as below: 

         this.helperPackages = (helperPackages == null) || (helperPackages.length == 0)
      ? EMPTY_LIST
      : new ReadOnlyArrayList(
          0,
          (String subDirName) -> this.pkgRootDirectory +
              (subDirName.endsWith(FS) ? subDirName : (subDirName + FS)),
          helperPackages
      );

    • Constructor Detail

      • BuildPackage

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public BuildPackage​(java.lang.String fullName,
                    java.lang.String classPathLocation,
                    java.lang.String nickName,
                    int flags,
                    java.lang.String... helperPackages)
        Constructs an instance of this class.
        Parameters:
        fullName - The full name of the package. This package, for instance, is named Torello.Java.Build.
        classPathLocation - The root class-path location
        nickName - A nick-name for this package that may be passed at the Command-Line Interface when it is necessary to specify that this package be included in the Build-Proces.
        flags - The Boolean-OR of all flags being assigned to this package.
        helperPackages - A list of any and all sub-directory packages to be included in this '.jar' upon which this package depends. This list must contain String's that name actual sub-directories of the package-directory that contains the source-files for this package.
        Throws:
        java.lang.IllegalArgumentException - This exception throws under the following circumstances:

        • If mustDocument and hasSubPackages are both, simultaneously, set
        • If any of the "Helper Packages" do not name valid sub-directories of the primary package-directory

    • Method Detail

      • toString

        🡅  ⇈  ⮫ 🗕  🗗  🗖 
        public java.lang.String toString()
        Stringify an instance of this class.
        Overrides:
        toString in class java.lang.Object
        Returns:
        a Java String representation of this class.
        Code:
        Exact Method Body:
         final int LEN = 22;

 final String CPL = (classPathLocation.length() == 0)
     ? BGREEN + "Current Working Directory" + RESET
     : classPathLocation;

 return 
     StringParse.rightSpacePad("fullName:", LEN)             + fullName              + '\n' +
     StringParse.rightSpacePad("classPathLocation:", LEN)    + CPL                   + '\n' +
     StringParse.rightSpacePad("pkgRootDirectory:", LEN)     + pkgRootDirectory      + '\n' +
     StringParse.rightSpacePad("nickName:", LEN)             + nickName              + '\n' +
     StringParse.rightSpacePad("hasUpgradeFilesDir:", LEN)   + hasUpgradeFilesDir    + '\n' +
     StringParse.rightSpacePad("hasPackageSourceDir:", LEN)  + hasPackageSourceDir   + '\n' +
     StringParse.rightSpacePad("mustReCompile:", LEN)        + mustReCompile         + '\n' +
     StringParse.rightSpacePad("mustDocument:", LEN)         + mustDocument          + '\n' +
     StringParse.rightSpacePad("hasSubPackages:", LEN)       + hasSubPackages        + '\n' +
     StringParse.rightSpacePad("skipIfQuickerBuild:", LEN)   + skipIfQuickerBuild    + '\n' +
     StringParse.rightSpacePad("earlyDevelopment:", LEN)     + earlyDevelopment      + '\n' +
     StringParse.rightSpacePad("helperPackages:", LEN) +
         '[' + StrCSV.toCSV(helperPackages, true, true, null) + ']';