Package de.xima.fc.common.filesystem

Interface ICommonFileSystem<FD>

Type Parameters:

FD - Type of the file descriptor, such as e.g. a string representing a file path.

All Superinterfaces:

AutoCloseable

All Known Subinterfaces:

ISynchronizedFileSystem<FD>

All Known Implementing Classes:

EntityFileSystem

public interface ICommonFileSystem<FD>
extends AutoCloseable

High-level interface for abstracting common file system operations. Implementations could use a real file system, a database or any other storage medium.

Since:

8.3.0

Author:

XIMA MEDIA GmbH

Method Summary

Modifier and Type	Method	Description
void	copy(FD source, FD target)	Copies the file with the given source key to the target key.
void	delete(FD file)	Deletes the file or directory with the given key.
boolean	exists(FD file)	Checks whether this file system contains a file (or folder) with the given key.
Instant	getFileLastModifiedAt(FD file)	Gets the last modified time of the file with the given key.
String	getFileLastModifiedBy(FD file)	Gets the user who last modified the file with the given key.
Iterable<FD>	getFiles()	Gets the keys of all existing files.
FileSize	getFileSize(FD file)	Gets the size of the file with the given key.
boolean	hasPendingChanges(FD file)	Checks whether the content of the file with the given key has been changed and is in a pending state, not yet persisted or synchronized with an external storage medium.
boolean	isOpen()	Checks whether this file system is open.
Iterable<FD>	listFolder(FD folder)	Gets the keys of all existing files within the given folder, non-recursively.
Iterable<FD>	listFolderRecursively(FD folder)	Gets the keys of all existing files within the given folder, recursively.
void	makeFile(FD file)	Creates a new file with no content.
void	makeFolder(FD fileKey)	Creates a new folder with no content.
InputStream	openFileInput(FD file)	Gets an input stream for the data of the file with the given key.
InputStream	openFileInputMarkable(FD file)	Gets an input stream for the data of the file with the given key.
OutputStream	openFileOutput(FD file)	Opens an output stream to the given file key.
void	refresh()	If the implementation employs any kind of caching: discards all caches and refreshes the file system so that all entries represent the most up-to-date state.
void	refresh(Iterable<FD> files)	If the implementation employs any kind of caching: discards all caches and refreshes the file system so that all given entries represent the most up-to-date state.
Map<FD,FD>	rename(FD source, FD target)	Renames the file system entry with the given source key to the target key.
<FileSystem> FileSystem	unwrap(Class<? extends FileSystem> type)	Unwraps this file system to the given type.

Methods inherited from interface java.lang.AutoCloseable

close

Method Detail

copy

void copy(FD source,
          FD target)
   throws IOException

Copies the file with the given source key to the target key. If the source key does not exist, this method does nothing. If the target key exists already, an IOException is thrown.

If the source is a directory, all contents of the source must also be copied to the target.

Parameters:

source - The descriptor of the file to copy.

target - The descriptor of the file to copy to.

Throws:

IOException - If an error occurs while copying the file data.

delete

void delete(FD file)
     throws IOException

Deletes the file or directory with the given key. If the file or directory does not exist, this method does nothing.

Parameters:

file - The file descriptor of the file to delete.

Throws:

IOException - If an error occurs while deleting the file.

exists

boolean exists(FD file)

Checks whether this file system contains a file (or folder) with the given key. Returns false if the file could not be checked.

Parameters:

file - The file descriptor.

Returns:

true if the file (or folder) exists, false otherwise.

getFileLastModifiedAt

Instant getFileLastModifiedAt(FD file)
                       throws IOException

Gets the last modified time of the file with the given key. If the file does not exist, or if the last modified time is not available, Instant.EPOCH is returned.

Parameters:

file - The file descriptor.

Returns:

The last modified time of the file, or Instant.EPOCH if the file does not exist.

Throws:

IOException - If an error occurs while loading the last modified time.

getFileLastModifiedBy

String getFileLastModifiedBy(FD file)
                      throws IOException

Gets the user who last modified the file with the given key. If the file does not exist, or if the last modified user is not available, the empty string is returned.

Parameters:

file - The key of the file.

Returns:

The user who last modified the file, or the empty string if the file does not exist.

Throws:

IOException - If an error occurs while loading the user who last modified the file.

getFileSize

FileSize getFileSize(FD file)
              throws IOException

Gets the size of the file with the given key. If the file does not exist, or if the size cannot be determined 0 is returned.

Parameters:

file - The file descriptor.

Returns:

The size of the file, or 0 if unavailable.

Throws:

IOException - If an error occurs while loading the file size.

getFiles

Iterable<FD> getFiles()

Gets the keys of all existing files.

Returns:

The keys of all existing files.

hasPendingChanges

