Module com.github.robtimus.filesystems
Package com.github.robtimus.filesystems

Class FileSystemMap<S extends FileSystem>

  • 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

    • Method Detail

      • 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

      • 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.