org.objectledge.filesystem
Class FileSystem

java.lang.Object
  org.objectledge.filesystem.FileSystem

public class FileSystem
extends Object

Provides an abstration of files available in the local file system, in the ClassLoader, web application context, or through java.net.URL mechanism.

Version:

$Id: FileSystem.java,v 1.31 2006/02/08 18:22:33 zwierzem Exp $

Author:

Rafal.Krzewski

Field Summary

private int	bufferSize The size of the buffer.
private int	maxReadSize Maximum size of a file that is loaded into memory in one chunk by the.
private String	protocol
private List<FileSystemProvider>	providers The providers.

Constructor Summary

protected	FileSystem() Protected no-arg constructor to allow mocking.
	FileSystem(FileSystemProvider[] providers, int bufferSize, int maxReadSize) Creates a new instance of the File System.

Method Summary

static String	basePath(String path) Returns the base name of a file.
boolean	canRead(String path) Returns true if the file specified by the abstract pathname can be read.
boolean	canWrite(String path) Returns true if the file specified by the abstract pathname can be written.
boolean	checkPathChars(String path) Returns true if the given path contains acceptable characters.
void	copyDir(String src, String dst) Copies the contents of a directory to another location.
void	copyFile(String from, String to) Copies a file from one location to another.
boolean	createNewFile(String path) Atomically creates a new, empty file named by this abstract pathname if and only if a file with this name does not yet exist.
void	delete(String path) Deletes a file or directory.
void	deleteRecursive(String path) Deletes recursive a directory.
static String	directoryPath(String path) Returns hte directory name of a file.
boolean	exists(String path) Returns true if the file specified by the abstract pathname exists.
static FileSystem	getClasspathFileSystem() Creates a classpath file system.
InputStream	getInputStream(String path) Returns an InputStream for reading the file.
OutputStream	getOutputStream(String path) Returns an OutputStream for writing the file.
OutputStream	getOutputStream(String path, boolean append) Returns an OutputStream for writing the file, or appending to it.
String	getProtocol() Return the URL protocol name for this FileSystem.
FileSystemProvider	getProvider(String name) Return the provider with the specified name.
FileSystemProvider[]	getProviders() Return the installed providers.
RandomAccessFile	getRandomAccess(String path, String mode) Returns a RandomAccess interface implementation for accessing the file at arbitrary positions.
Reader	getReader(String path, String encoding) Returns a Reader for reading the file.
URL	getResource(String path) Returns an URL poiting to a file.
static FileSystem	getStandardFileSystem(String root) Creates a standard file system.
Writer	getWriter(String path, String encoding) Returns a Writer for writing the file, or appendig to it.
Writer	getWriter(String path, String encoding, boolean append) Returns a Writer for writing the file, or appendig to it.
boolean	isDirectory(String path) Returns true if the abstract pathname points to a directory.
boolean	isFile(String path) Returns true if the abstract pathname points to an ordinary file.
long	lastModified(String path) Returns the time of the last modificaion of the specified file.
long	length(String path) Returns the size of the specified file.
String[]	list(String path) Lists the contents of a directory.
void	mkdirs(String path) Creates a directory and all neccessary parent directories.
static String	normalizedPath(String path) Normalizes a pathname.
byte[]	read(String path) Read the contents of a file into a byte array.
void	read(String path, OutputStream out) Read the contents of a file and write them into an OutputStream.
String	read(String path, String encoding) Read the contents of a file into a String.
static String	relativePath(String path, String base) Returns the relative pathname of a file with respect to given base directory.
void	rename(String from, String to) Atomically renames a file or directory.
void	write(String path, byte[] bytes) Write contents of a byte array into a file.
void	write(String path, InputStream in) Write the data read from an InputStream into a file.
void	write(String path, String string, String encoding) Write contents of a byte array into a file.

Methods inherited from class java.lang.Object

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

Field Detail

protocol

private String protocol

providers

private List<FileSystemProvider> providers

The providers.

bufferSize

private int bufferSize

The size of the buffer.

maxReadSize

private int maxReadSize

Maximum size of a file that is loaded into memory in one chunk by the. read() methods.

Constructor Detail

FileSystem

protected FileSystem()

Protected no-arg constructor to allow mocking.

FileSystem

public FileSystem(FileSystemProvider[] providers,
                  int bufferSize,
                  int maxReadSize)

Creates a new instance of the File System.

Parameters:

providers - the backend implementations of the service.

bufferSize - the size of the buffers using for reading/writing files.

maxReadSize - maximum size of file that is loaded into memory as a single chunk.

Method Detail

getProtocol

public String getProtocol()

Return the URL protocol name for this FileSystem.

Returns:

the protocol prefix used by the service.

getProviders

public FileSystemProvider[] getProviders()

Return the installed providers.

The provider objects are returned in the same order in which they are accessed.

Returns:

the installed providers.

getProvider

public FileSystemProvider getProvider(String name)
                               throws IllegalArgumentException

Return the provider with the specified name.

