com.github.fge.filesystem.provider

Class FileSystemProviderBase

java.lang.Object

java.nio.file.spi.FileSystemProvider

com.github.fge.filesystem.provider.FileSystemProviderBase

@ParametersAreNonnullByDefault
public abstract class FileSystemProviderBase
extends FileSystemProvider

Base FileSystemProvider implementation

Important note: in order to match the behaviour of the default filesystems, you should be aware of the following:

• The copy operation will not perform recursive copies; if the source is a non empty directory, the operation fails with DirectoryNotEmptyException. This class enforces this behaviour if the source and target paths are not on the same filesystem; if they are, this is then delegated to your own copy implementation.
• if the target path of a move operation exists and is a non empty directory, and you selected to replace the existing target path, the operation fails with DirectoryNotEmptyException; if the source and target paths are not on the same filesystem, this behaviour is enforced by this class; if they are on the same filesystem, this is delegated to your own move implementation.
• The deletion operation (delete(Path) and FileSystemProvider.deleteIfExists(Path) do not perform recursive deletions; if the target is a non empty directory, this method throws DirectoryNotEmptyException.

Field Summary

Fields

Modifier and Type	Field and Description
protected FileSystemRepository	repository

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	FileSystemProviderBase(FileSystemRepository repository)

Method Summary

Methods

Modifier and Type	Method and Description
void	checkAccess(Path path, AccessMode... modes) Checks the existence, and optionally the accessibility, of a file.
void	copy(Path source, Path target, CopyOption... options) Copy a file to a target file.
protected OpenOption[]	copyToOpenOptions(CopyOption... copyOptions) Convert a set of copy options to a set of open options
void	createDirectory(Path dir, FileAttribute<?>... attrs) Creates a new directory.
void	delete(Path path) Deletes a file.
<V extends FileAttributeView> V	getFileAttributeView(Path path, Class<V> type, LinkOption... options) Returns a file attribute view of a given type.
FileStore	getFileStore(Path path) Returns the FileStore representing the file store where a file is located.
FileSystem	getFileSystem(URI uri) Returns an existing FileSystem created by this provider.
Path	getPath(URI uri) Return a Path object by converting the given URI.
String	getScheme() Returns the URI scheme that identifies this provider.
boolean	isHidden(Path path) Tells whether or not a file is considered hidden.
boolean	isSameFile(Path path, Path path2) Tests if two paths locate the same file.
void	move(Path source, Path target, CopyOption... options) Move or rename a file to a target file.
SeekableByteChannel	newByteChannel(Path path, Set<? extends OpenOption> options, FileAttribute<?>... attrs) Opens or creates a file, returning a seekable byte channel to access the file.
DirectoryStream<Path>	newDirectoryStream(Path dir, DirectoryStream.Filter<? super Path> filter) Opens a directory, returning a DirectoryStream to iterate over the entries in the directory.
FileSystem	newFileSystem(URI uri, Map<String,?> env) Constructs a new FileSystem object identified by a URI.
InputStream	newInputStream(Path path, OpenOption... options) Opens a file, returning an input stream to read from the file.
OutputStream	newOutputStream(Path path, OpenOption... options) Opens or creates a file, returning an output stream that may be used to write bytes to the file.
<A extends BasicFileAttributes> A	readAttributes(Path path, Class<A> type, LinkOption... options) Reads a file's attributes as a bulk operation.
Map<String,Object>	readAttributes(Path path, String attributes, LinkOption... options) Reads a set of file attributes as a bulk operation.
void	setAttribute(Path path, String attribute, Object value, LinkOption... options) Sets the value of a file attribute.

Methods inherited from class java.nio.file.spi.FileSystemProvider

createLink, createSymbolicLink, deleteIfExists, installedProviders, newAsynchronousFileChannel, newFileChannel, newFileSystem, readSymbolicLink

Methods inherited from class java.lang.Object

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

Field Detail

repository

protected final FileSystemRepository repository

Constructor Detail

FileSystemProviderBase

protected FileSystemProviderBase(FileSystemRepository repository)

Method Detail

getScheme

public final String getScheme()

Returns the URI scheme that identifies this provider.

Specified by:

getScheme in class FileSystemProvider

Returns:

The URI scheme

newFileSystem

public final FileSystem newFileSystem(URI uri,
                       Map<String,?> env)
                               throws IOException

Constructs a new FileSystem object identified by a URI. This method is invoked by the FileSystems.newFileSystem(URI, Map) method to open a new file system identified by a URI.

The uri parameter is an absolute, hierarchical URI, with a scheme equal (without regard to case) to the scheme supported by this provider. The exact form of the URI is highly provider dependent. The env parameter is a map of provider specific properties to configure the file system.

This method throws FileSystemAlreadyExistsException if the file system already exists because it was previously created by an invocation of this method. Once a file system is closed it is provider-dependent if the provider allows a new file system to be created with the same URI as a file system it previously created.

Specified by:

newFileSystem in class FileSystemProvider

Parameters:

uri - URI reference

env - A map of provider specific properties to configure the file system; may be empty

Returns:

A new file system

Throws:

IllegalArgumentException - If the pre-conditions for the uri parameter aren't met, or the env parameter does not contain properties required by the provider, or a property value is invalid

IOException - An I/O error occurs creating the file system

SecurityException - If a security manager is installed and it denies an unspecified permission required by the file system provider implementation

FileSystemAlreadyExistsException - If the file system has already been created

getFileSystem

public final FileSystem getFileSystem(URI uri)

Returns an existing FileSystem created by this provider.

This method returns a reference to a FileSystem that was created by invoking the newFileSystem (URI,Map) method. File systems created the newFileSystem(Path,Map) method are not returned by this method. The file system is identified by its URI. Its exact form is highly provider dependent. In the case of the default provider the URI's path component is "/" and the authority, query and fragment components are undefined (Undefined components are represented by null).

Once a file system created by this provider is closed it is provider-dependent if this method returns a reference to the closed file system or throws FileSystemNotFoundException. If the provider allows a new file system to be created with the same URI as a file system it previously created then this method throws the exception if invoked after the file system is closed (and before a new instance is created by the newFileSystem method).

If a security manager is installed then a provider implementation may require to check a permission before returning a reference to an existing file system. In the case of the default file system, no permission check is required.

Specified by:

getFileSystem in class FileSystemProvider

Parameters:

uri - URI reference

Returns:

The file system

Throws:

IllegalArgumentException - If the pre-conditions for the uri parameter aren't met

FileSystemNotFoundException - If the file system does not exist

SecurityException - If a security manager is installed and it denies an unspecified permission.

getPath

public final Path getPath(URI uri)

Return a Path object by converting the given URI. The resulting Path is associated with a FileSystem that already exists or is constructed automatically.

The exact form of the URI is file system provider dependent. In the case of the default provider, the URI scheme is "file" and the given URI has a non-empty path component, and undefined query, and fragment components. The resulting Path is associated with the default default FileSystem.

If a security manager is installed then a provider implementation may require to check a permission. In the case of the default file system, no permission check is required.

Specified by:

getPath in class FileSystemProvider

Parameters:

uri - The URI to convert

Throws:

IllegalArgumentException - If the URI scheme does not identify this provider or other preconditions on the uri parameter do not hold

FileSystemNotFoundException - The file system, identified by the URI, does not exist and cannot be created automatically

SecurityException - If a security manager is installed and it denies an unspecified permission.

newInputStream

public final InputStream newInputStream(Path path,
                         OpenOption... options)
                                 throws IOException

Opens a file, returning an input stream to read from the file. This method works in exactly the manner specified by the Files.newInputStream(java.nio.file.Path, java.nio.file.OpenOption...) method.

The default implementation of this method opens a channel to the file as if by invoking the newByteChannel(java.nio.file.Path, java.util.Set<? extends java.nio.file.OpenOption>, java.nio.file.attribute.FileAttribute<?>...) method and constructs a stream that reads bytes from the channel. This method should be overridden where appropriate.

Overrides:

newInputStream in class FileSystemProvider

Parameters:

path - the path to the file to open

options - options specifying how the file is opened

Returns:

a new input stream

Throws:

IllegalArgumentException - if an invalid combination of options is specified

UnsupportedOperationException - if an unsupported option is specified

IOException - if an I/O error occurs

SecurityException - In the case of the default provider, and a security manager is installed, the checkRead method is invoked to check read access to the file.

newOutputStream

public final OutputStream newOutputStream(Path path,
                           OpenOption... options)
                                   throws IOException

Opens or creates a file, returning an output stream that may be used to write bytes to the file. This method works in exactly the manner specified by the Files.newOutputStream(java.nio.file.Path, java.nio.file.OpenOption...) method.

The default implementation of this method opens a channel to the file as if by invoking the newByteChannel(java.nio.file.Path, java.util.Set<? extends java.nio.file.OpenOption>, java.nio.file.attribute.FileAttribute<?>...) method and constructs a stream that writes bytes to the channel. This method should be overridden where appropriate.

Overrides:

newOutputStream in class FileSystemProvider

Parameters:

path - the path to the file to open or create

options - options specifying how the file is opened

Returns:

a new output stream

Throws:

IllegalArgumentException - if options contains an invalid combination of options

UnsupportedOperationException - if an unsupported option is specified

IOException - if an I/O error occurs

SecurityException - In the case of the default provider, and a security manager is installed, the checkWrite method is invoked to check write access to the file. The checkDelete method is invoked to check delete access if the file is opened with the DELETE_ON_CLOSE option.

newByteChannel

public final SeekableByteChannel newByteChannel(Path path,
                                 Set<? extends OpenOption> options,
                                 FileAttribute<?>... attrs)
                                         throws IOException

Opens or creates a file, returning a seekable byte channel to access the file. This method works in exactly the manner specified by the Files.newByteChannel(Path, Set, FileAttribute[]) method.

Specified by:

newByteChannel in class FileSystemProvider

Parameters:

path - the path to the file to open or create

options - options specifying how the file is opened

attrs - an optional list of file attributes to set atomically when creating the file

Returns:

a new seekable byte channel

Throws:

IllegalArgumentException - if the set contains an invalid combination of options

UnsupportedOperationException - if an unsupported open option is specified or the array contains attributes that cannot be set atomically when creating the file

FileAlreadyExistsException - if a file of that name already exists and the CREATE_NEW option is specified (optional specific exception)

IOException - if an I/O error occurs

SecurityException - In the case of the default provider, and a security manager is installed, the checkRead method is invoked to check read access to the path if the file is opened for reading. The checkWrite method is invoked to check write access to the path if the file is opened for writing. The checkDelete method is invoked to check delete access if the file is opened with the DELETE_ON_CLOSE option.

newDirectoryStream

public final DirectoryStream<Path> newDirectoryStream(Path dir,
                                       DirectoryStream.Filter<? super Path> filter)
                                               throws IOException

Opens a directory, returning a DirectoryStream to iterate over the entries in the directory. This method works in exactly the manner specified by the Files.newDirectoryStream(Path, DirectoryStream.Filter) method.

Specified by:

newDirectoryStream in class FileSystemProvider

Parameters:

dir - the path to the directory

filter - the directory stream filter

Returns:

a new and open DirectoryStream object

Throws:

NotDirectoryException - if the file could not otherwise be opened because it is not a directory (optional specific exception)

IOException - if an I/O error occurs

SecurityException - In the case of the default provider, and a security manager is installed, the checkRead method is invoked to check read access to the directory.

createDirectory

public final void createDirectory(Path dir,
                   FileAttribute<?>... attrs)
                           throws IOException

Creates a new directory. This method works in exactly the manner specified by the Files.createDirectory(java.nio.file.Path, java.nio.file.attribute.FileAttribute<?>...) method.

Specified by:

createDirectory in class FileSystemProvider

Parameters:

dir - the directory to create

attrs - an optional list of file attributes to set atomically when creating the directory

Throws:

UnsupportedOperationException - if the array contains an attribute that cannot be set atomically when creating the directory

FileAlreadyExistsException - if a directory could not otherwise be created because a file of that name already exists (optional specific exception)

IOException - if an I/O error occurs or the parent directory does not exist

SecurityException - In the case of the default provider, and a security manager is installed, the checkWrite method is invoked to check write access to the new directory.

delete

public final void delete(Path path)
                  throws IOException

Deletes a file. This method works in exactly the manner specified by the Files.delete(java.nio.file.Path) method.

Specified by:

delete in class FileSystemProvider

Parameters:

path - the path to the file to delete

Throws:

NoSuchFileException - if the file does not exist (optional specific exception)

DirectoryNotEmptyException - if the file is a directory and could not otherwise be deleted because the directory is not empty (optional specific exception)

IOException - if an I/O error occurs

SecurityException - In the case of the default provider, and a security manager is installed, the SecurityManager.checkDelete(String) method is invoked to check delete access to the file

copy

public final void copy(Path source,
        Path target,
        CopyOption... options)
                throws IOException

Copy a file to a target file. This method works in exactly the manner specified by the Files.copy(Path, Path, CopyOption[]) method except that both the source and target paths must be associated with this provider.

Specified by:

copy in class FileSystemProvider

Parameters:

source - the path to the file to copy

target - the path to the target file

options - options specifying how the copy should be done

Throws:

UnsupportedOperationException - if the array contains a copy option that is not supported

FileAlreadyExistsException - if the target file exists but cannot be replaced because the REPLACE_EXISTING option is not specified (optional specific exception)

DirectoryNotEmptyException - the REPLACE_EXISTING option is specified but the file cannot be replaced because it is a non-empty directory (optional specific exception)

IOException - if an I/O error occurs

SecurityException - In the case of the default provider, and a security manager is installed, the checkRead method is invoked to check read access to the source file, the checkWrite is invoked to check write access to the target file. If a symbolic link is copied the security manager is invoked to check LinkPermission("symbolic").

move

public final void move(Path source,
        Path target,
        CopyOption... options)
                throws IOException

Move or rename a file to a target file. This method works in exactly the manner specified by the Files.move(java.nio.file.Path, java.nio.file.Path, java.nio.file.CopyOption...) method except that both the source and target paths must be associated with this provider.

Specified by:

move in class FileSystemProvider

Parameters:

source - the path to the file to move

target - the path to the target file

options - options specifying how the move should be done

Throws:

UnsupportedOperationException - if the array contains a copy option that is not supported

FileAlreadyExistsException - if the target file exists but cannot be replaced because the REPLACE_EXISTING option is not specified (optional specific exception)

DirectoryNotEmptyException - the REPLACE_EXISTING option is specified but the file cannot be replaced because it is a non-empty directory (optional specific exception)

AtomicMoveNotSupportedException - if the options array contains the ATOMIC_MOVE option but the file cannot be moved as an atomic file system operation.

IOException - if an I/O error occurs

SecurityException - In the case of the default provider, and a security manager is installed, the checkWrite method is invoked to check write access to both the source and target file.

isSameFile

public final boolean isSameFile(Path path,
                 Path path2)
                         throws IOException

Tests if two paths locate the same file. This method works in exactly the manner specified by the Files.isSameFile(java.nio.file.Path, java.nio.file.Path) method.

Specified by:

isSameFile in class FileSystemProvider

Parameters:

path - one path to the file

path2 - the other path

Returns:

true if, and only if, the two paths locate the same file

Throws:

IOException - if an I/O error occurs

SecurityException - In the case of the default provider, and a security manager is installed, the checkRead method is invoked to check read access to both files.

isHidden

public final boolean isHidden(Path path)
                       throws IOException

Tells whether or not a file is considered hidden. This method works in exactly the manner specified by the Files.isHidden(java.nio.file.Path) method.

This method is invoked by the isHidden method.

Specified by:

isHidden in class FileSystemProvider

Parameters:

path - the path to the file to test

Returns:

true if the file is considered hidden

Throws:

IOException - if an I/O error occurs

SecurityException - In the case of the default provider, and a security manager is installed, the checkRead method is invoked to check read access to the file.

checkAccess

public final void checkAccess(Path path,
               AccessMode... modes)
                       throws IOException

Checks the existence, and optionally the accessibility, of a file.

This method may be used by the isReadable, isWritable and isExecutable methods to check the accessibility of a file.

This method checks the existence of a file and that this Java virtual machine has appropriate privileges that would allow it access the file according to all of access modes specified in the modes parameter as follows:

Value	Description
READ	Checks that the file exists and that the Java virtual machine has permission to read the file.
WRITE	Checks that the file exists and that the Java virtual machine has permission to write to the file,
EXECUTE	Checks that the file exists and that the Java virtual machine has permission to execute the file. The semantics may differ when checking access to a directory. For example, on UNIX systems, checking for EXECUTE access checks that the Java virtual machine has permission to search the directory in order to access file or subdirectories.

If the modes parameter is of length zero, then the existence of the file is checked.

This method follows symbolic links if the file referenced by this object is a symbolic link. Depending on the implementation, this method may require to read file permissions, access control lists, or other file attributes in order to check the effective access to the file. To determine the effective access to a file may require access to several attributes and so in some implementations this method may not be atomic with respect to other file system operations.

Specified by:

checkAccess in class FileSystemProvider

Parameters:

path - the path to the file to check

modes - The access modes to check; may have zero elements

Throws:

UnsupportedOperationException - an implementation is required to support checking for READ, WRITE, and EXECUTE access. This exception is specified to allow for the Access enum to be extended in future releases.

NoSuchFileException - if a file does not exist (optional specific exception)

AccessDeniedException - the requested access would be denied or the access cannot be determined because the Java virtual machine has insufficient privileges or other reasons. (optional specific exception)

IOException - if an I/O error occurs

SecurityException - In the case of the default provider, and a security manager is installed, the checkRead is invoked when checking read access to the file or only the existence of the file, the checkWrite is invoked when checking write access to the file, and checkExec is invoked when checking execute access.

getFileAttributeView

public final <V extends FileAttributeView> V getFileAttributeView(Path path,
                                                   Class<V> type,
                                                   LinkOption... options)

Returns a file attribute view of a given type. This method works in exactly the manner specified by the Files.getFileAttributeView(java.nio.file.Path, java.lang.Class<V>, java.nio.file.LinkOption...) method.

Specified by:

getFileAttributeView in class FileSystemProvider

Parameters:

path - the path to the file

type - the Class object corresponding to the file attribute view

options - options indicating how symbolic links are handled

Returns:

a file attribute view of the specified type, or null if the attribute view type is not available

readAttributes

public final <A extends BasicFileAttributes> A readAttributes(Path path,
                                               Class<A> type,
                                               LinkOption... options)
                                                   throws IOException

Reads a file's attributes as a bulk operation. This method works in exactly the manner specified by the Files.readAttributes(Path, Class, LinkOption[]) method.

Specified by:

readAttributes in class FileSystemProvider

Parameters:

path - the path to the file

type - the Class of the file attributes required to read

options - options indicating how symbolic links are handled

Returns:

the file attributes

Throws:

UnsupportedOperationException - if an attributes of the given type are not supported

IOException - if an I/O error occurs

SecurityException - In the case of the default provider, a security manager is installed, its checkRead method is invoked to check read access to the file

readAttributes

public final Map<String,Object> readAttributes(Path path,
                                String attributes,
                                LinkOption... options)
                                        throws IOException

Reads a set of file attributes as a bulk operation. This method works in exactly the manner specified by the Files.readAttributes(Path, String, LinkOption[]) method.

Specified by:

readAttributes in class FileSystemProvider

Parameters:

path - the path to the file

attributes - the attributes to read

options - options indicating how symbolic links are handled

Returns:

a map of the attributes returned; may be empty. The map's keys are the attribute names, its values are the attribute values

Throws:

UnsupportedOperationException - if the attribute view is not available

IllegalArgumentException - if no attributes are specified or an unrecognized attributes is specified

IOException - If an I/O error occurs

SecurityException - In the case of the default provider, and a security manager is installed, its checkRead method denies read access to the file. If this method is invoked to read security sensitive attributes then the security manager may be invoke to check for additional permissions.

setAttribute

public final void setAttribute(Path path,
                String attribute,
                Object value,
                LinkOption... options)
                        throws IOException

Sets the value of a file attribute. This method works in exactly the manner specified by the Files.setAttribute(java.nio.file.Path, java.lang.String, java.lang.Object, java.nio.file.LinkOption...) method.

Specified by:

setAttribute in class FileSystemProvider

Parameters:

path - the path to the file

attribute - the attribute to set

value - the attribute value

options - options indicating how symbolic links are handled

Throws:

UnsupportedOperationException - if the attribute view is not available

IllegalArgumentException - if the attribute name is not specified, or is not recognized, or the attribute value is of the correct type but has an inappropriate value

ClassCastException - If the attribute value is not of the expected type or is a collection containing elements that are not of the expected type

IOException - If an I/O error occurs

SecurityException - In the case of the default provider, and a security manager is installed, its checkWrite method denies write access to the file. If this method is invoked to set security sensitive attributes then the security manager may be invoked to check for additional permissions.

getFileStore

public final FileStore getFileStore(Path path)
                             throws IOException

Returns the FileStore representing the file store where a file is located. This method works in exactly the manner specified by the Files.getFileStore(java.nio.file.Path) method.

Specified by:

getFileStore in class FileSystemProvider

Parameters:

path - the path to the file

Returns:

the file store where the file is stored

Throws:

IOException - if an I/O error occurs

SecurityException - In the case of the default provider, and a security manager is installed, the checkRead method is invoked to check read access to the file, and in addition it checks RuntimePermission ("getFileStoreAttributes")

copyToOpenOptions

protected OpenOption[] copyToOpenOptions(CopyOption... copyOptions)

Convert a set of copy options to a set of open options

This method is used in copy(Path, Path, CopyOption...) when the filesystems for the source and destination paths are different.

The set of options built from this method (if any) will be passed to FileSystemDriver.newOutputStream(Path, OpenOption...).

The default implementation will refuse both StandardCopyOption.COPY_ATTRIBUTES and StandardCopyOption.ATOMIC_MOVE, and will transform StandardCopyOption.REPLACE_EXISTING into both open options StandardOpenOption.WRITE and StandardOpenOption.CREATE_NEW. All other copy options are not supported.

Parameters:

copyOptions - the options to copy (never null)

Returns:

the matching set of open options

Throws:

UnsupportedOperationException - one specified option is not supported