com.github.robtimus.filesystems

Class FileSystemMap<S extends FileSystem>

java.lang.Object

com.github.robtimus.filesystems.FileSystemMap<S>

Type Parameters:

S - The type of file system to maintain.

public final class FileSystemMap<S extends FileSystem>
extends Object

A map for file systems that can be used by FileSystemProvider implementations. This class provides a thread-safe way to add, retrieve and remove file systems without any unnecessary locking during the actual creation of file systems, which may take a while. It does so by maintaining a lock per URI; calling addIfNotExists(URI, Map) , get(URI), find(URI) or remove(URI) while a file system is still being created will block until the creation is done (or has failed). However, any call with a different URI will not block until the file system is created.

All methods that take a URI require the same URI to be used. While that is often automatically the case for adding and removing file systems from FileSystemProvider.newFileSystem(URI, Map) and FileSystem.close() respectively, and usually also for retrieving file systems from FileSystemProvider.getFileSystem(URI), FileSystemProvider.getPath(URI) often needs some conversion or normalization, as it allows sub paths. This class does not enforce any conversion or normalization; however, it does provide access to the currently registered URIs through uris(). That returns a NavigableSet, which allows a closest match to be easily found for a URI.

Author:

Rob Spoor

Since:

2.1

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	FileSystemMap.FileSystemFactory<S extends FileSystem> A factory for file system.
static class	FileSystemMap.FileSystemStatus<S extends FileSystem> The status for a file system.

Constructor Summary

Constructors

Constructor and Description
FileSystemMap(FileSystemMap.FileSystemFactory<? extends S> factory) Creates a new FileSystem map.

Method Summary

Modifier and Type	Method and Description
S	add(URI uri, Map<String,?> env) Adds a new file system.
S	addIfNotExists(URI uri, Map<String,?> env) Adds a new file system if it does not exist yet.
Optional<S>	find(URI uri) Returns a previously added file system if it exists.
S	get(URI uri) Returns a previously added file system.
boolean	remove(URI uri) Removes a previously added file system.
FileSystemMap.FileSystemStatus<S>	status(URI uri) Returns the status for a file system.
NavigableSet<URI>	uris() Returns the URIs of the currently added file systems.

Methods inherited from class java.lang.Object

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

Constructor Detail

FileSystemMap

public FileSystemMap(FileSystemMap.FileSystemFactory<? extends S> factory)

Creates a new FileSystem map.

Parameters:

factory - The factory to use to create new FileSystem instances.

Method Detail

add

public S add(URI uri,
             Map<String,?> env)
      throws IOException

Adds a new file system. It is created using the factory provided in the constructor.

Parameters:

uri - The URI representing the file system.

env - A map of provider specific properties to configure the file system.

Returns:

The new file system.

Throws:

NullPointerException - If the given URI or map is null.

FileSystemAlreadyExistsException - If a file system has already been added for the given URI.

IOException - If the file system could not be created.

See Also:

FileSystemProvider.newFileSystem(URI, Map)

addIfNotExists

public S addIfNotExists(URI uri,
                        Map<String,?> env)
                 throws IOException

Adds a new file system if it does not exist yet. It is created using the factory provided in the constructor. If a file system has already been added for the given URI, the existing file system is returned and no new file system is created. This can be used for FileSystemProvider.getPath(URI) to create a new file system automatically. The map argument should then contain default properties as necessary to create the file system.

Parameters:

uri - The URI representing the file system to add or return.

env - A map of provider specific properties to configure the file system. Ignored if the file system already exists.

Returns:

The new or existing file system.

Throws:

NullPointerException - If the given URI or map is null.

IOException - If the file system could not be created.

Since:

2.3

get

public S get(URI uri)

Returns a previously added file system.

Parameters:

uri - The URI representing the file system.

Returns:

The file system represented by the given URI.

Throws:

NullPointerException - If the given URI is null.

FileSystemNotFoundException - If no file system has been added for the given URI.

See Also:

FileSystemProvider.getFileSystem(URI)

find

public Optional<S> find(URI uri)

Returns a previously added file system if it exists.

Parameters:

uri - The URI representing the file system.

Returns:

An Optional describing the file system represented by the given URI, or Optional.empty() if no file system has been added for the given URI.

Throws:

NullPointerException - If the given URI is null.

Since:

2.3

remove

public boolean remove(URI uri)

Removes a previously added file system. This method should be called when a file system returned by add(URI, Map) or addIfNotExists(URI, Map) is closed.

If no file system had been added for the given URI, or if it already had been removed, no error will be thrown.

Parameters:

uri - The URI representing the file system.

Returns:

true if a file system was added for the given URI, or false otherwise.

Throws:

NullPointerException - If the given URI is null.

See Also:

FileSystem.close()

status

public FileSystemMap.FileSystemStatus<S> status(URI uri)

Returns the status for a file system. Unlike get(URI) or find(URI), this method will not block if a file system is still being created. That makes it possible to distinguish the three different states for a file system: not found, still being created, or already created. See the documentation of FileSystemMap.FileSystemStatus for more information.

Parameters:

uri - The URI representing the file system.

Returns:

An object representing the status - not found, still being created or already created.

Throws:

NullPointerException - If the given URI is null.

Since:

2.3

uris

public NavigableSet<URI> uris()

Returns the URIs of the currently added file systems. The result is a snapshot of the current state; it will not be updated if a file system is added or removed.

Note that the URIs of file systems that are still being created as part of add(URI, Map) or addIfNotExists(URI, Map) will be included in the result.

Returns:

A set with the URIs of the currently added file systems.