BetterJapanese/kuebiko — pull request #4 by Vorzard (2014-05-28 17:46:44+00:00)
Title: Deploy Fileresource

FileResource is a **reference** to a *non-executable data file*.

FileResource wraps methods from `Path`, `Paths` and `Files` every time it does anything substantial. FileResource is a specialized `Path` that captures common use cases (behavior) and context (state) related to handling a non-executable data file in a convenient and uniform way.

A FileResource can be created with either `FileResource.of` (references an arbitrary path) or `FileResource.locate` (locates a file).

When and only when a FileResource is constructed a set of `OpenOption` can be specified that determines how the file is opened by `newInputStream` and `newOutputStream`.
By default the file can be opened to *read* and can be opened to *write*. If it is opened to *write* and the file already exists it is *truncated* to zero length, otherwise it is *created*.

You should **never rely on the specified options as a security measure**. The client can acquire unbounded access to a referenced file in various ways, including by requesting a `Path`, `File` or `URI` representation.

The **specified path is not checked** or tested in any way to ensure that it is a regular file (not a directory or a symbolic link). That's not possible without opening or creating the file, and FileResource is merely a reference.