001package Torello.Java.Build; 002 003import Apache.CLI.Option; 004import Torello.Java.ReadOnly.ReadOnlyList; 005 006import static Torello.Java.C.BCYAN; 007import static Torello.Java.C.RESET; 008 009/** 010 * This class contains an internally used {@code boolean}-Flag field corresponding to each of the 011 * Auxiliary Command-Line Options / Switches available by this Build-Tool. 012 * 013 * <!-- Contains the black-banner declaring this is a CLI-group internally used class --> 014 * <EMBED CLASS='external-html' DATA-FILE-ID=CLI_INTERNAL_USE> 015 * 016 * <!-- Explains how to retrieve an instance of this class, and provides an example --> 017 * <EMBED CLASS='external-html' DATA-FIELDNAME=aor DATA-FILE-ID=CLI_GET_REFERENCE> 018 * 019 * <BR /><BR />This record is used to help convert Command-Line Switches into 020 * {@code boolean}-Constants. These {@code final-boolean} fields are used inside: 021 * 022 * <BR /><BR /><UL CLASS-JDUL> 023 * <LI>Inside class {@link CLI}'s Constructor</LI> 024 * <LI>The class {@link BuilderRecord}'s constructor</LI> 025 * <LI>Inside of the 8 various stages of this Build-Tool</LI> 026 * </UL> 027 * 028 * <BR /><BR />This Record does help "keep clear" which Auxiliary-Switches are offered. There is 029 * also an Error-Checking class for this record. The class ({@link ErrorCheckAuxOpts}) checks each 030 * of the field in this class corresponds to <B STYLE='color: red;'><I>EXACTLY ONE</I></B> of the 031 * available <B>{@code "Auxiliary Options"}</B> that may be entered into the Command-Line or 032 * "Terminal Window". 033 * 034 * <BR /><BR />This class will do nothing more than copy these switches into a Read-Only Record. 035 * Since the new JDK-21 Records are, indeed, "ReadOnly" - this class will possibly be converted 036 * into a JDK-Record (instead of class), but not today. Right now, JDK-11 has its benefits too. 037 * I am stuck in Java 11, and I'm not exactly sure when I will be able to transition. Certainly 038 * this year, though. 039 * 040 * @see SelectedOptionsRecord 041 */ 042public class AuxiliaryOptRecord 043{ 044 /** 045 * To-Do: Create a detailed explanation of this sick little bugger. 046 * 047 * <EMBED CLASS=external-html DATA-FILE-ID=CLI_PUBLIC_FIELD> 048 * @see BuildPackage#QUICKER_BUILD_SKIP 049 */ 050 public final boolean NO_QUICK_BUILD_SWITCH; 051 052 /** 053 * One of the Primary Build-Goals for this Build-Package is to generate a standard Java 054 * {@code '.jar'}-File from your Source-Code. If you feel you have changed something in your 055 * code, and need to use the classes that are contained within your previously constructed 056 * {@code '.jar'}-File in your class-path, there is an Auxiliary-Menu Option for this. 057 * 058 * <BR /><BR /><B CLASS=JDDescLabel>How it's Used:</B> 059 * 060 * <BR />If the user has passed the {@code '-JCP'} Parameter at the Command-Line, then this 061 * {@code boolean}-Field will be assigned {@code TRUE}, and the Stage-01 {@code 'javac'} 062 * invocation will include whatever {@code '.jar'}-File in the Class-Path when it executes / 063 * runs {@code 'javac'} on your {@code '.java'} Source-Code Files. 064 * 065 * <EMBED CLASS=external-html DATA-FILE-ID=CLI_PUBLIC_FIELD> 066 */ 067 public final boolean INCLUDE_JAR_IN_CP_SWITCH; 068 069 /** 070 * One of the really powerful advantages to using this Build-Tool, is that re-compiling and 071 * updating your doc-files to your web-site can all be done with one single Command-Line 072 * invocation. This means your development process moves along nearly as fast the JDK's 073 * {@code 'javac'}-Command. 074 * 075 * <BR /><BR />In all honesty, the slowest part of the Java-HTML Build Process is copying 076 * 10,000 Java-Doc {@code '.html'} Files to the appropriate Google Storage-Bucket. If you 077 * have a Web-Address that is used for making your Source-Documentation Publicly-Visibly where 078 * it is not mission-critical to first remove all of the older documentation pages that are 079 * already present inside the Storage-Bucket's directories - <I>you may pass the Command-Line 080 * switch {@code '-SRG'} to your build, and the "Remove the Old Files" procedure will be 081 * skipped</I>. 082 * 083 * <BR /><BR />In Java-HTML, compiling, documenting and synchronizing all of the generated 084 * JavaDoc-Files to the Web can take upwards of 2.5 minutes. Passing the {@code '-SRG'} 085 * switch can shave off up to 30 seconds of Command-Line Wait-Time. 086 * 087 * <BR /><BR /><B CLASS=JDDescLabel>How it's Used:</B> 088 * 089 * <BR />This field will be assigned {@code TRUE} precisely when the {@code '-SRG'} 090 * Command-Line Switch has been passed to the <B>{@code String[] argv}</B> 091 * {@code String[]}-Array Parameter. 092 * 093 * <BR /><BR />When this Configuration-Field has been assigned {@code FALSE}, it will be 094 * comletel ignored, and the standard routine of deleting the old {@code 'html'}-Files from 095 * your Web-Domain's {@code Storage-Buckets} (your "original"), will be removed before the 096 * new {@code '.html'}-Files are copied. 097 * 098 * <BR /><BR />However, when this field is assigned {@code TRUE}, the Stage-5 Build-Logic 099 * will skip the removal of old {@code '.html'}-Files from your Bucket-Directories. 100 * 101 * <BR /><BR />As your {@code '.jar'}-File grows in size, this can save you several seconds 102 * of wating and staring at your Command-Line / Terminal Text-Output (waiting for you Build 103 * to finish, so you can see what the doc's look like). 104 * 105 * <EMBED CLASS=external-html DATA-FILE-ID=CLI_PUBLIC_FIELD> 106 */ 107 public final boolean SKIP_REMOVE_GCS_FILES_SWITCH; 108 109 /** 110 * This Build-Package's Command-Line Interface, as explained at the top of this {@code '.html'} 111 * Page, will accept the flag <B>{@code '-TXL'}</B>. 112 * 113 * <BR /><BR />The class {@code Config} has a User-Assignable {@code Boolean}-Field called, 114 * simply, {@link Config#USE_XLINT_SWITCH}. When this Build-Tool is configured such that this 115 * Configuration-Field is assigned {@code TRUE}, the Stage-1 Compilation {@code 'javac'} Stage 116 * will be executed with the included switch {@code '-Xlint:all,-processing'}. 117 * 118 * <BR /><BR />This can often help spot bugs which, according the JDK are not errors, just 119 * warnings (for instance), by halting the build when they occur. If you have a preference, 120 * then simply assigned {@code TRUE} or {@code FALSE} to the {@link Config} instance that is 121 * passed to class {@link BuilderRecord}. 122 * 123 * <BR /><BR />Now, in the event that this {@code 'javac'} switch is forcing your Build too 124 * fail, and you would like compile with such warnings anyway, you may pass the switch 125 * {@code '-TXL'} at the Command-Line, at it will <B STYLE='color: red;'>'toggle'</B> whatever 126 * assigned {@code Boolean}-Value was provided to class {@code Config} in your {@code '.java'} 127 * Source-File. 128 * 129 * <BR /><BR />Note that this also means that if you have this Compiler-Flag turned off by 130 * default, it may be temporarily "activated" at the Command-Line by passing the switch 131 * {@code '-TXL'} when you invoke class {@link RunBuild}. 132 * 133 * <BR /><BR /><B CLASS=JDDescLabel>How it's Used:</B> 134 * 135 * <BR />The value of this particular {@code Boolean}-Field will be {@code TRUE} when the 136 * switch was identified by the Apache-CLI Options-Processing code. It will be assigned 137 * {@code FALSE} (in this class, {@link CLI}, constructor) - when the switch is not present. 138 * 139 * <BR /><BR />The Build Stage-1 {@code 'javac'} Build-Step will decide whether or not to 140 * employ the {@code '-Xlint:all,-processing'} switch based on the value assigned to 141 * <B STYLE='color: red'>BOTH</B> the {@link Config#USE_XLINT_SWITCH} 142 * <B STYLE='color: red'>AND</B> the value assigned this field, as well. 143 * 144 * <BR /><BR />Again, when this field is {@code TRUE}, it just requests that the value stored 145 * to {@link Config#USE_XLINT_SWITCH} be <B STYLE='color: red;'>toggled</B> before being 146 * interpreted by the Stage 01 Build-Step ({@code 'javac'}). 147 * 148 * <EMBED CLASS=external-html DATA-FILE-ID=CLI_PUBLIC_FIELD> 149 * @see Config#USE_XLINT_SWITCH 150 */ 151 public final boolean OVERRIDE_TOGGLE_USE_XLINT_SWITCH; 152 153 /** 154 * This Build-Package's Command-Line Interface, as explained at the top of this {@code '.html'} 155 * Page, will accept the flag <B>{@code '-TXD'}</B>. 156 * 157 * <BR /><BR />This field is nearly identical to the final {@code Boolean}-Field, above, 158 * {@link #OVERRIDE_TOGGLE_USE_XLINT_SWITCH}. This field is used to 159 * <B STYLE='color: red;'>'toggle'</B> the User-Provided setting, passed by to class 160 * {@link Config}, assigned to the field {@link Config#USE_XDIAGS_SWITCH}. 161 * 162 * <BR /><BR />In the exact same fashion as {@link Config#USE_XLINT_SWITCH}, when the field 163 * {@link Config#USE_XDIAGS_SWITCH} is {@code TRUE}, it means that the Stage-1 Build-Logic 164 * should include the Command-Line switch {@code '-Xdiags:verbose'} when executing 165 * {@code 'javac'}. Quite a bit of useful information can, occasionally, be made available 166 * by the {@code 'javac'} command (by passing this switch to {@code 'javac'} at its 167 * Command-Line). 168 * 169 * <BR /><BR />However, when it is spitting out warnings, it also means your compilation 170 * stage will be prematurely halted. 171 * 172 * <BR /><BR /><B CLASS=JDDescLabel>How it's Used:</B> 173 * 174 * <BR />The value of this particular {@code Boolean}-Field will be {@code TRUE} when the 175 * switch was identified by the Apache-CLI Options-Processing code. It will be assigned 176 * {@code FALSE} (in this class, {@link CLI}, constructor) - when the switch is not present. 177 * 178 * <BR /><BR />The Build Stage-1 {@code 'javac'} Build-Step will decide whether or not to 179 * employ the {@code '-Xdiags:verbose'} switch based on the value assigned to 180 * <B STYLE='color: red'>BOTH</B> the {@link Config#USE_XDIAGS_SWITCH} 181 * <B STYLE='color: red'>AND</B> the value assigned this field, as well. 182 * 183 * <BR /><BR />Again, when this field is {@code TRUE}, it just requests that the value stored 184 * to {@link Config#USE_XDIAGS_SWITCH} be <B STYLE='color: red;'>toggled</B> before being 185 * interpreted by the Stage 01 Build-Step ({@code 'javac'}). 186 * 187 * <EMBED CLASS=external-html DATA-FILE-ID=CLI_PUBLIC_FIELD> 188 * @see Config#USE_XDIAGS_SWITCH 189 */ 190 public final boolean OVERRIDE_TOGGLE_USE_XDIAGS_SWITCH; 191 192 /** 193 * Adding a new Java-Package to a <B STYLE='color: red;'>{@code CI/CD: Continuous-Integraton / 194 * Continuous-Delivery}</B> Build-System can be somewhat un-nerving. If you would like to add 195 * a new Package - but occasionally want to leave it out of the Publicly-Visible 196 * Synchronization-Stages, then mark your packages (in class <B>{@link BuildPackage}</B>) with 197 * the <B>{@link BuildPackage#EARLY_DEVELOPMENT}</B> Flag. 198 * 199 * <BR /><BR />Using the Command-Line Switch <B>{@code "-IED"}</B>, you will be able to include 200 * or exclude such appropriately flagged Java-Packages as you see fit. 201 * 202 * <BR /><BR /><B CLASS=JDDescLabel>How it's Used:</B> 203 * 204 * <BR />The value assigned to this field will be {@code TRUE} precisely when the Build Switch 205 * {@code "-IED"} has been passed at the Command-Line. 206 * 207 * <BR /><BR />When this field has been assigned {@code FALSE}, it will be ignored, completely 208 * by the Build-Logic. However, when it is assigned {@code TRUE}, any of your Java-Packages 209 * that have been configured with the {@link BuildPackage#EARLY_DEVELOPMENT}-Flag will be 210 * 'elided' (to use a new, JDK-21+ term) or 'eliminated' completely from your Build-Process. 211 * 212 * <EMBED CLASS=external-html DATA-FILE-ID=CLI_PUBLIC_FIELD> 213 * @see BuildPackage#EARLY_DEVELOPMENT 214 */ 215 public final boolean INCLUDE_EARLY_DEV_PACKAGES_SWITCH; 216 217 /** 218 * For Menu-Option #4, "Run Archive-Stage - generate {@code '.tar'} and {@code '.jar'} Files", 219 * the user amy provided a Command-Line Switch {@code "-JFO"}. This switch allows a user to 220 * request that only a Java {@code '.jar'}-File be generated, and that the Java-Doc 221 * {@code 'tar'}-File and the Project Source-Code Archive {@code '.tar'}-File be skipped. 222 * 223 * <BR /><BR />This Auxiliary-Switch can only be applied if the Main-Menu Choice that has been 224 * provided is Command-Line Option {@code "-4"}, or the Composite-Stage Command-Line Option for 225 * Stages {@code "-1"} through {@code "-4"} has been entered. 226 * 227 * <BR /><BR />If neither of these two Menu-Options were entered at the termainal / 228 * Command-Line Interface, then this Build-Tool will print the Help-Menu and report that an 229 * error has occurred. 230 * 231 * <EMBED CLASS=external-html DATA-FILE-ID=CLI_PUBLIC_FIELD> 232 */ 233 public final boolean JAR_FILE_ONLY_SWITCH; 234 235 /** 236 * This option may be specified in combination with Main-Menu Option #1 (The Java-Compiler). 237 * This asks that before any of the Source-Files for any of the Packages-to-be-compiled are 238 * actually sent to 'javac', their respective '.class'-Files should, first, be removed and 239 * deleted from disk. 240 * 241 * <BR /><BR />This Auxiliary-Switch may only be used in combination with Main-Menu Option 242 * "-1". If used with any of the other Primary or Composite Stage Build-Requests, the CLI 243 * Processor will flag the input as an error. 244 */ 245 public final boolean WIPE_CLASS_FILES_FIRST; 246 247 248 AuxiliaryOptRecord(ReadOnlyList<Option> optList) 249 { 250 // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** 251 // Fill in this class' "Extra Switch Fields" (These are the non-main-menu Switches) 252 // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** 253 // 254 // All of these variables are declared, even though they are largely just exact copies of 255 // the public fields declared at the top of this class - BECAUSE THOSE FIELDS ARE ALL 256 // DECLARED 'final' - Meaning they may only be assigned once in this giant constructor that 257 // I have written. 258 // 259 // Declaring them 'final' means they can also be declared 'public', and the end user can 260 // play with them to his heart's content, wihthout having the ability to screw anything up 261 // either! 262 263 boolean 264 NO_QUICK_BUILD_SWITCH = false, 265 INCLUDE_JAR_IN_CP_SWITCH = false, 266 SKIP_REMOVE_GCS_FILES_SWITCH = false, 267 OVERRIDE_TOGGLE_USE_XLINT_SWITCH = false, 268 OVERRIDE_TOGGLE_USE_XDIAGS_SWITCH = false, 269 INCLUDE_EARLY_DEV_PACKAGES_SWITCH = false, 270 JAR_FILE_ONLY_SWITCH = false, 271 WIPE_CLASS_FILES_FIRST = false; 272 273 for (Option opt : optList) switch (opt.getOpt()) 274 { 275 case "NQB" : NO_QUICK_BUILD_SWITCH = true; break; 276 case "JCP" : INCLUDE_JAR_IN_CP_SWITCH = true; break; 277 case "SRG" : SKIP_REMOVE_GCS_FILES_SWITCH = true; break; 278 case "TXL" : OVERRIDE_TOGGLE_USE_XLINT_SWITCH = true; break; 279 case "TXD" : OVERRIDE_TOGGLE_USE_XDIAGS_SWITCH = true; break; 280 case "IEDP" : INCLUDE_EARLY_DEV_PACKAGES_SWITCH = true; break; 281 case "JFO" : JAR_FILE_ONLY_SWITCH = true; break; 282 case "WCFF" : WIPE_CLASS_FILES_FIRST = true; break; 283 // default : continue; 284 } 285 286 this.NO_QUICK_BUILD_SWITCH = NO_QUICK_BUILD_SWITCH; 287 this.INCLUDE_JAR_IN_CP_SWITCH = INCLUDE_JAR_IN_CP_SWITCH; 288 this.SKIP_REMOVE_GCS_FILES_SWITCH = SKIP_REMOVE_GCS_FILES_SWITCH; 289 this.OVERRIDE_TOGGLE_USE_XLINT_SWITCH = OVERRIDE_TOGGLE_USE_XLINT_SWITCH; 290 this.OVERRIDE_TOGGLE_USE_XDIAGS_SWITCH = OVERRIDE_TOGGLE_USE_XDIAGS_SWITCH; 291 this.INCLUDE_EARLY_DEV_PACKAGES_SWITCH = INCLUDE_EARLY_DEV_PACKAGES_SWITCH; 292 this.JAR_FILE_ONLY_SWITCH = JAR_FILE_ONLY_SWITCH; 293 this.WIPE_CLASS_FILES_FIRST = WIPE_CLASS_FILES_FIRST; 294 } 295 296 297 // ******************************************************************************************** 298 // ******************************************************************************************** 299 // java.lang.Object (Would JDK-21+ Record do this for me by automatic?) 300 // ******************************************************************************************** 301 // ******************************************************************************************** 302 303 304 /** 305 * Converts {@code 'this'} instance to a {@code java.lang.String} 306 * @return This class represented as a {@code String}. 307 */ 308 public String toString() 309 { 310 return 311 BCYAN + "this.NO_QUICK_BUILD_SWITCH " + RESET + 312 NO_QUICK_BUILD_SWITCH + "\n" + 313 314 BCYAN + "this.INCLUDE_JAR_IN_CP_SWITCH " + RESET + 315 INCLUDE_JAR_IN_CP_SWITCH + "\n" + 316 317 BCYAN + "this.SKIP_REMOVE_GCS_FILES_SWITCH: " + RESET + 318 SKIP_REMOVE_GCS_FILES_SWITCH + "\n" + 319 320 BCYAN + "this.OVERRIDE_TOGGLE_USE_XLINT_SWITCH: " + RESET + 321 OVERRIDE_TOGGLE_USE_XLINT_SWITCH + "\n" + 322 323 BCYAN + "this.OVERRIDE_TOGGLE_USE_XDIAGS_SWITCH: " + RESET + 324 OVERRIDE_TOGGLE_USE_XDIAGS_SWITCH + "\n" + 325 326 BCYAN + "this.INCLUDE_EARLY_DEV_PACKAGES_SWITCH: " + RESET + 327 INCLUDE_EARLY_DEV_PACKAGES_SWITCH + "\n" + 328 329 BCYAN + "this.JAR_FILE_ONLY_SWITCH: " + RESET + 330 JAR_FILE_ONLY_SWITCH + "\n" + 331 332 BCYAN + "this.WIPE_CLASS_FILES_FIRST: " + RESET + 333 WIPE_CLASS_FILES_FIRST + "\n"; 334 } 335 336 /** 337 * Check's for equality between {@code 'this'} instance, and any other instance of 338 * {@code java.lang.Object} 339 * 340 * @param o Any Java Object-Reference. Only an instance of class {@code AuxiliaryOptRecord} 341 * will generate a return-value of {@code TRUE}, and particularly only one whose fields are all 342 * equal to the corresponding fields in {@code 'this'} instance. 343 * 344 * @return {@code TRUE} if and only if {@code 'o'} and {@code 'this'} are equal, as explained 345 * above. 346 */ 347 public boolean equals(Object o) 348 { 349 if (! (o instanceof AuxiliaryOptRecord)) return false; 350 351 AuxiliaryOptRecord other = (AuxiliaryOptRecord) o; 352 353 return 354 (this.NO_QUICK_BUILD_SWITCH == 355 other.NO_QUICK_BUILD_SWITCH) 356 357 && (this.INCLUDE_JAR_IN_CP_SWITCH == 358 other.INCLUDE_JAR_IN_CP_SWITCH) 359 360 && (this.SKIP_REMOVE_GCS_FILES_SWITCH == 361 other.SKIP_REMOVE_GCS_FILES_SWITCH) 362 363 && (this.OVERRIDE_TOGGLE_USE_XLINT_SWITCH == 364 other.OVERRIDE_TOGGLE_USE_XLINT_SWITCH) 365 366 && (this.OVERRIDE_TOGGLE_USE_XDIAGS_SWITCH == 367 other.OVERRIDE_TOGGLE_USE_XDIAGS_SWITCH) 368 369 && (this.INCLUDE_EARLY_DEV_PACKAGES_SWITCH == 370 other.INCLUDE_EARLY_DEV_PACKAGES_SWITCH) 371 372 && (this.JAR_FILE_ONLY_SWITCH == 373 other.JAR_FILE_ONLY_SWITCH) 374 375 && (this.WIPE_CLASS_FILES_FIRST == 376 other.WIPE_CLASS_FILES_FIRST); 377 } 378 379 /** 380 * Generates a Hash-Code for use with Standard-Java {@code Hashtable's} etc... 381 * 382 * @return A (somewhat) unique Hash-Code, to be used for placing an instance of this 383 * class into any variant of Hash-Table. 384 */ 385 public int hashCode() 386 { 387 return 388 (this.NO_QUICK_BUILD_SWITCH ? 1 : 0) + 389 (this.INCLUDE_JAR_IN_CP_SWITCH ? 10 : 0) + 390 (this.SKIP_REMOVE_GCS_FILES_SWITCH ? 100 : 0) + 391 (this.OVERRIDE_TOGGLE_USE_XLINT_SWITCH ? 1_000 : 0) + 392 (this.OVERRIDE_TOGGLE_USE_XDIAGS_SWITCH ? 10_000 : 0) + 393 (this.INCLUDE_EARLY_DEV_PACKAGES_SWITCH ? 100_000 : 0) + 394 (this.JAR_FILE_ONLY_SWITCH ? 1_000_000 : 0) + 395 (this.WIPE_CLASS_FILES_FIRST ? 10_000_000 : 0); 396 } 397}