Showing the changes to java/pkg/java/nio/file/FileSystems.java (1 of 18352 files). Show all
Unified · Split
| @@ -0,0 +1,405 @@ | |||
| 1 | /* | ||
| 2 | * Copyright (c) 2007, 2011, Oracle and/or its affiliates. All rights reserved. | ||
| 3 | * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. | ||
| 4 | * | ||
| 5 | * This code is free software; you can redistribute it and/or modify it | ||
| 6 | * under the terms of the GNU General Public License version 2 only, as | ||
| 7 | * published by the Free Software Foundation. Oracle designates this | ||
| 8 | * particular file as subject to the "Classpath" exception as provided | ||
| 9 | * by Oracle in the LICENSE file that accompanied this code. | ||
| 10 | * | ||
| 11 | * This code is distributed in the hope that it will be useful, but WITHOUT | ||
| 12 | * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or | ||
| 13 | * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License | ||
| 14 | * version 2 for more details (a copy is included in the LICENSE file that | ||
| 15 | * accompanied this code). | ||
| 16 | * | ||
| 17 | * You should have received a copy of the GNU General Public License version | ||
| 18 | * 2 along with this work; if not, write to the Free Software Foundation, | ||
| 19 | * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. | ||
| 20 | * | ||
| 21 | * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA | ||
| 22 | * or visit www.oracle.com if you need additional information or have any | ||
| 23 | * questions. | ||
| 24 | */ | ||
| 25 | |||
| 26 | package java.nio.file; | ||
| 27 | |||
| 28 | import java.nio.file.spi.FileSystemProvider; | ||
| 29 | import java.net.URI; | ||
| 30 | import java.io.IOException; | ||
| 31 | import java.security.AccessController; | ||
| 32 | import java.security.PrivilegedAction; | ||
| 33 | import java.util.*; | ||
| 34 | import java.lang.reflect.Constructor; | ||
| 35 | |||
| 36 | /** | ||
| 37 | * Factory methods for file systems. This class defines the {@link #getDefault | ||
| 38 | * getDefault} method to get the default file system and factory methods to | ||
| 39 | * construct other types of file systems. | ||
| 40 | * | ||
| 41 | * <p> The first invocation of any of the methods defined by this class causes | ||
| 42 | * the default {@link FileSystemProvider provider} to be loaded. The default | ||
| 43 | * provider, identified by the URI scheme "file", creates the {@link FileSystem} | ||
| 44 | * that provides access to the file systems accessible to the Java virtual | ||
| 45 | * machine. If the process of loading or initializing the default provider fails | ||
| 46 | * then an unspecified error is thrown. | ||
| 47 | * | ||
| 48 | * <p> The first invocation of the {@link FileSystemProvider#installedProviders | ||
| 49 | * installedProviders} method, by way of invoking any of the {@code | ||
| 50 | * newFileSystem} methods defined by this class, locates and loads all | ||
| 51 | * installed file system providers. Installed providers are loaded using the | ||
| 52 | * service-provider loading facility defined by the {@link ServiceLoader} class. | ||
| 53 | * Installed providers are loaded using the system class loader. If the | ||
| 54 | * system class loader cannot be found then the extension class loader is used; | ||
| 55 | * if there is no extension class loader then the bootstrap class loader is used. | ||
| 56 | * Providers are typically installed by placing them in a JAR file on the | ||
| 57 | * application class path or in the extension directory, the JAR file contains a | ||
| 58 | * provider-configuration file named {@code java.nio.file.spi.FileSystemProvider} | ||
| 59 | * in the resource directory {@code META-INF/services}, and the file lists one or | ||
| 60 | * more fully-qualified names of concrete subclass of {@link FileSystemProvider} | ||
| 61 | * that have a zero argument constructor. | ||
| 62 | * The ordering that installed providers are located is implementation specific. | ||
| 63 | * If a provider is instantiated and its {@link FileSystemProvider#getScheme() | ||
| 64 | * getScheme} returns the same URI scheme of a provider that was previously | ||
| 65 | * instantiated then the most recently instantiated duplicate is discarded. URI | ||
| 66 | * schemes are compared without regard to case. During construction a provider | ||
| 67 | * may safely access files associated with the default provider but care needs | ||
| 68 | * to be taken to avoid circular loading of other installed providers. If | ||
| 69 | * circular loading of installed providers is detected then an unspecified error | ||
| 70 | * is thrown. | ||
| 71 | * | ||
| 72 | * <p> This class also defines factory methods that allow a {@link ClassLoader} | ||
| 73 | * to be specified when locating a provider. As with installed providers, the | ||
| 74 | * provider classes are identified by placing the provider configuration file | ||
| 75 | * in the resource directory {@code META-INF/services}. | ||
| 76 | * | ||
| 77 | * <p> If a thread initiates the loading of the installed file system providers | ||
| 78 | * and another thread invokes a method that also attempts to load the providers | ||
| 79 | * then the method will block until the loading completes. | ||
| 80 | * | ||
| 81 | * @since 1.7 | ||
| 82 | */ | ||
| 83 | |||
| 84 | public final class FileSystems { | ||
| 85 | private FileSystems() { | ||
| 86 | } | ||
| 87 | |||
| 88 | // lazy initialization of default file system | ||
| 89 | private static class DefaultFileSystemHolder { | ||
| 90 | static final FileSystem defaultFileSystem = defaultFileSystem(); | ||
| 91 | |||
| 92 | // returns default file system | ||
| 93 | private static FileSystem defaultFileSystem() { | ||
| 94 | // load default provider | ||
| 95 | FileSystemProvider provider = AccessController | ||
| 96 | .doPrivileged(new PrivilegedAction<FileSystemProvider>() { | ||
| 97 | public FileSystemProvider run() { | ||
| 98 | return getDefaultProvider(); | ||
| 99 | } | ||
| 100 | }); | ||
| 101 | |||
| 102 | // return file system | ||
| 103 | return provider.getFileSystem(URI.create("file:///")); | ||
| 104 | } | ||
| 105 | |||
| 106 | // returns default provider | ||
| 107 | private static FileSystemProvider getDefaultProvider() { | ||
| 108 | FileSystemProvider provider = sun.nio.fs.DefaultFileSystemProvider.create(); | ||
| 109 | |||
| 110 | // if the property java.nio.file.spi.DefaultFileSystemProvider is | ||
| 111 | // set then its value is the name of the default provider (or a list) | ||
| 112 | String propValue = System | ||
| 113 | .getProperty("java.nio.file.spi.DefaultFileSystemProvider"); | ||
| 114 | if (propValue != null) { | ||
| 115 | for (String cn: propValue.split(",")) { | ||
| 116 | try { | ||
| 117 | Class<?> c = Class | ||
| 118 | .forName(cn, true, ClassLoader.getSystemClassLoader()); | ||
| 119 | Constructor<?> ctor = c | ||
| 120 | .getDeclaredConstructor(FileSystemProvider.class); | ||
| 121 | provider = (FileSystemProvider)ctor.newInstance(provider); | ||
| 122 | |||
| 123 | // must be "file" | ||
| 124 | if (!provider.getScheme().equals("file")) | ||
| 125 | throw new Error("Default provider must use scheme 'file'"); | ||
| 126 | |||
| 127 | } catch (Exception x) { | ||
| 128 | throw new Error(x); | ||
| 129 | } | ||
| 130 | } | ||
| 131 | } | ||
| 132 | return provider; | ||
| 133 | } | ||
| 134 | } | ||
| 135 | |||
| 136 | /** | ||
| 137 | * Returns the default {@code FileSystem}. The default file system creates | ||
| 138 | * objects that provide access to the file systems accessible to the Java | ||
| 139 | * virtual machine. The <em>working directory</em> of the file system is | ||
| 140 | * the current user directory, named by the system property {@code user.dir}. | ||
| 141 | * This allows for interoperability with the {@link java.io.File java.io.File} | ||
| 142 | * class. | ||
| 143 | * | ||
| 144 | * <p> The first invocation of any of the methods defined by this class | ||
| 145 | * locates the default {@link FileSystemProvider provider} object. Where the | ||
| 146 | * system property {@code java.nio.file.spi.DefaultFileSystemProvider} is | ||
| 147 | * not defined then the default provider is a system-default provider that | ||
| 148 | * is invoked to create the default file system. | ||
| 149 | * | ||
| 150 | * <p> If the system property {@code java.nio.file.spi.DefaultFileSystemProvider} | ||
| 151 | * is defined then it is taken to be a list of one or more fully-qualified | ||
| 152 | * names of concrete provider classes identified by the URI scheme | ||
| 153 | * {@code "file"}. Where the property is a list of more than one name then | ||
| 154 | * the names are separated by a comma. Each class is loaded, using the system | ||
| 155 | * class loader, and instantiated by invoking a one argument constructor | ||
| 156 | * whose formal parameter type is {@code FileSystemProvider}. The providers | ||
| 157 | * are loaded and instantiated in the order they are listed in the property. | ||
| 158 | * If this process fails or a provider's scheme is not equal to {@code "file"} | ||
| 159 | * then an unspecified error is thrown. URI schemes are normally compared | ||
| 160 | * without regard to case but for the default provider, the scheme is | ||
| 161 | * required to be {@code "file"}. The first provider class is instantiated | ||
| 162 | * by invoking it with a reference to the system-default provider. | ||
| 163 | * The second provider class is instantiated by invoking it with a reference | ||
| 164 | * to the first provider instance. The third provider class is instantiated | ||
| 165 | * by invoking it with a reference to the second instance, and so on. The | ||
| 166 | * last provider to be instantiated becomes the default provider; its {@code | ||
| 167 | * getFileSystem} method is invoked with the URI {@code "file:///"} to | ||
| 168 | * get a reference to the default file system. | ||
| 169 | * | ||
| 170 | * <p> Subsequent invocations of this method return the file system that was | ||
| 171 | * returned by the first invocation. | ||
| 172 | * | ||
| 173 | * @return the default file system | ||
| 174 | */ | ||
| 175 | public static FileSystem getDefault() { | ||
| 176 | return DefaultFileSystemHolder.defaultFileSystem; | ||
| 177 | } | ||
| 178 | |||
| 179 | /** | ||
| 180 | * Returns a reference to an existing {@code FileSystem}. | ||
| 181 | * | ||
| 182 | * <p> This method iterates over the {@link FileSystemProvider#installedProviders() | ||
| 183 | * installed} providers to locate the provider that is identified by the URI | ||
| 184 | * {@link URI#getScheme scheme} of the given URI. URI schemes are compared | ||
| 185 | * without regard to case. The exact form of the URI is highly provider | ||
| 186 | * dependent. If found, the provider's {@link FileSystemProvider#getFileSystem | ||
| 187 | * getFileSystem} method is invoked to obtain a reference to the {@code | ||
| 188 | * FileSystem}. | ||
| 189 | * | ||
| 190 | * <p> Once a file system created by this provider is {@link FileSystem#close | ||
| 191 | * closed} it is provider-dependent if this method returns a reference to | ||
| 192 | * the closed file system or throws {@link FileSystemNotFoundException}. | ||
| 193 | * If the provider allows a new file system to be created with the same URI | ||
| 194 | * as a file system it previously created then this method throws the | ||
| 195 | * exception if invoked after the file system is closed (and before a new | ||
| 196 | * instance is created by the {@link #newFileSystem newFileSystem} method). | ||
| 197 | * | ||
| 198 | * <p> If a security manager is installed then a provider implementation | ||
| 199 | * may require to check a permission before returning a reference to an | ||
| 200 | * existing file system. In the case of the {@link FileSystems#getDefault | ||
| 201 | * default} file system, no permission check is required. | ||
| 202 | * | ||
| 203 | * @throws IllegalArgumentException | ||
| 204 | * if the pre-conditions for the {@code uri} parameter are not met | ||
| 205 | * @throws FileSystemNotFoundException | ||
| 206 | * if the file system, identified by the URI, does not exist | ||
| 207 | * @throws ProviderNotFoundException | ||
| 208 | * if a provider supporting the URI scheme is not installed | ||
| 209 | * @throws SecurityException | ||
| 210 | * if a security manager is installed and it denies an unspecified | ||
| 211 | * permission | ||
| 212 | */ | ||
| 213 | public static FileSystem getFileSystem(URI uri) { | ||
| 214 | String scheme = uri.getScheme(); | ||
| 215 | for (FileSystemProvider provider: FileSystemProvider.installedProviders()) { | ||
| 216 | if (scheme.equalsIgnoreCase(provider.getScheme())) { | ||
| 217 | return provider.getFileSystem(uri); | ||
| 218 | } | ||
| 219 | } | ||
| 220 | throw new ProviderNotFoundException("Provider \"" + scheme + "\" not found"); | ||
| 221 | } | ||
| 222 | |||
| 223 | /** | ||
| 224 | * Constructs a new file system that is identified by a {@link URI} | ||
| 225 | * | ||
| 226 | * <p> This method iterates over the {@link FileSystemProvider#installedProviders() | ||
| 227 | * installed} providers to locate the provider that is identified by the URI | ||
| 228 | * {@link URI#getScheme scheme} of the given URI. URI schemes are compared | ||
| 229 | * without regard to case. The exact form of the URI is highly provider | ||
| 230 | * dependent. If found, the provider's {@link FileSystemProvider#newFileSystem(URI,Map) | ||
| 231 | * newFileSystem(URI,Map)} method is invoked to construct the new file system. | ||
| 232 | * | ||
| 233 | * <p> Once a file system is {@link FileSystem#close closed} it is | ||
| 234 | * provider-dependent if the provider allows a new file system to be created | ||
| 235 | * with the same URI as a file system it previously created. | ||
| 236 | * | ||
| 237 | * <p> <b>Usage Example:</b> | ||
| 238 | * Suppose there is a provider identified by the scheme {@code "memory"} | ||
| 239 | * installed: | ||
| 240 | * <pre> | ||
| 241 | * Map<String,String> env = new HashMap<>(); | ||
| 242 | * env.put("capacity", "16G"); | ||
| 243 | * env.put("blockSize", "4k"); | ||
| 244 | * FileSystem fs = FileSystems.newFileSystem(URI.create("memory:///?name=logfs"), env); | ||
| 245 | * </pre> | ||
| 246 | * | ||
| 247 | * @param uri | ||
| 248 | * the URI identifying the file system | ||
| 249 | * @param env | ||
| 250 | * a map of provider specific properties to configure the file system; | ||
| 251 | * may be empty | ||
| 252 | * | ||
| 253 | * @return a new file system | ||
| 254 | * | ||
| 255 | * @throws IllegalArgumentException | ||
| 256 | * if the pre-conditions for the {@code uri} parameter are not met, | ||
| 257 | * or the {@code env} parameter does not contain properties required | ||
| 258 | * by the provider, or a property value is invalid | ||
| 259 | * @throws FileSystemAlreadyExistsException | ||
| 260 | * if the file system has already been created | ||
| 261 | * @throws ProviderNotFoundException | ||
| 262 | * if a provider supporting the URI scheme is not installed | ||
| 263 | * @throws IOException | ||
| 264 | * if an I/O error occurs creating the file system | ||
| 265 | * @throws SecurityException | ||
| 266 | * if a security manager is installed and it denies an unspecified | ||
| 267 | * permission required by the file system provider implementation | ||
| 268 | */ | ||
| 269 | public static FileSystem newFileSystem(URI uri, Map<String,?> env) | ||
| 270 | throws IOException | ||
| 271 | { | ||
| 272 | return newFileSystem(uri, env, null); | ||
| 273 | } | ||
| 274 | |||
| 275 | /** | ||
| 276 | * Constructs a new file system that is identified by a {@link URI} | ||
| 277 | * | ||
| 278 | * <p> This method first attempts to locate an installed provider in exactly | ||
| 279 | * the same manner as the {@link #newFileSystem(URI,Map) newFileSystem(URI,Map)} | ||
| 280 | * method. If none of the installed providers support the URI scheme then an | ||
| 281 | * attempt is made to locate the provider using the given class loader. If a | ||
| 282 | * provider supporting the URI scheme is located then its {@link | ||
| 283 | * FileSystemProvider#newFileSystem(URI,Map) newFileSystem(URI,Map)} is | ||
| 284 | * invoked to construct the new file system. | ||
| 285 | * | ||
| 286 | * @param uri | ||
| 287 | * the URI identifying the file system | ||
| 288 | * @param env | ||
| 289 | * a map of provider specific properties to configure the file system; | ||
| 290 | * may be empty | ||
| 291 | * @param loader | ||
| 292 | * the class loader to locate the provider or {@code null} to only | ||
| 293 | * attempt to locate an installed provider | ||
| 294 | * | ||
| 295 | * @return a new file system | ||
| 296 | * | ||
| 297 | * @throws IllegalArgumentException | ||
| 298 | * if the pre-conditions for the {@code uri} parameter are not met, | ||
| 299 | * or the {@code env} parameter does not contain properties required | ||
| 300 | * by the provider, or a property value is invalid | ||
| 301 | * @throws FileSystemAlreadyExistsException | ||
| 302 | * if the URI scheme identifies an installed provider and the file | ||
| 303 | * system has already been created | ||
| 304 | * @throws ProviderNotFoundException | ||
| 305 | * if a provider supporting the URI scheme is not found | ||
| 306 | * @throws ServiceConfigurationError | ||
| 307 | * when an error occurs while loading a service provider | ||
| 308 | * @throws IOException | ||
| 309 | * an I/O error occurs creating the file system | ||
| 310 | * @throws SecurityException | ||
| 311 | * if a security manager is installed and it denies an unspecified | ||
| 312 | * permission required by the file system provider implementation | ||
| 313 | */ | ||
| 314 | public static FileSystem newFileSystem(URI uri, Map<String,?> env, ClassLoader loader) | ||
| 315 | throws IOException | ||
| 316 | { | ||
| 317 | String scheme = uri.getScheme(); | ||
| 318 | |||
| 319 | // check installed providers | ||
| 320 | for (FileSystemProvider provider: FileSystemProvider.installedProviders()) { | ||
| 321 | if (scheme.equalsIgnoreCase(provider.getScheme())) { | ||
| 322 | return provider.newFileSystem(uri, env); | ||
| 323 | } | ||
| 324 | } | ||
| 325 | |||
| 326 | // if not found, use service-provider loading facility | ||
| 327 | if (loader != null) { | ||
| 328 | ServiceLoader<FileSystemProvider> sl = ServiceLoader | ||
| 329 | .load(FileSystemProvider.class, loader); | ||
| 330 | for (FileSystemProvider provider: sl) { | ||
| 331 | if (scheme.equalsIgnoreCase(provider.getScheme())) { | ||
| 332 | return provider.newFileSystem(uri, env); | ||
| 333 | } | ||
| 334 | } | ||
| 335 | } | ||
| 336 | |||
| 337 | throw new ProviderNotFoundException("Provider \"" + scheme + "\" not found"); | ||
| 338 | } | ||
| 339 | |||
| 340 | /** | ||
| 341 | * Constructs a new {@code FileSystem} to access the contents of a file as a | ||
| 342 | * file system. | ||
| 343 | * | ||
| 344 | * <p> This method makes use of specialized providers that create pseudo file | ||
| 345 | * systems where the contents of one or more files is treated as a file | ||
| 346 | * system. | ||
| 347 | * | ||
| 348 | * <p> This method iterates over the {@link FileSystemProvider#installedProviders() | ||
| 349 | * installed} providers. It invokes, in turn, each provider's {@link | ||
| 350 | * FileSystemProvider#newFileSystem(Path,Map) newFileSystem(Path,Map)} method | ||
| 351 | * with an empty map. If a provider returns a file system then the iteration | ||
| 352 | * terminates and the file system is returned. If none of the installed | ||
| 353 | * providers return a {@code FileSystem} then an attempt is made to locate | ||
| 354 | * the provider using the given class loader. If a provider returns a file | ||
| 355 | * system then the lookup terminates and the file system is returned. | ||
| 356 | * | ||
| 357 | * @param path | ||
| 358 | * the path to the file | ||
| 359 | * @param loader | ||
| 360 | * the class loader to locate the provider or {@code null} to only | ||
| 361 | * attempt to locate an installed provider | ||
| 362 | * | ||
| 363 | * @return a new file system | ||
| 364 | * | ||
| 365 | * @throws ProviderNotFoundException | ||
| 366 | * if a provider supporting this file type cannot be located | ||
| 367 | * @throws ServiceConfigurationError | ||
| 368 | * when an error occurs while loading a service provider | ||
| 369 | * @throws IOException | ||
| 370 | * if an I/O error occurs | ||
| 371 | * @throws SecurityException | ||
| 372 | * if a security manager is installed and it denies an unspecified | ||
| 373 | * permission | ||
| 374 | */ | ||
| 375 | public static FileSystem newFileSystem(Path path, | ||
| 376 | ClassLoader loader) | ||
| 377 | throws IOException | ||
| 378 | { | ||
| 379 | if (path == null) | ||
| 380 | throw new NullPointerException(); | ||
| 381 | Map<String,?> env = Collections.emptyMap(); | ||
| 382 | |||
| 383 | // check installed providers | ||
| 384 | for (FileSystemProvider provider: FileSystemProvider.installedProviders()) { | ||
| 385 | try { | ||
| 386 | return provider.newFileSystem(path, env); | ||
| 387 | } catch (UnsupportedOperationException uoe) { | ||
| 388 | } | ||
| 389 | } | ||
| 390 | |||
| 391 | // if not found, use service-provider loading facility | ||
| 392 | if (loader != null) { | ||
| 393 | ServiceLoader<FileSystemProvider> sl = ServiceLoader | ||
| 394 | .load(FileSystemProvider.class, loader); | ||
| 395 | for (FileSystemProvider provider: sl) { | ||
| 396 | try { | ||
| 397 | return provider.newFileSystem(path, env); | ||
| 398 | } catch (UnsupportedOperationException uoe) { | ||
| 399 | } | ||
| 400 | } | ||
| 401 | } | ||
| 402 | |||
| 403 | throw new ProviderNotFoundException("Provider not found"); | ||
| 404 | } | ||
| 405 | } | ||