io.vertx.core.file.package-info Maven / Gradle / Ivy

Go to download
/*
 * Copyright 2014 Red Hat, Inc.
 *
 *  All rights reserved. This program and the accompanying materials
 *  are made available under the terms of the Eclipse Public License v1.0
 *  and Apache License v2.0 which accompanies this distribution.
 *
 *  The Eclipse Public License is available at
 *  http://www.eclipse.org/legal/epl-v10.html
 *
 *  The Apache License v2.0 is available at
 *  http://www.opensource.org/licenses/apache2.0.php
 *
 *  You may elect to redistribute this code under either of these licenses.
 */

/**
 * == Using the file system with Vert.x
 *
 * The Vert.x {@link io.vertx.core.file.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  {@link io.vertx.core.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]
 * ----
 * {@link 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]
 * ----
 * {@link 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 {@link io.vertx.core.file.FileSystem API docs} for the full list.
 *
 * Let's see a couple of examples using asynchronous methods:
 *
 * [source,$lang]
 * ----
 * {@link 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 {@link io.vertx.core.file.AsyncFile AsyncFile} as follows:
 *
 * [source,$lang]
 * ----
 * {@link 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
 * {@link io.vertx.core.file.AsyncFile#write(io.vertx.core.buffer.Buffer, long, io.vertx.core.Handler) 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]
 * ----
 * {@link examples.FileSystemExamples#asyncFileWrite()}
 * ----
 *
 * ==== Random access reads
 *
 * To use an `AsyncFile` for random access reads you use the
 * {@link io.vertx.core.file.AsyncFile#read(io.vertx.core.buffer.Buffer, int, long, int, io.vertx.core.Handler) 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]
 * ----
 * {@link examples.FileSystemExamples#asyncFileRead()}
 * ----
 *
 * ==== Opening Options
 *
 * When opening an `AsyncFile`, you pass an {@link io.vertx.core.file.OpenOptions OpenOptions} instance.
 * These options describe the behavior of the file access. For instance, you can configure the file permissions with the
 * {@link io.vertx.core.file.OpenOptions#setRead(boolean)}, {@link io.vertx.core.file.OpenOptions#setWrite(boolean)}
 * and {@link io.vertx.core.file.OpenOptions#setPerms(java.lang.String)} methods.
 *
 * You can also configure the behavior if the open file already exists with
 * {@link io.vertx.core.file.OpenOptions#setCreateNew(boolean)} and
 * {@link io.vertx.core.file.OpenOptions#setTruncateExisting(boolean)}.
 *
 * You can also mark the file to be deleted on
 * close or when the JVM is shutdown with {@link io.vertx.core.file.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
 * {@link io.vertx.core.file.OpenOptions#setDsync(boolean)}. In that case, you can manually flush any writes from the OS
 * cache by calling the {@link io.vertx.core.file.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]
 * ----
 * {@link examples.FileSystemExamples#asyncFilePump()}
 * ----
 *
 * You can also use the _pump_ to write file content into HTTP responses, or more generally in any
 * `WriteStream`.
 * 
 * [[classpath]]
 * ==== Accessing files from the classpath
 *
 * When vert.x cannot find the file on the filesystem it tries to resolve the
 * file from the class path. Note that classpath resource paths never start with
 * a `/`. 
 * 
 * Due to the fact that Java does not offer async access to classpath
 * resources, the file is copied to the filesystem in a worker thread when the
 * classpath resource is accessed the very first time and served from there
 * asynchrously. When the same resource is accessed a second time, the file from
 * the filesystem is served directly from the filesystem. The original content
 * is served even if the classpath resource changes (e.g. in a development
 * system). 
 * 
 * This caching behaviour can be disabled by setting the system
 * property `vertx.disableFileCaching` to `true`. The path where the files are
 * cached is `.vertx` by default and can be customized by setting the system
 * property `vertx.cacheDirBase`.
 *
 * The whole classpath resolving feature can be disabled by setting the system
 * property `vertx.disableFileCPResolving` to `true`.
 *
 * NOTE: these system properties are evaluated once when the the `io.vertx.core.impl.FileResolver` class is loaded, so
 * these properties should be set before loading this class or as a JVM system property when launching it.
 *
 * ==== Closing an AsyncFile
 *
 * To close an `AsyncFile` call the {@link io.vertx.core.file.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.
 *
 */
@Document(fileName = "filesystem.adoc")
package io.vertx.core.file;

import io.vertx.docgen.Document;