Package rife.bld.extension.tools

Class IOTools

java.lang.Object
rife.bld.extension.tools.IOTools
@NullMarked public final class IOTools extends Object
I/O Tools.

Utility methods for common file system operations including existence checks, executability checks, directory creation, and path resolution. All methods accept null inputs and return false (or an appropriate default) rather than throwing NullPointerException.

Since:
1.0
Author:
Erik C. Thauvin

  • Method Details

    • canExecute

      public static boolean canExecute(@Nullable File file)
      Determines if the specified file exists, is a file, and is executable.
      Parameters:
      file - the file to be checked
      Returns:
      true if the file exists, is a file, and can be executed; false otherwise
      Since:
      1.0

    • canExecute

      public static boolean canExecute(@Nullable Path path)
      Determines if the specified path exists, is a regular file, and is executable.
      Parameters:
      path - the path to be checked
      Returns:
      true if the path exists, is a regular file, and can be executed; false otherwise
      Since:
      1.0

    • canExecute

      public static boolean canExecute(@Nullable String path)
      Determines if the file at the specified path string exists, is a regular file, and is executable.
      Parameters:
      path - the path string to be checked
      Returns:
      true if the path exists, is a regular file, and can be executed; false otherwise, including when the path is null, blank, or invalid
      Since:
      1.0

    • createDirs

      public static boolean createDirs(@Nullable Path path) throws IOException
      Creates the directory named by the given path, including any nonexistent parent directories.

      If path is null, this method does nothing and returns false. If the directory already exists, this method does nothing and returns true.

      Parameters:
      path - the directory to create, may be null
      Returns:
      true if the directory exists after the call, false if path is null
      Throws:
      FileAlreadyExistsException - if path exists and is not a directory
      AccessDeniedException - if the process does not have permission to create the directory
      IOException - if an I/O error occurs while creating the directory
      SecurityException - if a security manager denies write access
      Since:
      1.3

    • createDirs

      public static boolean createDirs(@Nullable File file) throws IOException
      Creates the directory named by the given file, including any nonexistent parent directories.

      If file is null, this method does nothing and returns false.

      Parameters:
      file - the directory to create, may be null
      Returns:
      true if the directory exists after the call, false if file is null
      Throws:
      FileAlreadyExistsException - if file exists and is not a directory
      AccessDeniedException - if the process does not have permission to create the directory
      IOException - if an I/O error occurs while creating the directory
      SecurityException - if a security manager denies write access
      Since:
      1.3

    • createDirs

      public static boolean createDirs(@Nullable String path) throws IOException
      Creates the directory named by the given path string, including any nonexistent parent directories.

      If path is null or blank, this method does nothing and returns false.

      Parameters:
      path - the path string of the directory to create, may be null or blank
      Returns:
      true if the directory exists after the call, false if path is null or blank
      Throws:
      InvalidPathException - if path cannot be converted to a Path
      FileAlreadyExistsException - if path exists and is not a directory
      AccessDeniedException - if the process does not have permission to create the directory
      IOException - if an I/O error occurs while creating the directory
      SecurityException - if a security manager denies write access
      Since:
      1.3

    • exists

      public static boolean exists(@Nullable File file)
      Checks if the specified file exists.
      Parameters:
      file - the file to check for existence
      Returns:
      true if the file is not null and exists; false otherwise
      Since:
      1.0

    • exists

      public static boolean exists(@Nullable Path path)
      Checks if the specified path exists.
      Parameters:
      path - the path to check for existence
      Returns:
      true if the path is not null and exists; false otherwise
      Since:
      1.0

    • exists

      public static boolean exists(@Nullable String path)
      Checks whether a file or directory exists at the specified path.
      Parameters:
      path - the file system path to check for existence
      Returns:
      true if the path is not null and a file or directory exists at the specified path; false otherwise, including when the path is blank or invalid
      Since:
      1.0

    • findFilesByExtensions

      public static List<Path> findFilesByExtensions(Path directory, String... extensions)
      Finds regular files located directly in directory whose file name ends with one of the given extensions (case-insensitive).

      This is non-recursive - it does not search subdirectories. If the directory cannot be read, an empty list is returned.

      Parameters:
      directory - the directory to list, must not be null
      extensions - one or more extensions to match, e.g. ".java" or "java"
      Returns:
      an unmodifiable list of matching files; never null, may be empty
      Throws:
      NullPointerException - if directory or extensions is null
      Since:
      1.4

    • isDirectory

      public static boolean isDirectory(@Nullable File file)
      Determines if the specified File is a directory.
      Parameters:
      file - the File object to be checked; if null, returns false
      Returns:
      true if the file exists and is a directory; false otherwise
      Since:
      1.0

    • isDirectory

      public static boolean isDirectory(@Nullable Path path)
      Determines if the specified Path represents an existing directory.
      Parameters:
      path - the Path object to be checked; if null, returns false
      Returns:
      true if the path exists and is a directory; false otherwise
      Since:
      1.0

    • isDirectory

      public static boolean isDirectory(@Nullable String path)
      Determines if the specified path string represents an existing directory.
      Parameters:
      path - the path string to be checked; if null or blank, returns false
      Returns:
      true if the specified path exists and is a directory; false otherwise, including when the path string is invalid
      Since:
      1.0

    • mkdirs

      public static boolean mkdirs(@Nullable File file)
      Creates the directory specified by the given file, including any nonexistent parent directories as necessary.

      Unlike createDirs(File), this method catches all exceptions and returns false on failure instead of throwing.

      Parameters:
      file - the directory to be created
      Returns:
      true if the directory was created successfully or already exists; false if the directory could not be created or file is null
      Since:
      1.0

    • mkdirs

      public static boolean mkdirs(@Nullable Path path)
      Creates the directory specified by the given path, including any nonexistent parent directories as necessary.

      Unlike createDirs(Path), this method catches all exceptions and returns false on failure instead of throwing.

      Parameters:
      path - the directory to be created
      Returns:
      true if the directory was created successfully or already exists; false if the directory could not be created or path is null
      Since:
      1.0

    • mkdirs

      public static boolean mkdirs(@Nullable String path)
      Creates the directory specified by the given path string, including any nonexistent parent directories as necessary.

      Unlike createDirs(String), this method catches all exceptions and returns false on failure instead of throwing.

      Parameters:
      path - the directory to be created
      Returns:
      true if the directory was created successfully or already exists; false if the directory could not be created or path is null, blank, or invalid
      Since:
      1.0

    • notExists

      public static boolean notExists(@Nullable File file)
      Checks if the specified file does not exist.

      Note: This method returns true for both null input and non-existent files. This diverges from Files.notExists(Path, java.nio.file.LinkOption...) which returns false when existence cannot be determined. The behavior here is a deliberate choice to simplify null-checking call sites.

      Parameters:
      file - the file to check for non-existence
      Returns:
      true if the file is null or does not exist; false otherwise
      Since:
      1.0

    • notExists

      public static boolean notExists(@Nullable Path path)
      Checks if the specified path does not exist.

      Note: This method returns true for both null input and non-existent paths. This diverges from Files.notExists(Path, java.nio.file.LinkOption...) which returns false when existence cannot be determined. The behavior here is a deliberate choice to simplify null-checking call sites.

      Parameters:
      path - the path to check for non-existence
      Returns:
      true if the path is null or does not exist; false otherwise
      Since:
      1.0

    • notExists

      public static boolean notExists(@Nullable String path)
      Checks whether a file or directory does not exist at the specified path.

      Note: This method returns true for null, blank, invalid, or non-existent paths. This diverges from Files.notExists(Path, java.nio.file.LinkOption...) which returns false when existence cannot be determined. The behavior here is a deliberate choice to simplify null-checking call sites.

      Parameters:
      path - the file system path to check for non-existence
      Returns:
      true if the path is null or no file or directory exists at the specified path; false otherwise
      Since:
      1.0

    • resolveFile

      public static File resolveFile(@Nullable File base, @Nullable String @Nullable ... segments)
      Resolves a file path by joining a base file with additional path segments.

      This method constructs a file path by appending one or more path segments to a base file. null or empty segments are silently skipped. To keep resolution relative to base, segments starting with "/" have the leading slash stripped before resolving. This is a deliberate design choice that prevents absolute segments from resetting the path to the filesystem root, which would violate the expectation that resolution is relative to the base. Callers passing absolute Unix paths should pre-strip the slash themselves if they intend root-relative semantics.

      If base is null, this behaves like new File(""): segments are resolved against the current directory.

      Parameters:
      base - the base file path to start from; may be null
      segments - additional path segments to append, in order; may be null, and individual null or empty segments are silently skipped
      Returns:
      a File representing the resolved path
      Since:
      1.0