org.joe_e.file
Class Filesystem

java.lang.Object
  org.joe_e.file.Filesystem

public final class Filesystem
extends Object

File construction. This provides a capability-safe API for access to files. A File object grants read and write access to a file or directory. Due to limitations in Java, all file references are to textual file names, not file descriptors. Multiple operations on a File may thus apply to different incarnations of the file. For this reason, File objects are not immune from time-of-check-to-time-of-use vulnerabilities (race conditions).

Method Summary

static void	checkName(String name) Vets a filename.
static File	file(File folder, String child) Produce a File capability for a file contained in a folder.
static long	length(File file) Gets the length of a file
static ConstArray<File>	list(File dir) List the contents of a directory.
static InputStream	read(File file) Opens an existing file for reading.
static OutputStream	writeNew(File file) Creates a file for writing, if and only if the file does not already exist, and returns an OutputStream for writing to that file.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

file

public static File file(File folder,
                        String child)
                 throws InvalidFilenameException

Produce a File capability for a file contained in a folder. The returned object is just a handle; the underlying file may not yet exist.

Parameters:

folder - containing folder

child - a single filename component, not a relative path

Returns:

a capability for the requested file

Throws:

IllegalArgumentException - if folder is null or the empty path

InvalidFilenameException

checkName

public static void checkName(String name)
                      throws InvalidFilenameException

Vets a filename. Checks that the argument would be interpreted as a file name rather than as a path or relative directory specifier

Parameters:

name - a single filename component, not a relative path

Throws:

InvalidFilenameException - name is rejected

list

public static ConstArray<File> list(File dir)
                             throws IOException

List the contents of a directory.

Parameters:

dir - directory to list

Returns:

directory entries, sorted alphabetically

Throws:

IOException - dir is not a directory, or an I/O error

length

public static long length(File file)
                   throws FileNotFoundException

Gets the length of a file

Parameters:

file - file to stat

Returns:

the length of the file in bytes

Throws:

FileNotFoundException - file not found

read

public static InputStream read(File file)
                        throws FileNotFoundException

Opens an existing file for reading.

Parameters:

file - file to open

Returns:

opened input stream

Throws:

FileNotFoundException - file not found

writeNew

public static OutputStream writeNew(File file)
                             throws IOException

Creates a file for writing, if and only if the file does not already exist, and returns an OutputStream for writing to that file. Warning: This method is not atomic with respect to other concurrent modifications to the filesystem.

Parameters:

file - file to create

Returns:

opened output stream

Throws:

IOException - file could not be created