Add PathBuilder documentation clean up code.

org.hl7.fhir.utilities/src/main/java/org/hl7/fhir/utilities/PathBuilder.java

@@ -11,22 +11,75 @@ import java.nio.file.Paths;
 @AllArgsConstructor(access = AccessLevel.PRIVATE)
 public class PathBuilder {
 
+  /**
+   * By default, the normalized built path must be a child of the first entry of the buildPath arguments. If a
+   * different parent is desired, this can be set via <code>withRequiredTarget</code>
+   */
   @With
   private final String requiredTarget;
 
+  /**
+   * By default, the first entry of the buildPath argument cannot be null or an empty string. Setting this to false will
+   * disable this check.
+   */
   @With
   private final boolean requireNonNullNonEmptyFirstEntry;
 
+  /**
+   * By default, the first entry of the buildPath argument cannot be a root directory (<code>"/", "C:\", etc. </code>. Setting this to false will disable this check.
+   */
   @With
   private final boolean requireNonRootFirstEntry;
 
+  /**
+   * By default, the normalized built path must be a child of the first entry of the buildPath arguments. Setting this
+   * to false will disable this check.
+   */
   @With
   private final boolean requirePathIsChildOfTarget;
 
+  /**
+   * Returns an instance of PathBuilder with all checks enabled (recommended).
+   *
+   * @return
+   */
   public static PathBuilder getPathBuilder() {
     return new PathBuilder(null, true, true, true);
   }
 
+  /**
+   * <p>Builds a path from the passed argument strings. This path will be compatible with the local filesystem.
+   * </p>
+   *
+   * <p>
+   * If the args contain variables enclosed in square brackets (<code>[ ]</code>), they will be replaced with values in
+   * the built path. There are several built-in variables available, listed below. Any text between square brackets that
+   * does not match these will be replaced by a matching System environment variable if one is available.
+   * </p>
+   *
+   * <p>
+   * Built-in variables include:
+   * <ul>
+   *  <li><i>[tmp]</i> An available temp directory (Java Temp directory, <code>c:\\temp, $TMPDIR, %TEMP%</code>, etc.) </li>
+   *  <li><i>[user]</i> The OS user directory (~, user.home, etc) </li>
+   * </ul>
+   * </p>
+   *
+   * <p>
+   * This method will run several checks by default to ensure that the built path does not point to unintended areas of
+   * the filesystem. If these checks are violated, a RuntimeException will be thrown. If needed in special cases, the
+   * behavior of these checks can be modified via the linked fluent constructor methods below.
+   * </p>
+   *
+   * @param args entries with which to construct the filesystem path
+   * @throws RuntimeException
+   * @return a local filesystem path
+   *
+   * @see this#withRequiredTarget(String)
+   * @see this#withRequireNonNullNonEmptyFirstEntry(boolean)
+   * @see this#withRequireNonRootFirstEntry(boolean)
+   * @see this#withRequirePathIsChildOfTarget(boolean)
+   */
   public String buildPath(String... args) {
 
     checkNonNullNonEmptyFirstEntry(args);

org.hl7.fhir.utilities/src/main/java/org/hl7/fhir/utilities/Utilities.java

@@ -613,26 +613,15 @@ public class Utilities {
     return s.toString();
   }
 
-  private static boolean isPathRoot(String pathString) {
-    boolean actual;
-    Path path = Path.of(pathString);
-    Path normalizedPath = path.normalize();
-    actual = normalizedPath.equals(path.getRoot());
-    return actual;
-  }
-
   /**
    * Composes a path string using by concatenating the passed arguments.
-   * Variables such as [tmp] and [user] are replaced.
    *
-   * In order to prevent unintentional access to areas of the file system
-   * outside of the first entry, this method will throw exceptions in situations
-   * where the constructed path is at a higher level than the first entry, or
-   * where the first entry is null or empty.
+   * This method enables all checks for unintended path locations.
    *
    * @param args
    * @return
    * @throws IOException
+   * @see PathBuilder#buildPath(String...)
    */
   public static String path(String... args) throws IOException {
     return PathBuilder.getPathBuilder().buildPath(args);
@@ -640,7 +629,6 @@ public class Utilities {
 
   /**
    * Composes a path string using by concatenating the passed arguments.
-   * Variables such as [tmp] and [user] are replaced.
    *
    * This method does not check for unintentional access to areas of the file
    * system outside of the first entry. ONLY USE THIS METHOD IN CASES WHERE YOU
@@ -649,7 +637,10 @@ public class Utilities {
    * @param args
    * @return
    * @throws IOException
+   *
+   * @see PathBuilder#buildPath(String...)
    */
+  @Deprecated
   public static String uncheckedPath(String... args) {
     return PathBuilder.getPathBuilder()
       .withRequireNonRootFirstEntry(false)
@@ -658,35 +649,6 @@ public class Utilities {
       .buildPath(args);
   }
 
-  private static String replaceVariables(String a) {
-    if ("[tmp]".equals(a)) {
-      if (hasCTempDir()) {
-        return C_TEMP_DIR;
-      } else if (ToolGlobalSettings.hasTempPath()) {
-        return ToolGlobalSettings.getTempPath();
-      } else {
-        return System.getProperty("java.io.tmpdir");
-      }
-    } else if ("[user]".equals(a)) {
-      return System.getProperty("user.home");
-    } else if (a.startsWith("[") && a.endsWith("]")) {
-      String ev = System.getenv(a.replace("[", "").replace("]", ""));
-      if (ev != null) {
-        return ev;
-      } else {
-        return "null";
-      }
-    }
-    return a;
-  }
-
-  private static boolean hasCTempDir() {
-    if (!System.getProperty("os.name").toLowerCase().contains("win")) {
-      return false;
-    }
-    File tmp = new File(C_TEMP_DIR);
-    return tmp.exists() && tmp.isDirectory() && tmp.canWrite();
-  }
 
   public static String pathURL(String... args) {
     StringBuilder s = new StringBuilder();