Package io.vertx.core.file

== Using the file system with Vert.x The Vert.x FileSystem object provides many operations for manipulating the file system.

See: Description

Interface Summary

Interface	Description
AsyncFile	Represents a file on the file-system which can be read from, or written to asynchronously.
FileProps	Represents properties of a file on the file system.
FileSystem	Contains a broad set of operations for manipulating files on the file system.
FileSystemProps	Represents properties of the file system.

Class Summary

Class	Description
OpenOptions	Describes how an AsyncFile should be opened.

Exception Summary

Exception	Description
FileSystemException	Exception thrown by the FileSystem class

Package io.vertx.core.file Description

== Using the file system with Vert.x The Vert.x FileSystem object provides many operations for manipulating the file system. There is one file system object per Vert.x instance, and you obtain it with Vertx.fileSystem(). A blocking and a 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. Here's an example of an asynchronous copy of a file: [source,$lang] ---- examples.FileSystemExamples#example1 ---- 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 from an event loop, so as not to break the Golden Rule. Here's the copy using the blocking API: [source,$lang] ---- examples.FileSystemExamples#example2 ---- Many operations exist to copy, move, truncate, chmod and many other file operations. We won't list them all here, please consult the API docs for the full list. Let's see a couple of examples using asynchronous methods: [source,$lang] ---- examples.FileSystemExamples#asyncAPIExamples ---- === Asynchronous files Vert.x provides an asynchronous file abstraction that allows you to manipulate a file on the file system. You open an AsyncFile as follows: [source,$lang] ---- examples.FileSystemExamples#example3 ---- `AsyncFile` implements `ReadStream` and `WriteStream` so you can _pump_ files to and from other stream objects such as net sockets, http requests and responses, and WebSockets. They also allow you to read and write directly to them. ==== Random access writes To use an `AsyncFile` for random access writing you use the write method. The parameters to the method are: * `buffer`: the buffer to write. * `position`: an integer position in the file where to write the buffer. If the position is greater or equal to the size of the file, the file will be enlarged to accommodate the offset. * `handler`: the result handler Here is an example of random access writes: [source,$lang] ---- examples.FileSystemExamples#asyncFileWrite() ---- ==== Random access reads To use an `AsyncFile` for random access reads you use the read method. The parameters to the method are: * `buffer`: the buffer into which the data will be read. * `offset`: an integer offset into the buffer where the read data will be placed. * `position`: the position in the file where to read data from. * `length`: the number of bytes of data to read * `handler`: the result handler Here's an example of random access reads: [source,$lang] ---- examples.FileSystemExamples#asyncFileRead() ---- ==== Opening Options When opening an `AsyncFile`, you pass an OpenOptions instance. These options describe the behavior of the file access. For instance, you can configure the file permissions with the OpenOptions.setRead(boolean), OpenOptions.setWrite(boolean) and OpenOptions.setPerms(java.lang.String) methods. You can also configure the behavior if the open file already exists with OpenOptions.setCreateNew(boolean) and OpenOptions.setTruncateExisting(boolean). You can also mark the file to be deleted on close or when the JVM is shutdown with OpenOptions.setDeleteOnClose(boolean). ==== Flushing data to underlying storage. In the `OpenOptions`, you can enable/disable the automatic synchronisation of the content on every write using OpenOptions.setDsync(boolean). In that case, you can manually flush any writes from the OS cache by calling the AsyncFile.flush() method. This method can also be called with an handler which will be called when the flush is complete. ==== Using AsyncFile as ReadStream and WriteStream `AsyncFile` implements `ReadStream` and `WriteStream`. You can then use them with a _pump_ to pump data to and from other read and write streams. For example, this would copy the content to another `AsyncFile`: [source,$lang] ---- examples.FileSystemExamples#asyncFilePump() ---- You can also use the _pump_ to write file content into HTTP responses, or more generally in any `WriteStream`. ==== Closing an AsyncFile To close an `AsyncFile` call the AsyncFile.close() method. Closing is asynchronous and if you want to be notified when the close has been completed you can specify a handler function as an argument.