Parameters:

name - the name of the provider

Returns:

the provider.

Throws:

IllegalArgumentException - if the requested provider is not installed.

getResource

public URL getResource(String path)
                throws MalformedURLException

Returns an URL poiting to a file.

Parameters:

path - the abstract pathname

Returns:

an URL of null if the file is not found.

Throws:

MalformedURLException - if the pathname is not valid.

getInputStream

public InputStream getInputStream(String path)

Returns an InputStream for reading the file.

Parameters:

path - the abstract pathname.

Returns:

an InputStream, or null if the file is not found.

getReader

public Reader getReader(String path,
                        String encoding)
                 throws UnsupportedEncodingException

Returns a Reader for reading the file.

Parameters:

path - the abstract pathname.

encoding - character encoding to use.

Returns:

a Reader, or null if the file is not found.

Throws:

UnsupportedEncodingException - if the requested encoding is not supported.

getOutputStream

public OutputStream getOutputStream(String path,
                                    boolean append)

Returns an OutputStream for writing the file, or appending to it.

Parameters:

path - the abstract pathname.

append - false to truncate the file, true to append.

Returns:

an OutputStream, or null if the operation is not supported, or the file could not be opened for writing.

getOutputStream

public OutputStream getOutputStream(String path)

Returns an OutputStream for writing the file.

Parameters:

path - the abstract pathname.

Returns:

an OutputStream, or null if the operation is not supported, or the file could not be opened for writing.

getWriter

public Writer getWriter(String path,
                        String encoding,
                        boolean append)
                 throws UnsupportedEncodingException

Returns a Writer for writing the file, or appendig to it.

Parameters:

path - the abstract pathname.

encoding - the character encoding to use.

append - false to truncate the file, true to append.

Returns:

a Writer, or null if the operation is not supported, or the file could not be opened for writing.

Throws:

UnsupportedEncodingException - if the requested encoding is not supported.

getWriter

public Writer getWriter(String path,
                        String encoding)
                 throws UnsupportedEncodingException

Returns a Writer for writing the file, or appendig to it.

Parameters:

path - the abstract pathname.

encoding - the character encoding to use.

Returns:

a Writer, or null if the operation is not supported, or the file could not be opened for writing.

Throws:

UnsupportedEncodingException - if the requested encoding is not supported.

getRandomAccess

public RandomAccessFile getRandomAccess(String path,
                                        String mode)

Returns a RandomAccess interface implementation for accessing the file at arbitrary positions.

Parameters:

path - the abstract pathname.

mode - the string which defines the opening mode for this random access file, the form of this string is equal to the mode parameter in java.io.RandomAccessFile constructor.

Returns:

an RandomAccess interface implementation, or null if the operation is not supported.

exists

public boolean exists(String path)

Returns true if the file specified by the abstract pathname exists.

Parameters:

path - the abstract pathname

Returns:

true if the file specified by the abstract pathname exists.

isFile

public boolean isFile(String path)

Returns true if the abstract pathname points to an ordinary file.

Parameters:

path - the abstract pathname

Returns:

true if the file specified by the abstract pathname exists.

isDirectory

public boolean isDirectory(String path)

Returns true if the abstract pathname points to a directory.

Parameters:

path - the abstract pathname

Returns:

true if the file specified by the abstract pathname exists.

canRead

public boolean canRead(String path)

Returns true if the file specified by the abstract pathname can be read.

Parameters:

path - the abstract pathname

Returns:

true if the file specified by the abstract pathname can be read.

canWrite

public boolean canWrite(String path)

Returns true if the file specified by the abstract pathname can be written.

Parameters:

path - the abstract pathname

Returns:

true if the file specified by the abstract pathname can be written.

lastModified

public long lastModified(String path)

Returns the time of the last modificaion of the specified file.

The time of the modification is returned as the number of milliseconds sice the epoch (Jan 1 1970), or -1L if the feature is not supported.

Parameters:

path - the abstract pathname.

Returns:

the time of last modification of the specified file.

length

public long length(String path)

Returns the size of the specified file.

If the operation is not supported -1L is returned.

Parameters:

path - an abstract pathname.

Returns:

the lenght of the file

list

public String[] list(String path)
              throws IOException

Lists the contents of a directory.

Parameters:

path - the directory to list.

Returns:

array of names of the contents of a directory.

Throws:

IOException - if the pathname does not point to a directory.

createNewFile

public boolean createNewFile(String path)
                      throws IOException,
                             UnsupportedCharactersInFilePathException

Atomically creates a new, empty file named by this abstract pathname if and only if a file with this name does not yet exist.

The check for the existence of the file and the creation of the file if it does not exist are a single operation that is atomic with respect to all other filesystem activities that might affect the file.

Parameters:

path - the pathname of the file to create.

Returns:

true if the named file does not exist and was successfully created; false if the named file already exists.

Throws:

UnsupportedCharactersInFilePathException - if the given path contains characters incompatible with underlying filesystem.

IOException - if the operation fails.

mkdirs

