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 create
168 * 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}.
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<String,String>();
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
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. The {@code file} parameter is a reference to an existing file
347 * and the {@code env} parameter is a map of provider specific properties to
348 * configure the file system.
349 *
350 * <p> This method iterates over the {@link FileSystemProvider#installedProviders()
351 * installed} providers. It invokes, in turn, each provider's {@link
352 * FileSystemProvider#newFileSystem(FileRef,Map) newFileSystem(FileRef,Map)} method.
353 * If a provider returns a file system then the iteration terminates
354 * and the file system is returned. If none of the installed providers return
355 * a {@code FileSystem} then an attempt is made to locate the provider using
356 * the given class loader. If a provider returns a file system then the lookup
357 * terminates and the file system is returned.
358 *
359 * @param file
360 * a reference to a file
361 * @param env
362 * a map of provider specific properties to configure the file system;
363 * may be empty
364 * @param loader
365 * the class loader to locate the provider or {@code null} to only
366 * attempt to locate an installed provider
367 *
368 * @return a new file system
369 *
370 * @throws IllegalArgumentException
371 * if the {@code env} parameter does not contain properties required
372 * by the provider, or a property value is invalid
373 * @throws ProviderNotFoundException
374 * if a provider supporting this file type cannot be located
375 * @throws ServiceConfigurationError
376 * when an error occurs while loading a service provider
377 * @throws IOException
378 * if an I/O error occurs
379 * @throws SecurityException
380 * if a security manager is installed and it denies an unspecified
381 * permission
382 */
383 public static FileSystem newFileSystem(FileRef file,
384 Map<String,?> env,
385 ClassLoader loader)
386 throws IOException
387 {
388 if (file == null)
389 throw new NullPointerException();
390
391 // check installed providers
392 for (FileSystemProvider provider: FileSystemProvider.installedProviders()) {
393 try {
394 return provider.newFileSystem(file, env);
395 } catch (UnsupportedOperationException uoe) {
396 }
397 }
398
399 // if not found, use service-provider loading facility
400 if (loader != null) {
401 ServiceLoader<FileSystemProvider> sl = ServiceLoader
402 .load(FileSystemProvider.class, loader);
403 for (FileSystemProvider provider: sl) {
404 try {
405 return provider.newFileSystem(file, env);
406 } catch (UnsupportedOperationException uoe) {
407 }
408 }
409 }
410
411 throw new ProviderNotFoundException("Provider not found");
412 }
413 }
|
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}.
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
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 }
|