[14] 8223151: Document whether FileSystemProvider.newFileSystem​(Path, Map) always returns new FileSystem objects

[Brian Burkhalter]

https://bugs.openjdk.java.net/browse/JDK-8223151 <https://bugs.openjdk.java.net/browse/JDK-8223151>

Please see the diff below. A CSR would be in order of course.

It appears that within the JDK the ZipFileSystemProvider is the only FileSystemProvider for which this method does not throw UOE.

Thanks,

Brian

--- a/src/java.base/share/classes/java/nio/file/spi/FileSystemProvider.java
+++ b/src/java.base/share/classes/java/nio/file/spi/FileSystemProvider.java
@@ -268,7 +268,7 @@
      *
      * <p> This method returns a reference to a {@code FileSystem} that was
      * created by invoking the {@link #newFileSystem(URI,Map) newFileSystem(URI,Map)}
-     * method. File systems created the {@link #newFileSystem(Path,Map)
+     * method. File systems created by the {@link #newFileSystem(Path,Map)
      * newFileSystem(Path,Map)} method are not returned by this method.
      * The file system is identified by its {@code URI}. Its exact form
      * is highly provider dependent. In the case of the default provider the URI's
@@ -351,6 +351,14 @@
      * it throws {@code UnsupportedOperationException}. The default implementation
      * of this method throws {@code UnsupportedOperationException}.
      *
+     * <p> Unlike {@link #newFileSystem(URI,Map)}, this method does <i>not</i>
+     * throw a {@link FileSystemAlreadyExistsException} if it is invoked
+     * with the same {@code path} used previously to create a file system.
+     * It is provider-dependent whether this method returns different
+     * {@link FileSystem} instances for two invocations with the same path. If
+     * different {@link FileSystem} instances are returned, it is likewise
+     * provider-dependent whether such instances can safely be used at once.
+     *
      * @param   path
      *          The path to the file
      * @param   env

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.java.net/pipermail/nio-dev/attachments/20190613/e909cd92/attachment.html>