boolean hasPendingChanges(FD file)

Checks whether the content of the file with the given key has been changed and is in a pending state, not yet persisted or synchronized with an external storage medium.

Parameters:

file - The file descriptor.

Returns:

true if the content has pending changes, false otherwise.

isOpen

boolean isOpen()

Checks whether this file system is open. If the file system is not open, no operations can be performed. See AutoCloseable.close().

Returns:

true if the file system is still open, false otherwise.

listFolder

Iterable<FD> listFolder(FD folder)
                 throws IOException

Gets the keys of all existing files within the given folder, non-recursively. Only the files in the given folder are returned, not files in subfolders.

The given folder is not included in the result.

Parameters:

folder - The key to start at.

Returns:

The keys of all existing files within the given folder.

Throws:

IOException - If an error occurs while listing the folder contents.

listFolderRecursively

Iterable<FD> listFolderRecursively(FD folder)
                            throws IOException

Gets the keys of all existing files within the given folder, recursively. This is a recursive operation, so all files in all subfolders are included. Folder contents are returned in breadth-first order, i.e. all files in the same folder are returned before files in subfolders.

The given folder is not included in the result.

Parameters:

folder - The file descriptor of the folder.

Returns:

The keys of all existing files within the given folder and subfolders.

Throws:

IOException - If an error occurs while listing the folder contents.

makeFile

void makeFile(FD file)
       throws IOException

Creates a new file with no content. Does nothing if the file already exists.

Parameters:

file - The file descriptor.

Throws:

IOException - If an error occurs while creating the file.

makeFolder

void makeFolder(FD fileKey)
         throws IOException

Creates a new folder with no content. Does nothing if the file already exists.

Parameters:

fileKey - The key of the folder.

Throws:

IOException - If an error occurs while creating the folder.

openFileInput

InputStream openFileInput(FD file)
                   throws IOException

Gets an input stream for the data of the file with the given key. If the file does not exist, or if the file data is not available, an empty input stream is returned.

No guarantees are made regarding the features of the input stream, other than data can be read from it.

Parameters:

file - The file descriptor.

Returns:

An input stream for the data of the file, or an empty stream if the file does not exist or the data is not available.

Throws:

IOException - If an error occurs while opening the file data from the temporary file.

openFileInputMarkable

InputStream openFileInputMarkable(FD file)
                           throws IOException

Gets an input stream for the data of the file with the given key. If the file does not exist, or if the file data is not available, an empty input stream is returned.

The returned input stream supports mark and reset operations.

Parameters:

file - The file descriptor.

Returns:

An input stream for the data of the file, or an empty stream if the file does not exist or the data is not available.

Throws:

IOException - If an error occurs while opening the file data from the temporary file.

openFileOutput

OutputStream openFileOutput(FD file)
                     throws IOException

Opens an output stream to the given file key. If the file does not exist yet, it is created. If the file exists already, the content is overwritten.

Parameters:

file - The file descriptor.

Returns:

An output stream for writing the file data.

Throws:

IOException - If an error occurs while opening the file output stream.

refresh

void refresh()
      throws IOException

If the implementation employs any kind of caching: discards all caches and refreshes the file system so that all entries represent the most up-to-date state.

Throws:

IOException - If an error occurs while refreshing the file system.

refresh

void refresh(Iterable<FD> files)
      throws IOException

If the implementation employs any kind of caching: discards all caches and refreshes the file system so that all given entries represent the most up-to-date state. If a file is given, only that file is refreshed. If a folder is given, all files and folder in that folder are refreshed (recursively).

Parameters:

files - The files to refresh.

Throws:

IOException - If an error occurs while refreshing the file system.

rename

Map<FD,FD> rename(FD source,
                        FD target)
                 throws IOException

Renames the file system entry with the given source key to the target key. If the source key does not exist, this method does nothing.

When source and target are directories, all contents of the source must also be moved to the target.

Parameters:

source - The descriptor of the file to rename.

target - The descriptor of the file towards which to rename.

Returns:

Mapping from the old to the new files or directories. Includes the contents of directories if the source is a directory.

Throws:

IllegalArgumentException - If the target key exists already.

IOException - If an error occurs while renaming the file.

unwrap

<FileSystem> FileSystem unwrap(Class<? extends FileSystem> type)

Unwraps this file system to the given type. If this file system is an instance of the given type, it is returned. Otherwise, potential wrappers are unwrapped until the given type is reached. If the file system cannot be unwrapped to the given type, null is returned.

If multiple wrappers are present, the first one that can be unwrapped to the given type is returned.

Type Parameters:

FileSystem - The type of the desired file system.

Parameters:

type - The type to unwrap to.

Returns:

The unwrapped file system, or null if the file system cannot be unwrapped to the given type.