public void mkdirs(String path)
            throws IOException,
                   UnsupportedCharactersInFilePathException

Creates a directory and all neccessary parent directories.

Parameters:

path - the directory name.

Throws:

UnsupportedCharactersInFilePathException - if the given path contains characters incompatible with underlying filesystem.

IOException - if the operation fails.

delete

public void delete(String path)
            throws IOException

Deletes a file or directory.

A directory must be empty at the time it is deleted.

Parameters:

path - the path of the file or directory

Throws:

IOException - if the operation fails.

deleteRecursive

public void deleteRecursive(String path)
                     throws IOException

Deletes recursive a directory.

Parameters:

path - the path of the directory.

Throws:

IOException - if the operation fails.

rename

public void rename(String from,
                   String to)
            throws IOException,
                   UnsupportedCharactersInFilePathException

Atomically renames a file or directory.

Parameters:

from - source path.

to - destination path.

Throws:

UnsupportedCharactersInFilePathException - if the given destination path contains characters incompatible with underlying filesystem.

IOException - if the operation fails.

copyFile

public void copyFile(String from,
                     String to)
              throws IOException,
                     UnsupportedCharactersInFilePathException

Copies a file from one location to another.

Parameters:

from - the source path.

to - the destination path.

Throws:

UnsupportedCharactersInFilePathException - if the given destination path contains characters incompatible with underlying filesystem.

IOException - if the operation fails.

copyDir

public void copyDir(String src,
                    String dst)
             throws IOException,
                    UnsupportedCharactersInFilePathException

Copies the contents of a directory to another location.

Parameters:

src - source directory.

dst - destination directory.

Throws:

UnsupportedCharactersInFilePathException - if the given destination path contains characters incompatible with underlying filesystem.

IOException - if the operation fails.

read

public void read(String path,
                 OutputStream out)
          throws IOException

Read the contents of a file and write them into an OutputStream.

Parameters:

path - the pathname of the file.

out - the stream to write file contents to.

Throws:

IOException - if the operation fails.

read

public byte[] read(String path)
            throws IOException

Read the contents of a file into a byte array.

Parameters:

path - the pathnamame of the file.

Returns:

the contents of the file.

Throws:

IOException - if the operation fails.

read

public String read(String path,
                   String encoding)
            throws IOException

Read the contents of a file into a String.

Parameters:

path - the pathnamame of the file.

encoding - the character encoding to use for decoding bytes into Unicode characters.

Returns:

the contents of the file.

Throws:

IOException - if the file cannot be read, or the specified encoding is not supported

write

public void write(String path,
                  InputStream in)
           throws IOException

Write the data read from an InputStream into a file.

Parameters:

path - the pathname of the file

in - the steram to read data from.

Throws:

IOException - if the opreation fails.

write

public void write(String path,
                  byte[] bytes)
           throws IOException

Write contents of a byte array into a file.

Parameters:

path - the pathname of the file.

bytes - the bytes to be written

Throws:

IOException - if the operation fails.

write

public void write(String path,
                  String string,
                  String encoding)
           throws IOException

Write contents of a byte array into a file.

Parameters:

path - the pathname of the file.

string - the String to be written

encoding - the character encoding to use for encoding Unicode characters into bytes.

Throws:

IOException - if the file cannot be written to, or the specified encoding is not supported.

normalizedPath

public static String normalizedPath(String path)
                             throws IllegalArgumentException

Normalizes a pathname.

This method removes redundant / characters, removes . and .. path elements, taking care that the paths dont reach outside filesystem root, removes trailing / from directories and adding leading / as neccessary.

Parameters:

path - the path.

Returns:

normalized path.

Throws:

IllegalArgumentException - if the path reaches outside the filesystem root.

basePath

public static String basePath(String path)

Returns the base name of a file.

This method returns the contents of the pathname after the last '/' character.

Parameters:

path - the pathname of the file.

Returns:

the basename of the file.

directoryPath

public static String directoryPath(String path)

Returns hte directory name of a file.

This method returns the normalized path before the last '/' character in the path.

Parameters:

path - the pathname of the file.

Returns:

the directory name of the file.

relativePath

public static String relativePath(String path,
                                  String base)
                           throws IllegalArgumentException

Returns the relative pathname of a file with respect to given base directory.

Parameters:

path - the pathname of a file.

base - the base pathname.

Returns:

the relative pathname.

Throws:

IllegalArgumentException - if the file is contained outside of base.

checkPathChars

public boolean checkPathChars(String path)

Returns true if the given path contains acceptable characters.

Parameters:

path - the path

Returns:

true if the given path contains acceptable characters.

getStandardFileSystem

public static FileSystem getStandardFileSystem(String root)

Creates a standard file system.

The file system is composed of a local file system, with the specified root, augmented with a classpath file system.

Parameters:

root - the local filesystem root.

Returns:

a standard file system.

getClasspathFileSystem

public static FileSystem getClasspathFileSystem()

Creates a classpath file system.

Returns:

a classpath file system.