Module org.tquadrat.foundation.util
Package org.tquadrat.foundation.util

Class IOUtils

java.lang.Object
org.tquadrat.foundation.util.IOUtils
@ClassVersion(sourceVersion="$Id: IOUtils.java 1092 2024-02-01 22:49:38Z tquadrat $") @UtilityClass public final class IOUtils extends Object
Some I/O, file, file system and network related helper and convenience methods.
Author:
Thomas Thrien (thomas.thrien@tquadrat.org)
Version:
$Id: IOUtils.java 1092 2024-02-01 22:49:38Z tquadrat $
Since:
0.0.5
UML Diagram
UML Diagram for "org.tquadrat.foundation.util.IOUtils"⁠

UML Diagram for "org.tquadrat.foundation.util.IOUtils"

UML Diagram for "org.tquadrat.foundation.util.IOUtils"⁠

  • Field Details

  • Constructor Details

    • IOUtils

      private IOUtils()
      No instance allowed for this class.

  • Method Details

    • closeQuietly

      @API(status=STABLE, since="0.0.5") public static final void closeQuietly(AutoCloseable closeable)
      Unconditionally closes an object instance of a class that implements the interface AutoCloseable.
      Equivalent to AutoCloseable.close(), except any exceptions will be ignored. This is typically used in finally blocks.

      Even after the introduction of try-with-resources with Java 7, this method can be still helpful.
      Parameters:
      closeable - The AutoCloseable instance to close, can be null or already closed.

    • createDirectories

      @API(status=STABLE, since="0.0.6") public static final File createDirectories(File dir, FileAttribute<?>... attributes) throws IOException

      Creates a new directory by creating all nonexistent parent directories first. Unlike the createDirectory(File,FileAttribute...) method, an exception is not thrown if the directory could not be created because it already exists.

      The attributes parameter is optional to set file-attributes atomically when creating the non-existent directories. Each file attribute is identified by its name. If more than one attribute of the same name is included in the array then all but the last occurrence is ignored.

      If this method fails, then it may do so after creating some, but not all, of the parent directories.

      Parameters:
      dir - The directory to create.
      attributes - An optional list of file attributes to set atomically when creating the directory.
      Returns:
      The directory.
      Throws:
      UnsupportedOperationException - The attributes array contains an attribute that cannot be set atomically when creating the directory.
      FileAlreadyExistsException - The dir exists but is not a directory (optional specific exception).
      IOException - An I/O error occurred.
      SecurityException - In the case a security manager is installed, the checkWrite() method is invoked prior to attempting to create a directory and its checkRead() is invoked for each parent directory that is checked. If dir is not an absolute path then its File.getAbsoluteFile() method may need to be invoked to get its absolute path. This may invoke the security manager's checkPropertyAccess() method to check access to the system property user.dir.
      Since:
      0.0.6
      See Also:

    • createDirectory

      @API(status=STABLE, since="0.0.6") public static File createDirectory(File dir, FileAttribute<?>... attributes) throws IOException

      Creates a new directory. The check for the existence of the file and the creation of the directory if it does not exist are a single operation that is atomic with respect to all other filesystem activities that might affect the directory. The createDirectories() method should be used where it is required to create all nonexistent parent directories first.

      The attributes parameter is optional to set file-attributes atomically when creating the directory. Each attribute is identified by its name. If more than one attribute of the same name is included in the array then all but the last occurrence is ignored.

      Parameters:
      dir - The directory to create.
      attributes - An optional list of file attributes to set atomically when creating the directory
      Returns:
      The directory.
      Throws:
      UnsupportedOperationException - The attributes array contains an attribute that cannot be set atomically when creating the directory.
      FileAlreadyExistsException - A directory could not otherwise be created because a file of that name already exists (optional specific exception).
      IOException - An I/O error occurred or the parent directory does not exist.
      SecurityException - In the case a security manager is installed, the checkWrite() method is invoked to check write access to the new directory.
      Since:
      0.0.6

    • createTempDirectory

      @API(status=STABLE, since="0.0.6") public static final File createTempDirectory() throws IOException

      Creates a directory named after the account name of the current user (determined by the system property "user.name") in the default temp folder, determined by the system property "java.io.tmpdir".

      The access rights are set for the current user only (for UNIX, it would be 700).

      The new directory will not be removed automatically after program termination.

      The class File provides a static method createTempFile() that creates a temporary file in the default temporary folder. As this may be not a problem on a single-user Windows system with default configuration, it will cause security problems on UNIX-like systems. Therefore, it is recommended, to use File.createTempFile(String, String, File) instead, like this:

      File tempFile = File.createTempFile( "PREFIX", "EXT", createTempDirectory() );

      This will guarantee that the temporary files cannot be read by other users.

      Returns:
      The new temporary directory; it is guaranteed that the directory exists after the call to this method returned.
      Throws:
      IOException - Something has gone wrong.
      Since:
      0.0.6

    • createTempDirectory

      @API(status=STABLE, since="0.0.6") public static Path createTempDirectory(File dir, String prefix, FileAttribute<?>... attributes) throws IOException

      Creates a new temporary directory in the specified directory, using the given prefix to generate its name.

      The details as to how the name of the directory is constructed is implementation dependent and therefore not specified. Where possible the prefix is used to construct candidate names.

      The attributes parameter is optional to set file-attributes atomically when creating the directory. Each attribute is identified by its name. If more than one attribute of the same name is included in the array then all but the last occurrence is ignored.

      Parameters:
      dir - The directory in which to create the temporary directory.
      prefix - The prefix string to be used in generating the directory's name; may be null.
      attributes - An optional list of file attributes to set atomically when creating the directory.
      Returns:
      The path to the newly created directory that did not exist before this method was invoked.
      Throws:
      IllegalArgumentException - The prefix cannot be used to generate a candidate directory name.
      UnsupportedOperationException - The attributes array contains an attribute that cannot be set atomically when creating the directory.
      IOException - An I/O error occurs or dir does not exist.
      SecurityException - In the case a security manager is installed, the checkWrite() method is invoked to check write access when creating the directory.
      Since:
      0.0.6
      See Also:

    • createTempDirectory

      @API(status=STABLE, since="0.0.6") public static File createTempDirectory(String prefix, FileAttribute<?>... attributes) throws IOException

      Creates a new directory in the default temporary-file directory, using the given prefix to generate its name.

      This method works in exactly the manner specified by createTempDirectory(File,String,FileAttribute[]) method for the case that the dir parameter is the temporary-file directory.

      Parameters:
      prefix - The prefix string to be used in generating the directory's name; may be null.
      attributes - An optional list of file attributes to set atomically when creating the directory.
      Returns:
      The File instance to the newly created directory that did not exist before this method was invoked.
      Throws:
      IllegalArgumentException - The prefix cannot be used to generate a candidate directory name.
      UnsupportedOperationException - The attributes array contains an attribute that cannot be set atomically when creating the directory.
      IOException - An I/O error occurred or the temporary-file directory does not exist.
      SecurityException - In the case a security manager is installed, the checkWrite() method is invoked to check write access when creating the directory.
      Since:
      0.0.6
      See Also:

    • deleteFolder

      public static final void deleteFolder(Path folder) throws IOException

      Deletes the folder (or file) that is determined by the given Path instance. If the argument denotes a directory, the method will remove its contents first, recursively.

      Parameters:
      folder - The folder to remove; despite the name of the argument and the method, this can be also a plain file.
      Throws:
      IOException - A problem occurred when deleting the Path.

    • deleteFolder

      public static final void deleteFolder(File folder) throws IOException

      Deletes the folder (or file) that is determined by the given File. instance. If the argument denotes a directory, the method will remove its contents first, recursively.

      Calls deleteFolder(Path) internally.

      Parameters:
      folder - The folder to remove; despite the name of the argument and the method, this can be also a plain file.
      Throws:
      IOException - A problem occurred when deleting the Path.

    • determineCheckSum

      @API(status=STABLE, since="0.0.5") public static final String determineCheckSum(File file, String algorithm) throws IOException, NoSuchAlgorithmException

      Calculates the check sum for the given file, using the algorithm with the given name.

      If the name is one of

      • CRC32
      • Adler32

      the method uses CRC32 or Adler32 for the calculation, any other name is taken as the name for a MessageDigest; all JVMs know

      • MD5
      • SHA1

      others can be added by installing additional security providers.

      This method calls determineCheckSum(Path, String) internally.

      Parameters:
      file - The file to process.
      algorithm - The name for the algorithm to use for the check sum calculation.
      Returns:
      The check sum as a hex string.
      Throws:
      IOException - Problems to process the file.
      NoSuchAlgorithmException - The provided algorithm does not exist or the provider for it is not installed properly.

    • determineCheckSum

      @API(status=STABLE, since="0.0.5") public static final String determineCheckSum(Path file, String algorithm) throws IOException, NoSuchAlgorithmException

      Calculates the check sum for the given file, using the algorithm with the given name.

      If the name is one of

      • CRC32
      • Adler32

      the method uses CRC32 or Adler32 for the calculation, any other name is taken as the name for a MessageDigest; all JVMs know

      • MD5
      • SHA1

      others can be added by installing additional security providers.

      Parameters:
      file - The file to process.
      algorithm - The name for the algorithm to use for the check sum calculation.
      Returns:
      The check sum as a hex string.
      Throws:
      IOException - Problems to process the file.
      NoSuchAlgorithmException - The provided algorithm does not exist or the provider for it is not installed properly.

    • determineCheckSum

      @API(status=STABLE, since="0.0.5") public static final long determineCheckSum(File file, Checksum algorithm) throws IOException
      Calculates the check sum for the given file, using provided check sum algorithm implementation.
      Parameters:
      file - The file to process.
      algorithm - The check sum algorithm to use for the check sum calculation.
      Returns:
      The check sum.
      Throws:
      IOException - Problems to process the file.

    • determineCheckSum

      @API(status=STABLE, since="0.0.5") public static final long determineCheckSum(Path file, Checksum algorithm) throws IOException
      Calculates the check sum for the given file, using provided check sum algorithm implementation.
      Parameters:
      file - The file to process.
      algorithm - The check sum algorithm to use for the check sum calculation.
      Returns:
      The check sum.
      Throws:
      IOException - Problems to process the file.

    • determineCheckSum

      @API(status=STABLE, since="0.0.5") public static final byte[] determineCheckSum(File file, MessageDigest algorithm) throws IOException
      Calculates the check sum for the given file, using the provided MessageDigest.
      Parameters:
      file - The file to process.
      algorithm - The MessageDigest to use for the check sum calculation.
      Returns:
      The check sum as a byte array.
      Throws:
      IOException - Problems to process the file.

    • determineCheckSum

      @API(status=STABLE, since="0.0.5") public static final byte[] determineCheckSum(Path file, MessageDigest algorithm) throws IOException
      Calculates the check sum for the given file, using the provided MessageDigest.
      Parameters:
      file - The file to process.
      algorithm - The MessageDigest to use for the check sum calculation.
      Returns:
      The check sum as a byte array.
      Throws:
      IOException - Problems to process the file.

    • getNullAppendable

      @API(status=STABLE, since="0.0.5") public static final Appendable getNullAppendable()
      Returns an Appendable that just swallows any data that is written to it, like the /dev/null device of a Unix or Linux machine, or NUL: on Windows.
      Returns:
      A null appendable.
      See Also:

    • getSystemTempFolder

      @API(status=STABLE, since="0.4.0") public static final Path getSystemTempFolder()
      Returns the Path object that represents the system's default temporary folder as specified in "java.io.tmpdir".
      Returns:
      The system temp folder.
      Since:
      0.4.0

    • getUncloseableOut

      @API(status=STABLE, since="0.0.7") public static final PrintStream getUncloseableOut()

      Returns System.out with a non-functional OutputStream.close() method.

      Assume the following scenario:

        …
  Optional<File> outputFile = …
  …
  PrintStream outputStream = outputFile.isPresent() ? new PrintStream( new FileOutputStream( outputFile.get() ) ) : IOUtils.getUncloseableOut();
  try( outputStream )
  {
      /**
       * Print something ...
       */
       …
  }
  …

      The output stream will be close at the end of the try block; this is desired in case of a FileOutputStream, but totally not wanted if the output stream is System.out.

      Returns:
      System.out without the close() method.

    • loadToString

      @API(status=STABLE, since="0.0.5") public static final String loadToString(Reader reader) throws IOException

      Reads the complete content of the provided Reader into a String.

      Obviously this method is feasible only for files with a limited size.

      Parameters:
      reader - The Reader instance.
      Returns:
      The content of the provided Reader.
      Throws:
      IOException - Problems on reading from the Reader.