Interface FileSystem

public interface FileSystem
Contains a broad set of operations for manipulating files on the file system.

A (potential) blocking and non blocking version of each operation is provided.

The non blocking versions take a handler which is called when the operation completes or an error occurs.

The blocking versions are named xxxBlocking and return the results, or throw exceptions directly. In many cases, depending on the operating system and file system some of the potentially blocking operations can return quickly, which is why we provide them, but it's highly recommended that you test how long they take to return in your particular application before using them on an event loop.

Please consult the documentation for more information on file system support.

Author:
Tim Fox

  • Method Details

    • copy

      Future<Void> copy(String from, String to)
      Copy a file from the path from to path to, asynchronously.

      The copy will fail if the destination already exists.

      Parameters:
      from - the path to copy from
      to - the path to copy to
      Returns:
      a future notified on completion

    • copy

      Future<Void> copy(String from, String to, CopyOptions options)
      Copy a file from the path from to path to, asynchronously.
      Parameters:
      from - the path to copy from
      to - the path to copy to
      options - options describing how the file should be copied
      Returns:
      a future notified on completion

    • copyBlocking

      FileSystem copyBlocking(String from, String to)
      Blocking version of copy(String, String)

    • copyRecursive

      Future<Void> copyRecursive(String from, String to, boolean recursive)
      Copy a file from the path from to path to, asynchronously.

      If recursive is true and from represents a directory, then the directory and its contents will be copied recursively to the destination to.

      The copy will fail if the destination if the destination already exists.

      Parameters:
      from - the path to copy from
      to - the path to copy to
      recursive -
      Returns:
      a future notified on completion

    • copyRecursiveBlocking

      FileSystem copyRecursiveBlocking(String from, String to, boolean recursive)
      Blocking version of copyRecursive(String, String, boolean)

    • move

      Future<Void> move(String from, String to)
      Move a file from the path from to path to, asynchronously.

      The move will fail if the destination already exists.

      Parameters:
      from - the path to copy from
      to - the path to copy to
      Returns:
      a future notified on completion

    • move

      Future<Void> move(String from, String to, CopyOptions options)
      Move a file from the path from to path to, asynchronously.
      Parameters:
      from - the path to copy from
      to - the path to copy to
      options - options describing how the file should be copied
      Returns:
      a future notified on completion

    • moveBlocking

      FileSystem moveBlocking(String from, String to)
      Blocking version of move(String, String)

    • truncate

      Future<Void> truncate(String path, long len)
      Truncate the file represented by path to length len in bytes, asynchronously.

      The operation will fail if the file does not exist or len is less than zero.

      Parameters:
      path - the path to the file
      len - the length to truncate it to
      Returns:
      a future notified on completion

    • truncateBlocking

      FileSystem truncateBlocking(String path, long len)
      Blocking version of truncate(String, long)

    • chmod

      Future<Void> chmod(String path, String perms)
      Change the permissions on the file represented by path to perms, asynchronously.

      The permission String takes the form rwxr-x--- as specified here.

      Parameters:
      path - the path to the file
      perms - the permissions string
      Returns:
      a future notified on completion

    • chmodBlocking

      FileSystem chmodBlocking(String path, String perms)
      Blocking version of chmod(String, String)

    • chmodRecursive

      Future<Void> chmodRecursive(String path, String perms, String dirPerms)
      Change the permissions on the file represented by path to perms, asynchronously.

      The permission String takes the form rwxr-x--- as specified in {here}.

      If the file is directory then all contents will also have their permissions changed recursively. Any directory permissions will be set to dirPerms, whilst any normal file permissions will be set to perms.

      Parameters:
      path - the path to the file
      perms - the permissions string
      dirPerms - the directory permissions
      Returns:
      a future notified on completion

    • chmodRecursiveBlocking

      FileSystem chmodRecursiveBlocking(String path, String perms, String dirPerms)
      Blocking version of chmodRecursive(String, String, String)

    • chown

      Future<Void> chown(String path, String user, String group)
      Change the ownership on the file represented by path to user and {code group}, asynchronously.
      Parameters:
      path - the path to the file
      user - the user name, null will not change the user name
      group - the user group, null will not change the user group name
      Returns:
      a future notified on completion

    • chownBlocking

      FileSystem chownBlocking(String path, String user, String group)
      Blocking version of chown(String, String, String)

    • props

      Future<FileProps> props(String path)
      Obtain properties for the file represented by path, asynchronously.

      If the file is a link, the link will be followed.

      Parameters:
      path - the path to the file
      Returns:
      a future notified on completion

    • propsBlocking

      FileProps propsBlocking(String path)
      Blocking version of props(String)

    • lprops

      Future<FileProps> lprops(String path)
      Obtain properties for the link represented by path, asynchronously.

      The link will not be followed.

      Parameters:
      path - the path to the file
      Returns:
      a future notified on completion

    • lpropsBlocking

      FileProps lpropsBlocking(String path)
      Blocking version of lprops(String)

    • link

      Future<Void> link(String link, String existing)
      Create a hard link on the file system from link to existing, asynchronously.
      Parameters:
      link - the link
      existing - the link destination
      Returns:
      a future notified on completion

    • linkBlocking

      FileSystem linkBlocking(String link, String existing)
      Blocking version of link(String, String)

    • symlink

      Future<Void> symlink(String link, String existing)
      Create a symbolic link on the file system from link to existing, asynchronously.
      Parameters:
      link - the link
      existing - the link destination
      Returns:
      a future notified on completion

    • symlinkBlocking

      FileSystem symlinkBlocking(String link, String existing)
      Blocking version of link(String, String)

    • unlink

      Future<Void> unlink(String link)
      Unlinks the link on the file system represented by the path link, asynchronously.
      Parameters:
      link - the link
      Returns:
      a future notified on completion

    • unlinkBlocking

      FileSystem unlinkBlocking(String link)
      Blocking version of unlink(String)

    • readSymlink

      Future<String> readSymlink(String link)
      Returns the path representing the file that the symbolic link specified by link points to, asynchronously.
      Parameters:
      link - the link
      Returns:
      a future notified on completion

    • readSymlinkBlocking

      String readSymlinkBlocking(String link)
      Blocking version of readSymlink(String)

    • delete

      Future<Void> delete(String path)
      Deletes the file represented by the specified path, asynchronously.
      Parameters:
      path - path to the file
      Returns:
      a future notified on completion

    • deleteBlocking

      FileSystem deleteBlocking(String path)
      Blocking version of delete(String)

    • deleteRecursive

      Future<Void> deleteRecursive(String path)
      Deletes the file represented by the specified path, asynchronously.

      If the path represents a directory and recursive = true then the directory and its contents will be deleted recursively.

      Parameters:
      path - path to the file
      Returns:
      a future notified on completion

    • deleteRecursiveBlocking

      FileSystem deleteRecursiveBlocking(String path)
      Blocking version of deleteRecursive(String)

    • mkdir

      Future<Void> mkdir(String path)
      Create the directory represented by path, asynchronously.

      The operation will fail if the directory already exists.

      Parameters:
      path - path to the file
      Returns:
      a future notified on completion

    • mkdirBlocking

      FileSystem mkdirBlocking(String path)
      Blocking version of mkdir(String)

    • mkdir

      Future<Void> mkdir(String path, String perms)
      Create the directory represented by path, asynchronously.

      The new directory will be created with permissions as specified by perms.

      The permission String takes the form rwxr-x--- as specified in here.

      The operation will fail if the directory already exists.

      Parameters:
      path - path to the file
      perms - the permissions string
      Returns:
      a future notified on completion

    • mkdirBlocking

      FileSystem mkdirBlocking(String path, String perms)
      Blocking version of mkdir(String, String)

    • mkdirs

      Future<Void> mkdirs(String path)
      Create the directory represented by path and any non existent parents, asynchronously.

      The operation will fail if the path already exists but is not a directory.

      Parameters:
      path - path to the file
      Returns:
      a future notified on completion

    • mkdirsBlocking

      FileSystem mkdirsBlocking(String path)
      Blocking version of mkdirs(String)

    • mkdirs

      Future<Void> mkdirs(String path, String perms)
      Create the directory represented by path and any non existent parents, asynchronously.

      The new directory will be created with permissions as specified by perms.

      The permission String takes the form rwxr-x--- as specified in here.

      The operation will fail if the path already exists but is not a directory.

      Parameters:
      path - path to the file
      perms - the permissions string
      Returns:
      a future notified on completion

    • mkdirsBlocking

      FileSystem mkdirsBlocking(String path, String perms)
      Blocking version of mkdirs(String, String)

    • readDir

      Future<List<String>> readDir(String path)
      Read the contents of the directory specified by path, asynchronously.

      The result is an array of String representing the paths of the files inside the directory.

      Parameters:
      path - path to the file
      Returns:
      a future notified on completion

    • readDirBlocking

      List<String> readDirBlocking(String path)
      Blocking version of readDir(String)

    • readDir

      Future<List<String>> readDir(String path, String filter)
      Read the contents of the directory specified by path, asynchronously.

      The parameter filter is a regular expression. If filter is specified then only the paths that match @{filter}will be returned.

      The result is an array of String representing the paths of the files inside the directory.

      Parameters:
      path - path to the directory
      filter - the filter expression
      Returns:
      a future notified on completion

    • readDirBlocking

      List<String> readDirBlocking(String path, String filter)
      Blocking version of readDir(String, String)

    • readFile

      Future<Buffer> readFile(String path)
      Reads the entire file as represented by the path path as a Buffer, asynchronously.

      Do not use this method to read very large files or you risk running out of available RAM.

      Parameters:
      path - path to the file
      Returns:
      a future notified on completion

    • readFileBlocking

      Buffer readFileBlocking(String path)
      Blocking version of readFile(String)

    • writeFile

      Future<Void> writeFile(String path, Buffer data)
      Creates the file, and writes the specified Buffer data to the file represented by the path path, asynchronously.
      Parameters:
      path - path to the file
      Returns:
      a future notified on completion

    • writeFileBlocking

      FileSystem writeFileBlocking(String path, Buffer data)
      Blocking version of writeFile(String, Buffer)

    • open

      Future<AsyncFile> open(String path, OpenOptions options)
      Open the file represented by path, asynchronously.

      The file is opened for both reading and writing. If the file does not already exist it will be created.

      Parameters:
      path - path to the file
      options - options describing how the file should be opened
      Returns:
      a future notified on completion

    • openBlocking

      AsyncFile openBlocking(String path, OpenOptions options)
      Blocking version of open(String, io.vertx.core.file.OpenOptions)

    • createFile

      Future<Void> createFile(String path)
      Creates an empty file with the specified path, asynchronously.
      Parameters:
      path - path to the file
      Returns:
      a future notified on completion

    • createFileBlocking

      FileSystem createFileBlocking(String path)
      Blocking version of createFile(String)

    • createFile

      Future<Void> createFile(String path, String perms)
      Creates an empty file with the specified path and permissions perms, asynchronously.
      Parameters:
      path - path to the file
      perms - the permissions string
      Returns:
      a future notified on completion

    • createFileBlocking

      FileSystem createFileBlocking(String path, String perms)
      Blocking version of createFile(String, String)

    • exists

      Future<Boolean> exists(String path)
      Determines whether the file as specified by the path path exists, asynchronously.
      Parameters:
      path - path to the file
      Returns:
      a future notified on completion

    • existsBlocking

      boolean existsBlocking(String path)
      Blocking version of exists(String)

    • fsProps

      Future<FileSystemProps> fsProps(String path)
      Returns properties of the file-system being used by the specified path, asynchronously.
      Parameters:
      path - path to anywhere on the filesystem
      Returns:
      a future notified on completion

    • fsPropsBlocking

      FileSystemProps fsPropsBlocking(String path)
      Blocking version of fsProps(String)

    • createTempDirectory

      Future<String> createTempDirectory(String prefix)
      Creates a new directory in the default temporary-file directory, using the given prefix to generate its name, asynchronously.

      As with the File.createTempFile methods, this method is only part of a temporary-file facility.A shutdown-hook, or the File.deleteOnExit() mechanism may be used to delete the directory automatically.

      Parameters:
      prefix - the prefix string to be used in generating the directory's name; may be null
      Returns:
      a future notified on completion

    • createTempDirectoryBlocking

      String createTempDirectoryBlocking(String prefix)
      Blocking version of createTempDirectory(String)

    • createTempDirectory

      Future<String> createTempDirectory(String prefix, String perms)
      Creates a new directory in the default temporary-file directory, using the given prefix to generate its name, asynchronously.

      The new directory will be created with permissions as specified by perms.

      The permission String takes the form rwxr-x--- as specified in here.

      As with the File.createTempFile methods, this method is only part of a temporary-file facility.A shutdown-hook, or the File.deleteOnExit() mechanism may be used to delete the directory automatically.

      Parameters:
      prefix - the prefix string to be used in generating the directory's name; may be null
      perms - the permissions string
      Returns:
      a future notified on completion

    • createTempDirectoryBlocking

      String createTempDirectoryBlocking(String prefix, String perms)
      Blocking version of createTempDirectory(String, String)

    • createTempDirectory

      Future<String> createTempDirectory(String dir, String prefix, String perms)
      Creates a new directory in the directory provided by the path path, using the given prefix to generate its name, asynchronously.

      The new directory will be created with permissions as specified by perms.

      The permission String takes the form rwxr-x--- as specified in here.

      As with the File.createTempFile methods, this method is only part of a temporary-file facility.A shutdown-hook, or the File.deleteOnExit() mechanism may be used to delete the directory automatically.

      Parameters:
      dir - the path to directory in which to create the directory
      prefix - the prefix string to be used in generating the directory's name; may be null
      perms - the permissions string
      Returns:
      a future notified on completion

    • createTempDirectoryBlocking

      String createTempDirectoryBlocking(String dir, String prefix, String perms)
      Blocking version of createTempDirectory(String, String, String)

    • createTempFile

      Future<String> createTempFile(String prefix, String suffix)
      Creates a new file in the default temporary-file directory, using the given prefix and suffix to generate its name, asynchronously.

      As with the File.createTempFile methods, this method is only part of a temporary-file facility.A shutdown-hook, or the File.deleteOnExit() mechanism may be used to delete the directory automatically.

      Parameters:
      prefix - the prefix string to be used in generating the directory's name; may be null
      suffix - the suffix string to be used in generating the file's name; may be null, in which case ".tmp" is used
      Returns:
      a future notified on completion

    • createTempFileBlocking

      String createTempFileBlocking(String prefix, String suffix)
      Blocking version of createTempFile(String, String)

    • createTempFile

      Future<String> createTempFile(String prefix, String suffix, String perms)
      Creates a new file in the directory provided by the path dir, using the given prefix and suffix to generate its name, asynchronously.

      As with the File.createTempFile methods, this method is only part of a temporary-file facility.A shutdown-hook, or the File.deleteOnExit() mechanism may be used to delete the directory automatically.

      Parameters:
      prefix - the prefix string to be used in generating the directory's name; may be null
      suffix - the suffix string to be used in generating the file's name; may be null, in which case ".tmp" is used
      Returns:
      a future notified on completion

    • createTempFileBlocking

      String createTempFileBlocking(String prefix, String suffix, String perms)
      Blocking version of createTempFile(String, String, String)

    • createTempFile

      Future<String> createTempFile(String dir, String prefix, String suffix, String perms)
      Creates a new file in the directory provided by the path dir, using the given prefix and suffix to generate its name, asynchronously.

      The new directory will be created with permissions as specified by perms.

      The permission String takes the form rwxr-x--- as specified in here.

      As with the File.createTempFile methods, this method is only part of a temporary-file facility.A shutdown-hook, or the File.deleteOnExit() mechanism may be used to delete the directory automatically.

      Parameters:
      dir - the path to directory in which to create the directory
      prefix - the prefix string to be used in generating the directory's name; may be null
      suffix - the suffix string to be used in generating the file's name; may be null, in which case ".tmp" is used
      perms - the permissions string
      Returns:
      a future notified on completion

    • createTempFileBlocking

      String createTempFileBlocking(String dir, String prefix, String suffix, String perms)
      Blocking version of createTempFile(String, String, String, String)