/*
 * Copyright (c) 2011-2017 Contributors to the Eclipse Foundation
 *
 * This program and the accompanying materials are made available under the
 * terms of the Eclipse Public License 2.0 which is available at
 * http://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
 * which is available at https://www.apache.org/licenses/LICENSE-2.0.
 *
 * SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
 */

package io.vertx.core.file;

import io.vertx.codegen.annotations.Fluent;
import io.vertx.codegen.annotations.Nullable;
import io.vertx.codegen.annotations.VertxGen;
import io.vertx.core.AsyncResult;
import io.vertx.core.Handler;
import io.vertx.core.buffer.Buffer;

import java.util.List;

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/**
 * Contains a broad set of operations for manipulating files on the file system.
 * <p>
 * A (potential) blocking and non blocking version of each operation is provided.
 * <p>
 * The non blocking versions take a handler which is called when the operation completes or an error occurs.
 * <p>
 * The blocking versions are named {@code 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.
 * <p>
 * Please consult the documentation for more information on file system support.
 *
 *
 * @author <a href="http://tfox.org">Tim Fox</a>
 */
@VertxGen
public interface FileSystem {

  
Copy a file from the path from to path to, asynchronously. 

The copy will fail if the destination already exists.
Params:
from –  the path to copy from
to –  the path to copy to
handler –  the handler that will be called on completion
Returns:
a reference to this, so the API can be used fluently/**
   * Copy a file from the path {@code from} to path {@code to}, asynchronously.
   * <p>
   * The copy will fail if the destination already exists.
   *
   * @param from  the path to copy from
   * @param to  the path to copy to
   * @param handler  the handler that will be called on completion
   * @return a reference to this, so the API can be used fluently
   */
  @Fluent
  FileSystem copy(String from, String to, Handler<AsyncResult<Void>> handler);

  
Copy a file from the path from to path to, asynchronously. 
Params:
from –    the path to copy from
to –      the path to copy to
options – options describing how the file should be copied
handler – the handler that will be called on completion
Returns:
a reference to this, so the API can be used fluently/**
   * Copy a file from the path {@code from} to path {@code to}, asynchronously.
   *
   * @param from    the path to copy from
   * @param to      the path to copy to
   * @param options options describing how the file should be copied
   * @param handler the handler that will be called on completion
   * @return a reference to this, so the API can be used fluently
   */
  @Fluent
  FileSystem copy(String from, String to, CopyOptions options, Handler<AsyncResult<Void>> handler);

  
Blocking version of copy(String, String, Handler<AsyncResult<Void>>) /**
   * Blocking version of {@link #copy(String, String, Handler)}
   */
  @Fluent
  FileSystem copyBlocking(String from, String to) ;

  
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.
Params:
from –  the path to copy from
to –  the path to copy to
recursive – 
handler –  the handler that will be called on completion
Returns:
a reference to this, so the API can be used fluently/**
   * Copy a file from the path {@code from} to path {@code to}, asynchronously.
   * <p>
   * If {@code recursive} is {@code true} and {@code from} represents a directory, then the directory and its contents
   * will be copied recursively to the destination {@code to}.
   * <p>
   * The copy will fail if the destination if the destination already exists.
   *
   * @param from  the path to copy from
   * @param to  the path to copy to
   * @param recursive
   * @param handler  the handler that will be called on completion
   * @return a reference to this, so the API can be used fluently
   */
  @Fluent
  FileSystem copyRecursive(String from, String to, boolean recursive, Handler<AsyncResult<Void>> handler);

  
Blocking version of copyRecursive(String, String, boolean, Handler<AsyncResult<Void>>) /**
   * Blocking version of {@link #copyRecursive(String, String, boolean, Handler)}
   */
  @Fluent
  FileSystem copyRecursiveBlocking(String from, String to, boolean recursive) ;

  
Move a file from the path from to path to, asynchronously. 

The move will fail if the destination already exists.
Params:
from –  the path to copy from
to –  the path to copy to
handler –  the handler that will be called on completion
Returns:
a reference to this, so the API can be used fluently/**
   * Move a file from the path {@code from} to path {@code to}, asynchronously.
   * <p>
   * The move will fail if the destination already exists.
   *
   * @param from  the path to copy from
   * @param to  the path to copy to
   * @param handler  the handler that will be called on completion
   * @return a reference to this, so the API can be used fluently
   */
  @Fluent
  FileSystem move(String from, String to, Handler<AsyncResult<Void>> handler);

  
Move a file from the path from to path to, asynchronously. 
Params:
from –    the path to copy from
to –      the path to copy to
options – options describing how the file should be copied
handler – the handler that will be called on completion
Returns:
a reference to this, so the API can be used fluently/**
   * Move a file from the path {@code from} to path {@code to}, asynchronously.
   *
   * @param from    the path to copy from
   * @param to      the path to copy to
   * @param options options describing how the file should be copied
   * @param handler the handler that will be called on completion
   * @return a reference to this, so the API can be used fluently
   */
  @Fluent
  FileSystem move(String from, String to, CopyOptions options, Handler<AsyncResult<Void>> handler);

  
Blocking version of move(String, String, Handler<AsyncResult<Void>>) /**
   * Blocking version of {@link #move(String, String, Handler)}
   */
  @Fluent
  FileSystem moveBlocking(String from, String to) ;

  
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. 
Params:
path –  the path to the file
len –  the length to truncate it to
handler –  the handler that will be called on completion
Returns:
a reference to this, so the API can be used fluently/**
   * Truncate the file represented by {@code path} to length {@code len} in bytes, asynchronously.
   * <p>
   * The operation will fail if the file does not exist or {@code len} is less than {@code zero}.
   *
   * @param path  the path to the file
   * @param len  the length to truncate it to
   * @param handler  the handler that will be called on completion
   * @return a reference to this, so the API can be used fluently
   */
  @Fluent
  FileSystem truncate(String path, long len, Handler<AsyncResult<Void>> handler);

  
Blocking version of truncate(String, long, Handler<AsyncResult<Void>>) /**
   * Blocking version of {@link #truncate(String, long, Handler)}
   */
  @Fluent
  FileSystem truncateBlocking(String path, long len) ;

  
Change the permissions on the file represented by path to perms, asynchronously. 

The permission String takes the form rwxr-x--- as
specified here.
Params:
path –  the path to the file
perms –  the permissions string
handler –  the handler that will be called on completion
Returns:
a reference to this, so the API can be used fluently/**
   * Change the permissions on the file represented by {@code path} to {@code perms}, asynchronously.
   * <p>
   * The permission String takes the form rwxr-x--- as
   * specified <a href="http://download.oracle.com/javase/7/docs/api/java/nio/file/attribute/PosixFilePermissions.html">here</a>.
   *
   * @param path  the path to the file
   * @param perms  the permissions string
   * @param handler  the handler that will be called on completion
   * @return a reference to this, so the API can be used fluently
   */
  @Fluent
  FileSystem chmod(String path, String perms, Handler<AsyncResult<Void>> handler);

  
Blocking version of chmod(String, String, Handler<AsyncResult<Void>>) /**
   * Blocking version of {@link #chmod(String, String, Handler) }
   */
  @Fluent
  FileSystem chmodBlocking(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 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. 
Params:
path –  the path to the file
perms –  the permissions string
dirPerms –  the directory permissions
handler –  the handler that will be called on completion
Returns:
a reference to this, so the API can be used fluently/**
   * Change the permissions on the file represented by {@code path} to {@code perms}, asynchronously.<p>
   * The permission String takes the form rwxr-x--- as
   * specified in {<a href="http://download.oracle.com/javase/7/docs/api/java/nio/file/attribute/PosixFilePermissions.html">here</a>}.
   * <p>
   * If the file is directory then all contents will also have their permissions changed recursively. Any directory permissions will
   * be set to {@code dirPerms}, whilst any normal file permissions will be set to {@code perms}.
   *
   * @param path  the path to the file
   * @param perms  the permissions string
   * @param dirPerms  the directory permissions
   * @param handler  the handler that will be called on completion
   * @return a reference to this, so the API can be used fluently
   */
  @Fluent
  FileSystem chmodRecursive(String path, String perms, String dirPerms, Handler<AsyncResult<Void>> handler);

  
Blocking version of chmodRecursive(String, String, String, Handler<AsyncResult<Void>>) /**
   * Blocking version of {@link #chmodRecursive(String, String, String, Handler)}
   */
  @Fluent
  FileSystem chmodRecursiveBlocking(String path, String perms, String dirPerms) ;


  
Change the ownership on the file represented by path to user and {code group}, asynchronously. 
Params:
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
handler –  the handler that will be called on completion
Returns:
a reference to this, so the API can be used fluently/**
   * Change the ownership on the file represented by {@code path} to {@code user} and {code group}, asynchronously.
   *
   * @param path  the path to the file
   * @param user  the user name, {@code null} will not change the user name
   * @param group  the user group, {@code null} will not change the user group name
   * @param handler  the handler that will be called on completion
   * @return a reference to this, so the API can be used fluently
   */
  @Fluent
  FileSystem chown(String path, @Nullable String user, @Nullable String group, Handler<AsyncResult<Void>> handler);

  
Blocking version of chown(String, String, String, Handler<AsyncResult<Void>>) /**
   * Blocking version of {@link #chown(String, String, String, Handler)}
   *
   */
  @Fluent
  FileSystem chownBlocking(String path, @Nullable String user, @Nullable String group) ;

  
Obtain properties for the file represented by path, asynchronously. 

If the file is a link, the link will be followed.
Params:
path –  the path to the file
handler –  the handler that will be called on completion
Returns:
a reference to this, so the API can be used fluently/**
   * Obtain properties for the file represented by {@code path}, asynchronously.
   * <p>
   * If the file is a link, the link will be followed.
   *
   * @param path  the path to the file
   * @param handler  the handler that will be called on completion
   * @return a reference to this, so the API can be used fluently
   */
  @Fluent
  FileSystem props(String path, Handler<AsyncResult<FileProps>> handler);

  
Blocking version of props(String, Handler<AsyncResult<FileProps>>) /**
   * Blocking version of {@link #props(String, Handler)}
   */
  FileProps propsBlocking(String path) ;

  
Obtain properties for the link represented by path, asynchronously. 

The link will not be followed.
Params:
path –  the path to the file
handler –  the handler that will be called on completion
Returns:
a reference to this, so the API can be used fluently/**
   * Obtain properties for the link represented by {@code path}, asynchronously.
   * <p>
   * The link will not be followed.
   *
   * @param path  the path to the file
   * @param handler  the handler that will be called on completion
   * @return a reference to this, so the API can be used fluently
   */
  @Fluent
  FileSystem lprops(String path, Handler<AsyncResult<FileProps>> handler);

  
Blocking version of lprops(String, Handler<AsyncResult<FileProps>>) /**
   * Blocking version of {@link #lprops(String, Handler)}
   */
  FileProps lpropsBlocking(String path) ;

  
Create a hard link on the file system from link to existing, asynchronously. 
Params:
link –  the link
existing –  the link destination
handler –  the handler that will be called on completion
Returns:
a reference to this, so the API can be used fluently/**
   * Create a hard link on the file system from {@code link} to {@code existing}, asynchronously.
   *
   * @param link  the link
   * @param existing  the link destination
   * @param handler  the handler that will be called on completion
   * @return a reference to this, so the API can be used fluently
   */
  @Fluent
  FileSystem link(String link, String existing, Handler<AsyncResult<Void>> handler);

  
Blocking version of link(String, String, Handler<AsyncResult<Void>>) /**
   * Blocking version of {@link #link(String, String, Handler)}
   */
  @Fluent
  FileSystem linkBlocking(String link, String existing) ;

  
Create a symbolic link on the file system from link to existing, asynchronously. 
Params:
link –  the link
existing –  the link destination
handler –  the handler that will be called on completion
Returns:
a reference to this, so the API can be used fluently/**
   * Create a symbolic link on the file system from {@code link} to {@code existing}, asynchronously.
   *
   * @param link  the link
   * @param existing  the link destination
   * @param handler  the handler that will be called on completion
   * @return a reference to this, so the API can be used fluently
   */
  @Fluent
  FileSystem symlink(String link, String existing, Handler<AsyncResult<Void>> handler);

  
Blocking version of link(String, String, Handler<AsyncResult<Void>>) /**
   * Blocking version of {@link #link(String, String, Handler)}
   */
  @Fluent
  FileSystem symlinkBlocking(String link, String existing) ;

  
Unlinks the link on the file system represented by the path link, asynchronously. 
Params:
link –  the link
handler –  the handler that will be called on completion
Returns:
a reference to this, so the API can be used fluently/**
   * Unlinks the link on the file system represented by the path {@code link}, asynchronously.
   *
   * @param link  the link
   * @param handler  the handler that will be called on completion
   * @return a reference to this, so the API can be used fluently
   */
  @Fluent
  FileSystem unlink(String link, Handler<AsyncResult<Void>> handler);

  
Blocking version of unlink(String, Handler<AsyncResult<Void>>) /**
   * Blocking version of {@link #unlink(String, Handler)}
   */
  @Fluent
  FileSystem unlinkBlocking(String link) ;

  
Returns the path representing the file that the symbolic link specified by link points to, asynchronously. 
Params:
link –  the link
handler –  the handler that will be called on completion
Returns:
a reference to this, so the API can be used fluently/**
   * Returns the path representing the file that the symbolic link specified by {@code link} points to, asynchronously.
   *
   * @param link  the link
   * @param handler  the handler that will be called on completion
   * @return a reference to this, so the API can be used fluently
   */
  @Fluent
  FileSystem readSymlink(String link, Handler<AsyncResult<String>> handler);

  
Blocking version of readSymlink(String, Handler<AsyncResult<String>>) /**
   * Blocking version of {@link #readSymlink(String, Handler)}
   */
  String readSymlinkBlocking(String link) ;

  
Deletes the file represented by the specified path, asynchronously. 
Params:
path –  path to the file
handler –  the handler that will be called on completion
Returns:
a reference to this, so the API can be used fluently/**
   * Deletes the file represented by the specified {@code path}, asynchronously.
   *
   * @param path  path to the file
   * @param handler  the handler that will be called on completion
   * @return a reference to this, so the API can be used fluently
   */
  @Fluent
  FileSystem delete(String path, Handler<AsyncResult<Void>> handler);

  
Blocking version of delete(String, Handler<AsyncResult<Void>>) /**
   * Blocking version of {@link #delete(String, Handler)}
   */
  @Fluent
  FileSystem deleteBlocking(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. 
Params:
path –  path to the file
recursive –  delete recursively?
handler –  the handler that will be called on completion
Returns:
a reference to this, so the API can be used fluently/**
   * Deletes the file represented by the specified {@code path}, asynchronously.
   * <p>
   * If the path represents a directory and {@code recursive = true} then the directory and its contents will be
   * deleted recursively.
   *
   * @param path  path to the file
   * @param recursive  delete recursively?
   * @param handler  the handler that will be called on completion
   * @return a reference to this, so the API can be used fluently
   */
  @Fluent
  FileSystem deleteRecursive(String path, boolean recursive, Handler<AsyncResult<Void>> handler);

  
Blocking version of deleteRecursive(String, boolean, Handler<AsyncResult<Void>>) /**
   * Blocking version of {@link #deleteRecursive(String, boolean, Handler)}
   */
  @Fluent
  FileSystem deleteRecursiveBlocking(String path, boolean recursive) ;

  
Create the directory represented by path, asynchronously. 

The operation will fail if the directory already exists.
Params:
path –  path to the file
handler –  the handler that will be called on completion
Returns:
a reference to this, so the API can be used fluently/**
   * Create the directory represented by {@code path}, asynchronously.
   * <p>
   * The operation will fail if the directory already exists.
   *
   * @param path  path to the file
   * @param handler  the handler that will be called on completion
   * @return a reference to this, so the API can be used fluently
   */
  @Fluent
  FileSystem mkdir(String path, Handler<AsyncResult<Void>> handler);

  
Blocking version of mkdir(String, Handler<AsyncResult<Void>>) /**
   * Blocking version of {@link #mkdir(String, Handler)}
   */
  @Fluent
  FileSystem mkdirBlocking(String path) ;

  
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.
Params:
path –  path to the file
perms –  the permissions string
handler –  the handler that will be called on completion
Returns:
a reference to this, so the API can be used fluently/**
   * Create the directory represented by {@code path}, asynchronously.
   * <p>
   * The new directory will be created with permissions as specified by {@code perms}.
   * <p>
   * The permission String takes the form rwxr-x--- as specified
   * in <a href="http://download.oracle.com/javase/7/docs/api/java/nio/file/attribute/PosixFilePermissions.html">here</a>.
   * <p>
   * The operation will fail if the directory already exists.
   *
   * @param path  path to the file
   * @param perms  the permissions string
   * @param handler  the handler that will be called on completion
   * @return a reference to this, so the API can be used fluently
   */
  @Fluent
  FileSystem mkdir(String path, String perms, Handler<AsyncResult<Void>> handler);

  
Blocking version of mkdir(String, String, Handler<AsyncResult<Void>>) /**
   * Blocking version of {@link #mkdir(String, String, Handler)}
   */
  @Fluent
  FileSystem mkdirBlocking(String path, String perms) ;

  
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. 
Params:
path –  path to the file
handler –  the handler that will be called on completion
Returns:
a reference to this, so the API can be used fluently/**
   * Create the directory represented by {@code path} and any non existent parents, asynchronously.
   * <p>
   * The operation will fail if the {@code path} already exists but is not a directory.
   *
   * @param path  path to the file
   * @param handler  the handler that will be called on completion
   * @return a reference to this, so the API can be used fluently
   */
  @Fluent
  FileSystem mkdirs(String path, Handler<AsyncResult<Void>> handler);

  
Blocking version of mkdirs(String, Handler<AsyncResult<Void>>) /**
   * Blocking version of {@link #mkdirs(String, Handler)}
   */
  @Fluent
  FileSystem mkdirsBlocking(String path) ;

  
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. 
Params:
path –  path to the file
perms –  the permissions string
handler –  the handler that will be called on completion
Returns:
a reference to this, so the API can be used fluently/**
   * Create the directory represented by {@code path} and any non existent parents, asynchronously.
   * <p>
   * The new directory will be created with permissions as specified by {@code perms}.
   * <p>
   * The permission String takes the form rwxr-x--- as specified
   * in <a href="http://download.oracle.com/javase/7/docs/api/java/nio/file/attribute/PosixFilePermissions.html">here</a>.
   * <p>
   * The operation will fail if the {@code path} already exists but is not a directory.
   *
   * @param path  path to the file
   * @param perms  the permissions string
   * @param handler  the handler that will be called on completion
   * @return a reference to this, so the API can be used fluently
   */
  @Fluent
  FileSystem mkdirs(String path, String perms, Handler<AsyncResult<Void>> handler);

  
Blocking version of mkdirs(String, String, Handler<AsyncResult<Void>>) /**
   * Blocking version of {@link #mkdirs(String, String, Handler)}
   */
  @Fluent
  FileSystem mkdirsBlocking(String path, String perms) ;

  
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.
Params:
path –  path to the file
handler –  the handler that will be called on completion
Returns:
a reference to this, so the API can be used fluently/**
   * Read the contents of the directory specified by {@code path}, asynchronously.
   * <p>
   * The result is an array of String representing the paths of the files inside the directory.
   *
   * @param path  path to the file
   * @param handler  the handler that will be called on completion
   * @return a reference to this, so the API can be used fluently
   */
  @Fluent
  FileSystem readDir(String path, Handler<AsyncResult<List<String>>> handler);

  
Blocking version of readDir(String, Handler<AsyncResult<List<String>>>) /**
   * Blocking version of {@link #readDir(String, Handler)}
   */
  List<String> readDirBlocking(String path) ;

  
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.
Params:
path –  path to the directory
filter –  the filter expression
handler –  the handler that will be called on completion
Returns:
a reference to this, so the API can be used fluently/**
   * Read the contents of the directory specified by {@code path}, asynchronously.
   * <p>
   * The parameter {@code filter} is a regular expression. If {@code filter} is specified then only the paths that
   * match  @{filter}will be returned.
   * <p>
   * The result is an array of String representing the paths of the files inside the directory.
   *
   * @param path  path to the directory
   * @param filter  the filter expression
   * @param handler  the handler that will be called on completion
   * @return a reference to this, so the API can be used fluently
   */
  @Fluent
  FileSystem readDir(String path, String filter, Handler<AsyncResult<List<String>>> handler);

  
Blocking version of readDir(String, String, Handler<AsyncResult<List<String>>>) /**
   * Blocking version of {@link #readDir(String, String, Handler)}
   */
  List<String> readDirBlocking(String path, String filter) ;

  
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.
Params:
path –  path to the file
handler –  the handler that will be called on completion
Returns:
a reference to this, so the API can be used fluently/**
   * Reads the entire file as represented by the path {@code path} as a {@link Buffer}, asynchronously.
   * <p>
   * Do not use this method to read very large files or you risk running out of available RAM.
   *
   * @param path  path to the file
   * @param handler  the handler that will be called on completion
   * @return a reference to this, so the API can be used fluently
   */
  @Fluent
  FileSystem readFile(String path, Handler<AsyncResult<Buffer>> handler);

  
Blocking version of readFile(String, Handler<AsyncResult<Buffer>>) /**
   * Blocking version of {@link #readFile(String, Handler)}
   */
  Buffer readFileBlocking(String path) ;

  
Creates the file, and writes the specified Buffer data to the file represented by the path path, asynchronously. 
Params:
path –  path to the file
handler –  the handler that will be called on completion
Returns:
a reference to this, so the API can be used fluently/**
   * Creates the file, and writes the specified {@code Buffer data} to the file represented by the path {@code path},
   * asynchronously.
   *
   * @param path  path to the file
   * @param handler  the handler that will be called on completion
   * @return a reference to this, so the API can be used fluently
   */
  @Fluent
  FileSystem writeFile(String path, Buffer data, Handler<AsyncResult<Void>> handler);

  
Blocking version of writeFile(String, Buffer, Handler<AsyncResult<Void>>) /**
   * Blocking version of {@link #writeFile(String, Buffer, Handler)}
   */
  @Fluent
  FileSystem writeFileBlocking(String path, Buffer data) ;

  
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.
Params:
path –  path to the file
options – options describing how the file should be opened
Returns:
a reference to this, so the API can be used fluently/**
   * Open the file represented by {@code path}, asynchronously.
   * <p>
   * The file is opened for both reading and writing. If the file does not already exist it will be created.
   *
   * @param path  path to the file
   * @param options options describing how the file should be opened
   * @return a reference to this, so the API can be used fluently
   *
   */
  @Fluent
  FileSystem open(String path, OpenOptions options, Handler<AsyncResult<AsyncFile>> handler);

  
Blocking version of open(String, OpenOptions, Handler<AsyncResult<AsyncFile>>) /**
   * Blocking version of {@link #open(String, io.vertx.core.file.OpenOptions, Handler)}
   */
  AsyncFile openBlocking(String path, OpenOptions options);

  
Creates an empty file with the specified path, asynchronously. 
Params:
path –  path to the file
handler –  the handler that will be called on completion
Returns:
a reference to this, so the API can be used fluently/**
   * Creates an empty file with the specified {@code path}, asynchronously.
   *
   * @param path  path to the file
   * @param handler  the handler that will be called on completion
   * @return a reference to this, so the API can be used fluently
   */
  @Fluent
  FileSystem createFile(String path, Handler<AsyncResult<Void>> handler);

  
Blocking version of createFile(String, Handler<AsyncResult<Void>>) /**
   * Blocking version of {@link #createFile(String, Handler)}
   */
  @Fluent
  FileSystem createFileBlocking(String path) ;

  
Creates an empty file with the specified path and permissions perms, asynchronously. 
Params:
path –  path to the file
perms –  the permissions string
handler –  the handler that will be called on completion
Returns:
a reference to this, so the API can be used fluently/**
   * Creates an empty file with the specified {@code path} and permissions {@code perms}, asynchronously.
   *
   * @param path  path to the file
   * @param perms  the permissions string
   * @param handler  the handler that will be called on completion
   * @return a reference to this, so the API can be used fluently
   */
  @Fluent
  FileSystem createFile(String path, String perms, Handler<AsyncResult<Void>> handler);

  
Blocking version of createFile(String, String, Handler<AsyncResult<Void>>) /**
   * Blocking version of {@link #createFile(String, String, Handler)}
   */
  @Fluent
  FileSystem createFileBlocking(String path, String perms) ;

  
Determines whether the file as specified by the path path exists, asynchronously. 
Params:
path –  path to the file
handler –  the handler that will be called on completion
Returns:
a reference to this, so the API can be used fluently/**
   * Determines whether the file as specified by the path {@code path} exists, asynchronously.
   *
   * @param path  path to the file
   * @param handler  the handler that will be called on completion
   * @return a reference to this, so the API can be used fluently
   */
  @Fluent
  FileSystem exists(String path, Handler<AsyncResult<Boolean>> handler);

  
Blocking version of exists(String, Handler<AsyncResult<Boolean>>) /**
   * Blocking version of {@link #exists(String, Handler)}
   */
  boolean existsBlocking(String path) ;

  
Returns properties of the file-system being used by the specified path, asynchronously. 
Params:
path –  path to anywhere on the filesystem
handler –  the handler that will be called on completion
Returns:
a reference to this, so the API can be used fluently/**
   * Returns properties of the file-system being used by the specified {@code path}, asynchronously.
   *
   * @param path  path to anywhere on the filesystem
   * @param handler  the handler that will be called on completion
   * @return a reference to this, so the API can be used fluently
   */
  @Fluent
  FileSystem fsProps(String path, Handler<AsyncResult<FileSystemProps>> handler);

  
Blocking version of fsProps(String, Handler<AsyncResult<FileSystemProps>>) /**
   * Blocking version of {@link #fsProps(String, Handler)}
   */
  FileSystemProps fsPropsBlocking(String path) ;

  
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. 
Params:
prefix –  the prefix string to be used in generating the directory's name; may be null
handler – the handler that will be called on completion
Returns:
a reference to this, so the API can be used fluently/**
   * Creates a new directory in the default temporary-file directory, using the given
   * prefix to generate its name, asynchronously.
   *
   * <p>
   * As with the {@code File.createTempFile} methods, this method is only
   * part of a temporary-file facility.A {@link Runtime#addShutdownHook shutdown-hook},
   * or the {@link java.io.File#deleteOnExit} mechanism may be used to delete the directory automatically.
   * </p>
   *
   * @param prefix  the prefix string to be used in generating the directory's name;
   *                may be {@code null}
   * @param handler the handler that will be called on completion
   * @return a reference to this, so the API can be used fluently
   */
  @Fluent
  FileSystem createTempDirectory(String prefix, Handler<AsyncResult<String>> handler);

  
Blocking version of createTempDirectory(String, Handler<AsyncResult<String>>) /**
   * Blocking version of {@link #createTempDirectory(String, Handler)}
   */
  String createTempDirectoryBlocking(String prefix);

  
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. 
Params:
prefix –  the prefix string to be used in generating the directory's name; may be null
perms –   the permissions string
handler – the handler that will be called on completion
Returns:
a reference to this, so the API can be used fluently/**
   * Creates a new directory in the default temporary-file directory, using the given
   * prefix to generate its name, asynchronously.
   * <p>
   * The new directory will be created with permissions as specified by {@code perms}.
   * </p>
   * The permission String takes the form rwxr-x--- as specified
   * in <a href="http://download.oracle.com/javase/7/docs/api/java/nio/file/attribute/PosixFilePermissions.html">here</a>.
   *
   * <p>
   * As with the {@code File.createTempFile} methods, this method is only
   * part of a temporary-file facility.A {@link Runtime#addShutdownHook shutdown-hook},
   * or the {@link java.io.File#deleteOnExit} mechanism may be used to delete the directory automatically.
   * </p>
   *
   * @param prefix  the prefix string to be used in generating the directory's name;
   *                may be {@code null}
   * @param perms   the permissions string
   * @param handler the handler that will be called on completion
   * @return a reference to this, so the API can be used fluently
   */
  @Fluent
  FileSystem createTempDirectory(String prefix, String perms, Handler<AsyncResult<String>> handler);

  
Blocking version of createTempDirectory(String, String, Handler<AsyncResult<String>>) /**
   * Blocking version of {@link #createTempDirectory(String, String, Handler)}
   */
  String createTempDirectoryBlocking(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. 
Params:
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
handler – the handler that will be called on completion
Returns:
a reference to this, so the API can be used fluently/**
   * Creates a new directory in the directory provided by the path {@code path}, using the given
   * prefix to generate its name, asynchronously.
   * <p>
   * The new directory will be created with permissions as specified by {@code perms}.
   * </p>
   * The permission String takes the form rwxr-x--- as specified
   * in <a href="http://download.oracle.com/javase/7/docs/api/java/nio/file/attribute/PosixFilePermissions.html">here</a>.
   *
   * <p>
   * As with the {@code File.createTempFile} methods, this method is only
   * part of a temporary-file facility.A {@link Runtime#addShutdownHook shutdown-hook},
   * or the {@link java.io.File#deleteOnExit} mechanism may be used to delete the directory automatically.
   * </p>
   *
   * @param dir     the path to directory in which to create the directory
   * @param prefix  the prefix string to be used in generating the directory's name;
   *                may be {@code null}
   * @param perms   the permissions string
   * @param handler the handler that will be called on completion
   * @return a reference to this, so the API can be used fluently
   */
  @Fluent
  FileSystem createTempDirectory(String dir, String prefix, String perms, Handler<AsyncResult<String>> handler);

  
Blocking version of createTempDirectory(String, String, String, Handler<AsyncResult<String>>) /**
   * Blocking version of {@link #createTempDirectory(String, String, String, Handler)}
   */
  String createTempDirectoryBlocking(String dir, String prefix, String perms);


  
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. 
Params:
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
handler – the handler that will be called on completion
Returns:
a reference to this, so the API can be used fluently/**
   * Creates a new file in the default temporary-file directory, using the given
   * prefix and suffix to generate its name, asynchronously.
   *
   * <p>
   * As with the {@code File.createTempFile} methods, this method is only
   * part of a temporary-file facility.A {@link Runtime#addShutdownHook shutdown-hook},
   * or the {@link java.io.File#deleteOnExit} mechanism may be used to delete the directory automatically.
   * </p>
   *
   * @param prefix  the prefix string to be used in generating the directory's name;
   *                may be {@code null}
   * @param suffix  the suffix string to be used in generating the file's name;
   *                may be {@code null}, in which case "{@code .tmp}" is used
   * @param handler the handler that will be called on completion
   * @return a reference to this, so the API can be used fluently
   */
  @Fluent
  FileSystem createTempFile(String prefix, String suffix, Handler<AsyncResult<String>> handler);

  
Blocking version of createTempFile(String, String, Handler<AsyncResult<String>>) /**
   * Blocking version of {@link #createTempFile(String, String, Handler)}
   */
  String createTempFileBlocking(String prefix, String suffix);

  
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. 
Params:
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
handler – the handler that will be called on completion
Returns:
a reference to this, so the API can be used fluently/**
   * Creates a new file in the directory provided by the path {@code dir}, using the given
   * prefix and suffix to generate its name, asynchronously.
   *
   * <p>
   * As with the {@code File.createTempFile} methods, this method is only
   * part of a temporary-file facility.A {@link Runtime#addShutdownHook shutdown-hook},
   * or the {@link java.io.File#deleteOnExit} mechanism may be used to delete the directory automatically.
   * </p>
   *
   * @param prefix  the prefix string to be used in generating the directory's name;
   *                may be {@code null}
   * @param suffix  the suffix string to be used in generating the file's name;
   *                may be {@code null}, in which case "{@code .tmp}" is used
   * @param handler the handler that will be called on completion
   * @return a reference to this, so the API can be used fluently
   */
  @Fluent
  FileSystem createTempFile(String prefix, String suffix, String perms, Handler<AsyncResult<String>> handler);

  
Blocking version of createTempFile(String, String, String, Handler<AsyncResult<String>>) /**
   * Blocking version of {@link #createTempFile(String, String, String, Handler)}
   */
  String createTempFileBlocking(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. 
Params:
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
handler – the handler that will be called on completion
Returns:
a reference to this, so the API can be used fluently/**
   * Creates a new file in the directory provided by the path {@code dir}, using the given
   * prefix and suffix to generate its name, asynchronously.
   * <p>
   * The new directory will be created with permissions as specified by {@code perms}.
   * </p>
   * The permission String takes the form rwxr-x--- as specified
   * in <a href="http://download.oracle.com/javase/7/docs/api/java/nio/file/attribute/PosixFilePermissions.html">here</a>.
   *
   * <p>
   * As with the {@code File.createTempFile} methods, this method is only
   * part of a temporary-file facility.A {@link Runtime#addShutdownHook shutdown-hook},
   * or the {@link java.io.File#deleteOnExit} mechanism may be used to delete the directory automatically.
   * </p>
   *
   * @param dir     the path to directory in which to create the directory
   * @param prefix  the prefix string to be used in generating the directory's name;
   *                may be {@code null}
   * @param suffix  the suffix string to be used in generating the file's name;
   *                may be {@code null}, in which case "{@code .tmp}" is used
   * @param perms   the permissions string
   * @param handler the handler that will be called on completion
   * @return a reference to this, so the API can be used fluently
   */
  @Fluent
  FileSystem createTempFile(String dir, String prefix, String suffix, String perms, Handler<AsyncResult<String>> handler);

  
Blocking version of createTempFile(String, String, String, String, Handler<AsyncResult<String>>) /**
   * Blocking version of {@link #createTempFile(String, String, String, String, Handler)}
   */
  String createTempFileBlocking(String dir, String prefix, String suffix, String perms);

}