Class Config


  • public final class Config
    extends java.lang.Object
    This class provides a list of fields, all of which may be modified and configured, for providing any needed settings to class BuilderRecord.

    Use the public constructor offered by this class, and then set and change the values of any of the Configuration-Fields. Once this class Configuration-Fields have been appropriately set to contain your project's data, pass the instance to the BuilderRecord class' only constructor (along with an argv String[]-Array).

    This will inform the BuilderRecord-Constructor of all of your nedded settings, and once built, will make running your project's build script very easy.


    • Field Detail

      • projectNameValidator

        🡇     🗕  🗗  🗖
        public static final java.util.function.Predicate<java.lang.String> projectNameValidator
        Project-Name validation String. The value passed to configuration field/parameter must match this regular expression. This is used in this class validate() method.
        See Also:
        PROJECT_NAME, BuilderRecord.PROJECT_NAME, validate()
        Code:
        Exact Field Declaration Expression:
         public static final Predicate<String> projectNameValidator =
                 Pattern.compile("^\\w[\\w\\d]*$").asPredicate();
        
      • LOCAL_JAVADOC_DIR

        🡅  🡇     🗕  🗗  🗖
        public java.lang.String LOCAL_JAVADOC_DIR
        The File-System Directory-Location where Java-Doc Output is sent for storage. Also the directory that the Upgrader searches to retrieve and parse JavaDoc Files.
        See Also:
        BuilderRecord.LOCAL_JAVADOC_DIR
        Code:
        Exact Field Declaration Expression:
         public String LOCAL_JAVADOC_DIR = "javadoc" + java.io.File.separator;
        
      • JAVAC_BIN

        🡅  🡇     🗕  🗗  🗖
        public java.lang.String JAVAC_BIN
        The full or partial Path-Name of the 'javac' binary to use for compiling this project. This parameter / field may not be null, or a NullPointerException will throw.

        Default Setting:
        The default setting for this Configuration-Field is just the command name, which is to presume that the PATH environment-variable has been set to facilitate finding 'javac'
        See Also:
        BuilderRecord.JAVAC_BIN
        Code:
        Exact Field Declaration Expression:
         public String JAVAC_BIN = "javac";
        
      • JAVADOC_BIN

        🡅  🡇     🗕  🗗  🗖
        public java.lang.String JAVADOC_BIN
        The full or partial Path-Name of the 'javac' binary to use for compiling this project. This parameter / field may not be null, or a NullPointerException will throw.

        Default Setting:
        The default setting for this Configuration-Field is just the command name, which is to presume that the PATH environment-variable has been set to facilitate finding 'javadoc'.
        See Also:
        BuilderRecord.JAVADOC_BIN
        Code:
        Exact Field Declaration Expression:
         public String JAVADOC_BIN = "javadoc";
        
      • FAVICON

        🡅  🡇     🗕  🗗  🗖
        public java.lang.String FAVICON
        If the Stage 3 Upgrade-Process utilizes a favicon on its Web-Pages, then this field may be assigned to the location on disk where that favicon is located.

        When this field contains a non-null Image-File, that image will be copied (after upgrade has completed) directly to the 'javadoc' output directory. When this field is left null, it will be ignored and no favicon image is copied.
        See Also:
        BuilderRecord.FAVICON
        Code:
        Exact Field Declaration Expression:
         public String FAVICON = null;
        
      • JAR_FILE_MOVE_DIR

        🡅  🡇     🗕  🗗  🗖
        public java.lang.String JAR_FILE_MOVE_DIR
        This optional configuration field is optional, and may be used to move / relocate the '.jar' File after it's built by this Build-Processor. If there is a diretory or location on the File-System into which the '.jar' should be moved, then provide that directory's name here.

        When this field is left null, it will be silently ignored; furthermore, the '.jar' File which the Build-Processor creates will be left in the Current Working Directory.
      • LOG_DIR

        🡅  🡇     🗕  🗗  🗖
        public java.lang.String LOG_DIR
        The directory location where log information will be saved. This configuration field may not be null, or a NullPointerException will throw.
      • extraSwitchesJAVAC

        🡅  🡇     🗕  🗗  🗖
        public java.lang.String[] extraSwitchesJAVAC
        For Stage 1, the Java-Compiler Stage, this Configuration-Field may be assigned any switch-String's, and they will be passed to the javac invocation.

        This field's value may be left null, or assigned a zero-length String[]-Array and, in both cases, it shall be ignored.
        See Also:
        BuilderRecord.extraSwitchesJAVAC
        Code:
        Exact Field Declaration Expression:
         public String[] extraSwitchesJAVAC = null;
        
      • extraSwitchesJAVADOC

        🡅  🡇     🗕  🗗  🗖
        public java.lang.String[] extraSwitchesJAVADOC
        For Stage 2, the javadoc Stage, this Configuration-Field may be assigned any switch-String's, and they will be passed to the javadoc invocation.

        This field's value may be left or null, or assigned a zero-length String[]-Array, and, in both cases, it shall be ignored.
        See Also:
        BuilderRecord.extraSwitchesJAVADOC
        Code:
        Exact Field Declaration Expression:
         public String[] extraSwitchesJAVADOC = null;
        
      • CLASS_PATH

        🡅  🡇     🗕  🗗  🗖
        public java.lang.String[] CLASS_PATH
        The Root Class-File Directories to use with 'javac'. This is used to generate the value passed to the -cp switch passed when Stage 1 invokes the Java-Compiler. This parameter / field may be empty or null, and if it is, it will be ignored.
      • jarIncludes

        🡅  🡇     🗕  🗗  🗖
        public JarInclude jarIncludes
        This allows for specifying a list of files to manually add into the '.jar' that is built by this package.

        Constructor Call:
        Because it isn't necessary to include any "Extra Files" into the '.jar', there is some likelihood that this Configuration-Field wouldn't ever be needed / used. Make sure to call the JarInclude constructor, first, to build an instance of this Config-Field before attempting to use it. Notice that it is initially initialized to null!

        Common Usess:
        Java-HTML has quite a few Data-Files that are inserted into the Jar-File, manually, using this class. There may also be the need to insert META-INF/ directory files that name things like Annotation-Processor locations, taglets, or other Java Services.
        See Also:
        BuilderRecord.jarIncludes
        Code:
        Exact Field Declaration Expression:
         public JarInclude jarIncludes = null;
        
      • NO_JAVADOC_FRAMES_SWITCH

        🡅  🡇     🗕  🗗  🗖
        public boolean NO_JAVADOC_FRAMES_SWITCH
        JavaDoc Frames were a true majesty that should never have been eliminated. If you would prefer to remove them, or you are using JDK 21+ which no longer accepts the --frames switch, then set this Configuration-Field to FALSE.
        See Also:
        BuilderRecord.NO_JAVADOC_FRAMES_SWITCH
        Code:
        Exact Field Declaration Expression:
         public boolean NO_JAVADOC_FRAMES_SWITCH = false;
        
    • Method Detail

      • validate

        🡅  🡇     🗕  🗗  🗖
        public final void validate()
                            throws java.io.FileNotFoundException
        Used by class BuilderRecord to validate all user-provided data on a best efforts basis.
        Throws:
        java.lang.NullPointerException - If any of the configuration parameter/fields listed here have been assigned null

        This exception will also be thrown if these lists contain any null-valued entries:
        java.lang.IllegalArgumentException - If any of these configuration fields were assigned a negative number:

        This exception will also be thrown if:
        java.io.FileNotFoundException - This exception will throw if either of these fields are not assigned a valid File-System Directory-Name:
        UnrecognizedImageExtException - If the FAVICON Image-Format cannot be properly "guessed" by class IF.
        EmptyListException - If packageList has been assigned an empty list.
        WriteableDirectoryException - If parameter JAR_FILE_MOVE_DIR is assigned a non-null value, but the String assigned it does not point to a File-System directory, or that directory is not writeable.

        Also throws if LOG_DIR is not a valid directory-name, that allows write-access.
        Code:
        Exact Method Body:
         Objects.requireNonNull(LOCAL_JAVADOC_DIR,   M1 + "LOCAL_JAVADOC_DIR" + M2);
         Objects.requireNonNull(PROJECT_NAME,        M1 + "PROJECT_NAME" + M2);
         Objects.requireNonNull(JAVAC_BIN,           M1 + "JAVAC_BIN" + M2);
         Objects.requireNonNull(JAVADOC_BIN,         M1 + "JAVADOC_BIN" + M2);
         Objects.requireNonNull(TAR_SOURCE_DIR,      M1 + "TAR_SOURCE_DIR" + M2);
         Objects.requireNonNull(LOG_DIR,             M1 + "LOG_DIR" + M2);
         Objects.requireNonNull(upgrader,            M1 + "upgrader" + M2);
         Objects.requireNonNull(packageList,         M1 + "packageList" + M2);
        
         if (! projectNameValidator.test(PROJECT_NAME)) throw new IllegalArgumentException
             (M1 + "PROJECT_NAME] was not passed a valid name.");
        
         if (VERSION_MAJOR_NUMBER < 0) throw new IllegalArgumentException
             (M1 + "VERSION_MAJOR_NUMBER" + M3 + VERSION_MAJOR_NUMBER);
        
         if (VERSION_MINOR_NUMBER < 0) throw new IllegalArgumentException
             (M1 + "VERSION_MINOR_NUMBER" + M3 + VERSION_MINOR_NUMBER);
        
         if (JAVADOC_VER < 0) throw new IllegalArgumentException
             (M1 + "JAVADOC_VER" + M3 + JAVADOC_VER);
        
         if (FAVICON != null)
         {
             File f = new File(FAVICON);
        
             if ((! f.exists()) || (! f.isFile())) throw new FileNotFoundException(
                 "Field 'FAVICON' [" + FAVICON + "] points to a file that was not found, or " +
                 "isn't a File"
             );
        
             IF.guessOrThrow(FAVICON);
         }
        
         if (packageList.length == 0) throw new EmptyListException
             (M1 + "packageList] was passed a list of size 0.");
        
         for (BuildPackage bp : packageList) if (bp == null) throw new NullPointerException
             (M1 + "packageList] contains a null value.");
        
         for (String p : CLASS_PATH) if (p == null) throw new NullPointerException
             (M1 + "CLASS_PATH] contains a null value.");
        
         File f = new File(TAR_SOURCE_DIR);
         if (! (f.exists() && f.isDirectory())) throw new FileNotFoundException
             (M1 + "] was not passed a vaild File-System Directory-Name.");
        
         if (JAR_FILE_MOVE_DIR != null)
         {
             WritableDirectoryException.check(JAR_FILE_MOVE_DIR);
        
             if (! JAR_FILE_MOVE_DIR.endsWith(File.separator))
                 JAR_FILE_MOVE_DIR = JAR_FILE_MOVE_DIR + File.separator;
         }
        
         WritableDirectoryException.check(LOG_DIR);
        
         if (! LOG_DIR.endsWith(File.separator)) LOG_DIR = LOG_DIR + File.separator;
        
      • createBuilder

        🡅  🡇     🗕  🗗  🗖
        public BuilderRecord createBuilder​(java.lang.String[] argv)
                                    throws java.io.FileNotFoundException,
                                           java.io.IOException
        Processes Command-Line Inputs, and creates an instance of BuilderRecord. You may initiate a build using that class by calling the RunBuild.run(BuilderRecord) method.
        Parameters:
        argv - The Command-Line Inputs
        Returns:
        An instance of BuilderRecord. You may invoke the method RunBuild.run(BuilderRecord) to initiate a build.
        Throws:
        java.io.FileNotFoundException - Throw by the class Config validate method if there are problems with the user's provided configurations.
        java.io.IOException - Thrown if there are IO Problems while reading any of the files in the Class-Path, or other configurations.
        Code:
        Exact Method Body:
         return new BuilderRecord(this, argv);
        
      • toString

        🡅     🗕  🗗  🗖
        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object
        Code:
        Exact Method Body:
         final Config DEF = new Config();
        
         // public String HOME_DIR = null;
         // public String LOCAL_JAVADOC_DIR = "javadoc" + java.io.File.separator;
         // public String PROJECT_NAME = null;
         // public byte VERSION_MAJOR_NUMBER = 1;
         // public byte VERSION_MINOR_NUMBER = 0;
         // public String JAVAC_BIN = "javac";
         // public String JAVADOC_BIN = "javadoc";
         // public byte JAVA_RELEASE_NUM_SWITCH = -1;
         // public byte JAVADOC_VER = 11;
         // public String FAVICON = null;
         // public String TAR_SOURCE_DIR = null;
         // public String JAR_FILE_MOVE_DIR = null;
         // public String LOG_DIR = null;
         // public Upgrade upgrader = null;
         // public UpgradeProcessor preUpgraderScript = null;
         // public UpgradeProcessor postUpgraderScript = null;
         // public String[] extraSwitchesJAVAC = null;
         // public String[] extraSwitchesJAVADOC = null;
         // public BuildPackage[] packageList = null;
         // public String[] CLASS_PATH = null;
         // public JarInclude jarIncludes = null;
         // public boolean USE_XLINT_SWITCH = true;
         // public boolean USE_XDIAGS_SWITCH = true;
         // public boolean NO_JAVADOC_FRAMES_SWITCH = false;
        
         return 
        
             // public String HOME_DIR
             BCYAN + "HOME_DIR:\n\t" + RESET + 
                 BYELLOW + "Value:   " + RESET + " **** " + /*this.HOME_DIR*/ "\n\t" +
                 BYELLOW + "Default: " + RESET + DEF.HOME_DIR + "\n\n" +
        
             // public String LOCAL_JAVADOC_DIR
             BCYAN + "LOCAL_JAVADOC_DIR:\n\t" + RESET + 
                 BYELLOW + "Value:   " + RESET + this.LOCAL_JAVADOC_DIR + "\n\t" +
                 BYELLOW + "Default: " + RESET + DEF.LOCAL_JAVADOC_DIR + "\n\n" +
        
             // public String PROJECT_NAME
             BCYAN + "PROJECT_NAME:\n\t" + RESET + 
                 BYELLOW + "Value:   " + RESET + this.PROJECT_NAME + "\n\t" +
                 BYELLOW + "Default: " + RESET + DEF.PROJECT_NAME + "\n\n" +
        
             // public byte VERSION_MAJOR_NUMBER
             BCYAN + "VERSION_MAJOR_NUMBER:\n\t" + RESET + 
                 BYELLOW + "Value:   " + RESET + this.VERSION_MAJOR_NUMBER + "\n\t" +
                 BYELLOW + "Default: " + RESET + DEF.VERSION_MAJOR_NUMBER + "\n\n" +
        
             // public byte VERSION_MINOR_NUMBER
             BCYAN + "VERSION_MINOR_NUMBER:\n\t" + RESET + 
                 BYELLOW + "Value:   " + RESET + this.VERSION_MINOR_NUMBER + "\n\t" +
                 BYELLOW + "Default: " + RESET + DEF.VERSION_MINOR_NUMBER + "\n\n" +
        
             // public String JAVAC_BIN
             BCYAN + "JAVAC_BIN:\n\t" + RESET + 
                 BYELLOW + "Value:   " + RESET + this.JAVAC_BIN + "\n\t" +
                 BYELLOW + "Default: " + RESET + DEF.JAVAC_BIN + "\n\n" +
        
             // public String JAVADOC_BIN
             BCYAN + "JAVADOC_BIN:\n\t" + RESET + 
                 BYELLOW + "Value:   " + RESET + this.JAVADOC_BIN + "\n\t" +
                 BYELLOW + "Default: " + RESET + DEF.JAVADOC_BIN + "\n\n" +
        
             // public byte JAVA_RELEASE_NUM_SWITCH
             BCYAN + "JAVA_RELEASE_NUM_SWITCH:\n\t" + RESET + 
                 BYELLOW + "Value:   " + RESET + this.JAVA_RELEASE_NUM_SWITCH + "\n\t" +
                 BYELLOW + "Default: " + RESET + DEF.JAVA_RELEASE_NUM_SWITCH + "\n\n" +
        
             // public byte JAVADOC_VER
             BCYAN + "JAVADOC_VER:\n\t" + RESET + 
                 BYELLOW + "Value:   " + RESET + this.JAVADOC_VER + "\n\t" +
                 BYELLOW + "Default: " + RESET + DEF.JAVADOC_VER + "\n\n" +
        
             // public String FAVICON
             BCYAN + "FAVICON:\n\t" + RESET + 
                 BYELLOW + "Value:   " + RESET + this.FAVICON + "\n\t" +
                 BYELLOW + "Default: " + RESET + DEF.FAVICON + "\n\n" +
        
             // public String TAR_SOURCE_DIR
             BCYAN + "TAR_SOURCE_DIR:\n\t" + RESET + 
                 BYELLOW + "Value:   " + RESET + this.TAR_SOURCE_DIR + "\n\t" +
                 BYELLOW + "Default: " + RESET + DEF.TAR_SOURCE_DIR + "\n\n" +
        
             // public String JAR_FILE_MOVE_DIR
             BCYAN + "JAR_FILE_MOVE_DIR:\n\t" + RESET + 
                 BYELLOW + "Value:   " + RESET + this.JAR_FILE_MOVE_DIR + "\n\t" +
                 BYELLOW + "Default: " + RESET + DEF.JAR_FILE_MOVE_DIR + "\n\n" +
        
             // public String LOG_DIR
             BCYAN + "LOG_DIR:\n\t" + RESET + 
                 BYELLOW + "Value:   " + RESET + this.LOG_DIR + "\n\t" +
                 BYELLOW + "Default: " + RESET + DEF.LOG_DIR + "\n\n" +
        
             // public Upgrader upgrader
             BCYAN + "upgrader:\n\t" + RESET + 
                 BYELLOW + "Value:   " + RESET + this.upgrader + "\n\t" +
                 BYELLOW + "Default: " + RESET + DEF.upgrader + "\n\n" +
        
             // public UpgradeProcessor preUpgraderScript
             BCYAN + "preUpgraderScript:\n\t" + RESET + 
                 BYELLOW + "Value:   " + RESET + this.preUpgraderScript + "\n\t" +
                 BYELLOW + "Default: " + RESET + DEF.preUpgraderScript + "\n\n" +
        
             // public UpgradeProcessor postUpgraderScript
             BCYAN + "postUpgraderScript:\n\t" + RESET + 
                 BYELLOW + "Value:   " + RESET + this.postUpgraderScript + "\n\t" +
                 BYELLOW + "Default: " + RESET + DEF.postUpgraderScript + "\n\n" +
        
             // public String[] extraSwitchesJAVAC
             BCYAN + "extraSwitchesJAVAC:\n\t" + RESET + 
                 BYELLOW + "Value:   " + RESET + SARR(this.extraSwitchesJAVAC) + "\n\t" +
                 BYELLOW + "Default: " + RESET + SARR(DEF.extraSwitchesJAVAC) + "\n\n" +
        
             // public String[] extraSwitchesJAVADOC
             BCYAN + "extraSwitchesJAVADOC:\n\t" + RESET + 
                 BYELLOW + "Value:   " + RESET + SARR(this.extraSwitchesJAVADOC) + "\n\t" +
                 BYELLOW + "Default: " + RESET + SARR(DEF.extraSwitchesJAVADOC) + "\n\n" +
        
             // public BuildPackage[] packageList
             BCYAN + "packageList:\n\t" + RESET + 
                 BYELLOW + "Value:   " + RESET + PLARR(this.packageList) + "\n\t" +
                 BYELLOW + "Default: " + RESET + PLARR(DEF.packageList) + "\n\n" +
        
             // public String[] CLASS_PATH
             BCYAN + "CLASS_PATH:\n\t" + RESET + 
                 BYELLOW + "Value:   " + RESET + SARR(this.CLASS_PATH) + "\n\t" +
                 BYELLOW + "Default: " + RESET + SARR(DEF.CLASS_PATH) + "\n\n" +
        
        
             // public JarInclude jarIncludes
             BCYAN + "jarIncludes:\n\t" + RESET + 
                 BYELLOW + "Value:   " + RESET + this.jarIncludes + "\n\t" +
                 BYELLOW + "Default: " + RESET + DEF.jarIncludes + "\n\n" +
        
             // public boolean USE_XLINT_SWITCH
             BCYAN + "USE_XLINT_SWITCH:\n\t" + RESET + 
                 BYELLOW + "Value:   " + RESET + this.USE_XLINT_SWITCH + "\n\t" +
                 BYELLOW + "Default: " + RESET + DEF.USE_XLINT_SWITCH + "\n\n" +
        
             // public boolean USE_XDIAGS_SWITCH
             BCYAN + "USE_XDIAGS_SWITCH:\n\t" + RESET + 
                 BYELLOW + "Value:   " + RESET + this.USE_XDIAGS_SWITCH + "\n\t" +
                 BYELLOW + "Default: " + RESET + DEF.USE_XDIAGS_SWITCH + "\n\n" +
        
             // public boolean NO_JAVADOC_FRAMES_SWITCH
             BCYAN + "NO_JAVADOC_FRAMES_SWITCH:\n\t" + RESET + 
                 BYELLOW + "Value:   " + RESET + this.NO_JAVADOC_FRAMES_SWITCH + "\n\t" +
                 BYELLOW + "Default: " + RESET + DEF.NO_JAVADOC_FRAMES_SWITCH + "\n\n";