1 /*
2 * Copyright (c) 2007, 2009, 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.spi;
27
28 import java.nio.file.*;
29 import java.nio.file.attribute.*;
30 import java.nio.channels.*;
31 import java.net.URI;
32 import java.io.InputStream;
33 import java.io.OutputStream;
34 import java.io.IOException;
35 import java.util.*;
36 import java.util.concurrent.ExecutorService;
37 import java.security.AccessController;
38 import java.security.PrivilegedAction;
39
40 /**
41 * Service-provider class for file systems. The methods defined by the {@link
42 * java.nio.file.Files} class will typically delegate to an instance of this
43 * class.
44 *
45 * <p> A file system provider is a concrete implementation of this class that
46 * implements the abstract methods defined by this class. A provider is
47 * identified by a {@code URI} {@link #getScheme() scheme}. The default provider
48 * is identified by the URI scheme "file". It creates the {@link FileSystem} that
49 * provides access to the file systems accessible to the Java virtual machine.
50 * The {@link FileSystems} class defines how file system providers are located
51 * and loaded. The default provider is typically a system-default provider but
52 * may be overridden if the system property {@code
53 * java.nio.file.spi.DefaultFileSystemProvider} is set. In that case, the
54 * provider has a one argument constructor whose formal parameter type is {@code
55 * FileSystemProvider}. All other providers have a zero argument constructor
56 * that initializes the provider.
57 *
58 * <p> A provider is a factory for one or more {@link FileSystem} instances. Each
59 * file system is identified by a {@code URI} where the URI's scheme matches
60 * the provider's {@link #getScheme scheme}. The default file system, for example,
61 * is identified by the URI {@code "file:///"}. A memory-based file system,
62 * for example, may be identified by a URI such as {@code "memory:///?name=logfs"}.
63 * The {@link #newFileSystem newFileSystem} method may be used to create a file
64 * system, and the {@link #getFileSystem getFileSystem} method may be used to
65 * obtain a reference to an existing file system created by the provider. Where
66 * a provider is the factory for a single file system then it is provider dependent
67 * if the file system is created when the provider is initialized, or later when
68 * the {@code newFileSystem} method is invoked. In the case of the default
69 * provider, the {@code FileSystem} is created when the provider is initialized.
70 *
71 * <p> All of the methods in this class are safe for use by multiple concurrent
72 * threads.
73 *
74 * @since 1.7
75 */
76
77 public abstract class FileSystemProvider {
78 // lock using when loading providers
79 private static final Object lock = new Object();
80
81 // installed providers
82 private static volatile List<FileSystemProvider> installedProviders;
83
84 // used to avoid recursive loading of instaled providers
85 private static boolean loadingProviders = false;
86
87 private static Void checkPermission() {
88 SecurityManager sm = System.getSecurityManager();
89 if (sm != null)
90 sm.checkPermission(new RuntimePermission("fileSystemProvider"));
91 return null;
92 }
93 private FileSystemProvider(Void ignore) { }
94
95 /**
96 * Initializes a new instance of this class.
97 *
98 * <p> During construction a provider may safely access files associated
99 * with the default provider but care needs to be taken to avoid circular
100 * loading of other installed providers. If circular loading of installed
101 * providers is detected then an unspecified error is thrown.
102 *
103 * @throws SecurityException
104 * If a security manager has been installed and it denies
105 * {@link RuntimePermission}<tt>("fileSystemProvider")</tt>
106 */
107 protected FileSystemProvider() {
108 this(checkPermission());
109 }
110
111 // loads all installed providers
112 private static List<FileSystemProvider> loadInstalledProviders() {
113 List<FileSystemProvider> list = new ArrayList<FileSystemProvider>();
114
115 ServiceLoader<FileSystemProvider> sl = ServiceLoader
116 .load(FileSystemProvider.class, ClassLoader.getSystemClassLoader());
117
118 // ServiceConfigurationError may be throw here
119 for (FileSystemProvider provider: sl) {
120 String scheme = provider.getScheme();
121
122 // add to list if the provider is not "file" and isn't a duplicate
123 if (!scheme.equalsIgnoreCase("file")) {
124 boolean found = false;
125 for (FileSystemProvider p: list) {
126 if (p.getScheme().equalsIgnoreCase(scheme)) {
127 found = true;
128 break;
129 }
130 }
131 if (!found) {
132 list.add(provider);
133 }
134 }
135 }
136 return list;
137 }
138
139 /**
140 * Returns a list of the installed file system providers.
141 *
142 * <p> The first invocation of this method causes the default provider to be
143 * initialized (if not already initialized) and loads any other installed
144 * providers as described by the {@link FileSystems} class.
145 *
146 * @return An unmodifiable list of the installed file system providers. The
147 * list contains at least one element, that is the default file
148 * system provider
149 *
150 * @throws ServiceConfigurationError
151 * When an error occurs while loading a service provider
152 */
153 public static List<FileSystemProvider> installedProviders() {
154 if (installedProviders == null) {
155 // ensure default provider is initialized
156 FileSystemProvider defaultProvider = FileSystems.getDefault().provider();
157
158 synchronized (lock) {
159 if (installedProviders == null) {
160 if (loadingProviders) {
161 throw new Error("Circular loading of installed providers detected");
162 }
163 loadingProviders = true;
164
165 List<FileSystemProvider> list = AccessController
166 .doPrivileged(new PrivilegedAction<List<FileSystemProvider>>() {
167 @Override
168 public List<FileSystemProvider> run() {
169 return loadInstalledProviders();
170 }});
171
172 // insert the default provider at the start of the list
173 list.add(0, defaultProvider);
174
175 installedProviders = Collections.unmodifiableList(list);
176 }
177 }
178 }
179 return installedProviders;
180 }
181
182 /**
183 * Returns the URI scheme that identifies this provider.
184 *
185 * @return The URI scheme
186 */
187 public abstract String getScheme();
188
189 /**
190 * Constructs a new {@code FileSystem} object identified by a URI. This
191 * method is invoked by the {@link FileSystems#newFileSystem(URI,Map)}
192 * method to open a new file system identified by a URI.
193 *
194 * <p> The {@code uri} parameter is an absolute, hierarchical URI, with a
195 * scheme equal (without regard to case) to the scheme supported by this
196 * provider. The exact form of the URI is highly provider dependent. The
197 * {@code env} parameter is a map of provider specific properties to configure
198 * the file system.
199 *
200 * <p> This method throws {@link FileSystemAlreadyExistsException} if the
201 * file system already exists because it was previously created by an
202 * invocation of this method. Once a file system is {@link
203 * java.nio.file.FileSystem#close closed} it is provider-dependent if the
204 * provider allows a new file system to be created with the same URI as a
205 * file system it previously created.
206 *
207 * @param uri
208 * URI reference
209 * @param env
210 * A map of provider specific properties to configure the file system;
211 * may be empty
212 *
213 * @return A new file system
214 *
215 * @throws IllegalArgumentException
216 * If the pre-conditions for the {@code uri} parameter aren't met,
217 * or the {@code env} parameter does not contain properties required
218 * by the provider, or a property value is invalid
219 * @throws IOException
220 * An I/O error occurs creating the file system
221 * @throws SecurityException
222 * If a security manager is installed and it denies an unspecified
223 * permission required by the file system provider implementation
224 * @throws FileSystemAlreadyExistsException
225 * If the file system has already been created
226 */
227 public abstract FileSystem newFileSystem(URI uri, Map<String,?> env)
228 throws IOException;
229
230 /**
231 * Returns an existing {@code FileSystem} created by this provider.
232 *
233 * <p> This method returns a reference to a {@code FileSystem} that was
234 * created by invoking the {@link #newFileSystem(URI,Map) newFileSystem(URI,Map)}
235 * method. File systems created the {@link #newFileSystem(Path,Map)
236 * newFileSystem(Path,Map)} method are not returned by this method.
237 * The file system is identified by its {@code URI}. Its exact form
238 * is highly provider dependent. In the case of the default provider the URI's
239 * path component is {@code "/"} and the authority, query and fragment components
240 * are undefined (Undefined components are represented by {@code null}).
241 *
242 * <p> Once a file system created by this provider is {@link
243 * java.nio.file.FileSystem#close closed} it is provider-dependent if this
244 * method returns a reference to the closed file system or throws {@link
245 * FileSystemNotFoundException}. If the provider allows a new file system to
246 * be created with the same URI as a file system it previously created then
247 * this method throws the exception if invoked after the file system is
248 * closed (and before a new instance is created by the {@link #newFileSystem
249 * newFileSystem} method).
250 *
251 * <p> If a security manager is installed then a provider implementation
252 * may require to check a permission before returning a reference to an
253 * existing file system. In the case of the {@link FileSystems#getDefault
254 * default} file system, no permission check is required.
255 *
256 * @param uri
257 * URI reference
258 *
259 * @return The file system
260 *
261 * @throws IllegalArgumentException
262 * If the pre-conditions for the {@code uri} parameter aren't met
263 * @throws FileSystemNotFoundException
264 * If the file system does not exist
265 * @throws SecurityException
266 * If a security manager is installed and it denies an unspecified
267 * permission.
268 */
269 public abstract FileSystem getFileSystem(URI uri);
270
271 /**
272 * Return a {@code Path} object by converting the given {@link URI}. The
273 * resulting {@code Path} is associated with a {@link FileSystem} that
274 * already exists or is constructed automatically.
275 *
276 * <p> The exact form of the URI is file system provider dependent. In the
277 * case of the default provider, the URI scheme is {@code "file"} and the
278 * given URI has a non-empty path component, and undefined query, and
279 * fragment components. The resulting {@code Path} is associated with the
280 * default {@link FileSystems#getDefault default} {@code FileSystem}.
281 *
282 * <p> If a security manager is installed then a provider implementation
283 * may require to check a permission. In the case of the {@link
284 * FileSystems#getDefault default} file system, no permission check is
285 * required.
286 *
287 * @param uri
288 * The URI to convert
289 *
290 * @throws IllegalArgumentException
291 * If the URI scheme does not identify this provider or other
292 * preconditions on the uri parameter do not hold
293 * @throws FileSystemNotFoundException
294 * The file system, identified by the URI, does not exist and
295 * cannot be created automatically
296 * @throws SecurityException
297 * If a security manager is installed and it denies an unspecified
298 * permission.
299 */
300 public abstract Path getPath(URI uri);
301
302 /**
303 * Constructs a new {@code FileSystem} to access the contents of a file as a
304 * file system.
305 *
306 * <p> This method is intended for specialized providers of pseudo file
307 * systems where the contents of one or more files is treated as a file
308 * system. The {@code env} parameter is a map of provider specific properties
309 * to configure the file system.
310 *
311 * <p> If this provider does not support the creation of such file systems
312 * or if the provider does not recognize the file type of the given file then
313 * it throws {@code UnsupportedOperationException}. The default implementation
314 * of this method throws {@code UnsupportedOperationException}.
315 *
316 * @param path
317 * The path to the file
318 * @param env
319 * A map of provider specific properties to configure the file system;
320 * may be empty
321 *
322 * @return A new file system
323 *
324 * @throws UnsupportedOperationException
325 * If this provider does not support access to the contents as a
326 * file system or it does not recognize the file type of the
327 * given file
328 * @throws IllegalArgumentException
329 * If the {@code env} parameter does not contain properties required
330 * by the provider, or a property value is invalid
331 * @throws IOException
332 * If an I/O error occurs
333 * @throws SecurityException
334 * If a security manager is installed and it denies an unspecified
335 * permission.
336 */
337 public FileSystem newFileSystem(Path path, Map<String,?> env)
338 throws IOException
339 {
340 throw new UnsupportedOperationException();
341 }
342
343 /**
344 * Opens a file, returning an input stream to read from the file. This
345 * method works in exactly the manner specified by the {@link
346 * Files#newInputStream} method.
347 *
348 * <p> The default implementation of this method opens a channel to the file
349 * as if by invoking the {@link #newByteChannel} method and constructs a
350 * stream that reads bytes from the channel. This method should be overridden
351 * where appropriate.
352 *
353 * @param path
354 * the path to the file to open
355 * @param options
356 * options specifying how the file is opened
357 *
358 * @return a new input stream
359 *
360 * @throws IllegalArgumentException
361 * if an invalid combination of options is specified
362 * @throws UnsupportedOperationException
363 * if an unsupported option is specified
364 * @throws IOException
365 * if an I/O error occurs
366 * @throws SecurityException
367 * In the case of the default provider, and a security manager is
368 * installed, the {@link SecurityManager#checkRead(String) checkRead}
369 * method is invoked to check read access to the file.
370 */
371 public InputStream newInputStream(Path path, OpenOption... options)
372 throws IOException
373 {
374 if (options.length > 0) {
375 for (OpenOption opt: options) {
376 if (opt != StandardOpenOption.READ)
377 throw new UnsupportedOperationException("'" + opt + "' not allowed");
378 }
379 }
380 return Channels.newInputStream(Files.newByteChannel(path));
381 }
382
383 /**
384 * Opens or creates a file, returning an output stream that may be used to
385 * write bytes to the file. This method works in exactly the manner
386 * specified by the {@link Files#newOutputStream} method.
387 *
388 * <p> The default implementation of this method opens a channel to the file
389 * as if by invoking the {@link #newByteChannel} method and constructs a
390 * stream that writes bytes to the channel. This method should be overridden
391 * where appropriate.
392 *
393 * @param path
394 * the path to the file to open or create
395 * @param options
396 * options specifying how the file is opened
397 *
398 * @return a new output stream
399 *
400 * @throws IllegalArgumentException
401 * if {@code options} contains an invalid combination of options
402 * @throws UnsupportedOperationException
403 * if an unsupported option is specified
404 * @throws IOException
405 * if an I/O error occurs
406 * @throws SecurityException
407 * In the case of the default provider, and a security manager is
408 * installed, the {@link SecurityManager#checkWrite(String) checkWrite}
409 * method is invoked to check write access to the file. The {@link
410 * SecurityManager#checkDelete(String) checkDelete} method is
411 * invoked to check delete access if the file is opened with the
412 * {@code DELETE_ON_CLOSE} option.
413 */
414 public OutputStream newOutputStream(Path path, OpenOption... options)
415 throws IOException
416 {
417 int len = options.length;
418 Set<OpenOption> opts = new HashSet<OpenOption>(len + 3);
419 if (len == 0) {
420 opts.add(StandardOpenOption.CREATE);
421 opts.add(StandardOpenOption.TRUNCATE_EXISTING);
422 } else {
423 for (OpenOption opt: options) {
424 if (opt == StandardOpenOption.READ)
425 throw new IllegalArgumentException("READ not allowed");
426 opts.add(opt);
427 }
428 }
429 opts.add(StandardOpenOption.WRITE);
430 return Channels.newOutputStream(newByteChannel(path, opts));
431 }
432
433 /**
434 * Opens or creates a file for reading and/or writing, returning a file
435 * channel to access the file. This method works in exactly the manner
436 * specified by the {@link FileChannel#open(Path,Set,FileAttribute[])
437 * FileChannel.open} method. A provider that does not support all the
438 * features required to construct a file channel throws {@code
439 * UnsupportedOperationException}. The default provider is required to
440 * support the creation of file channels. When not overridden, the default
441 * implementation throws {@code UnsupportedOperationException}.
442 *
443 * @param path
444 * the path of the file to open or create
445 * @param options
446 * options specifying how the file is opened
447 * @param attrs
448 * an optional list of file attributes to set atomically when
449 * creating the file
450 *
451 * @return a new file channel
452 *
453 * @throws IllegalArgumentException
454 * If the set contains an invalid combination of options
455 * @throws UnsupportedOperationException
456 * If this provider that does not support creating file channels,
457 * or an unsupported open option or file attribute is specified
458 * @throws IOException
459 * If an I/O error occurs
460 * @throws SecurityException
461 * In the case of the default file system, the {@link
462 * SecurityManager#checkRead(String)} method is invoked to check
463 * read access if the file is opened for reading. The {@link
464 * SecurityManager#checkWrite(String)} method is invoked to check
465 * write access if the file is opened for writing
466 */
467 public FileChannel newFileChannel(Path path,
468 Set<? extends OpenOption> options,
469 FileAttribute<?>... attrs)
470 throws IOException
471 {
472 throw new UnsupportedOperationException();
473 }
474
475 /**
476 * Opens or creates a file for reading and/or writing, returning an
477 * asynchronous file channel to access the file. This method works in
478 * exactly the manner specified by the {@link
479 * AsynchronousFileChannel#open(Path,Set,ExecutorService,FileAttribute[])
480 * AsynchronousFileChannel.open} method.
481 * A provider that does not support all the features required to construct
482 * an asynchronous file channel throws {@code UnsupportedOperationException}.
483 * The default provider is required to support the creation of asynchronous
484 * file channels. When not overridden, the default implementation of this
485 * method throws {@code UnsupportedOperationException}.
486 *
487 * @param path
488 * the path of the file to open or create
489 * @param options
490 * options specifying how the file is opened
491 * @param executor
492 * the thread pool or {@code null} to associate the channel with
493 * the default thread pool
494 * @param attrs
495 * an optional list of file attributes to set atomically when
496 * creating the file
497 *
498 * @return a new asynchronous file channel
499 *
500 * @throws IllegalArgumentException
501 * If the set contains an invalid combination of options
502 * @throws UnsupportedOperationException
503 * If this provider that does not support creating asynchronous file
504 * channels, or an unsupported open option or file attribute is
505 * specified
506 * @throws IOException
507 * If an I/O error occurs
508 * @throws SecurityException
509 * In the case of the default file system, the {@link
510 * SecurityManager#checkRead(String)} method is invoked to check
511 * read access if the file is opened for reading. The {@link
512 * SecurityManager#checkWrite(String)} method is invoked to check
513 * write access if the file is opened for writing
514 */
515 public AsynchronousFileChannel newAsynchronousFileChannel(Path path,
516 Set<? extends OpenOption> options,
517 ExecutorService executor,
518 FileAttribute<?>... attrs)
519 throws IOException
520 {
521 throw new UnsupportedOperationException();
522 }
523
524 /**
525 * Opens or creates a file, returning a seekable byte channel to access the
526 * file. This method works in exactly the manner specified by the {@link
527 * Files#newByteChannel(Path,Set,FileAttribute[])} method.
528 *
529 * @param path
530 * the path to the file to open or create
531 * @param options
532 * options specifying how the file is opened
533 * @param attrs
534 * an optional list of file attributes to set atomically when
535 * creating the file
536 *
537 * @return a new seekable byte channel
538 *
539 * @throws IllegalArgumentException
540 * if the set contains an invalid combination of options
541 * @throws UnsupportedOperationException
542 * if an unsupported open option is specified or the array contains
543 * attributes that cannot be set atomically when creating the file
544 * @throws FileAlreadyExistsException
545 * if a file of that name already exists and the {@link
546 * StandardOpenOption#CREATE_NEW CREATE_NEW} option is specified
547 * <i>(optional specific exception)</i>
548 * @throws IOException
549 * if an I/O error occurs
550 * @throws SecurityException
551 * In the case of the default provider, and a security manager is
552 * installed, the {@link SecurityManager#checkRead(String) checkRead}
553 * method is invoked to check read access to the path if the file is
554 * opened for reading. The {@link SecurityManager#checkWrite(String)
555 * checkWrite} method is invoked to check write access to the path
556 * if the file is opened for writing. The {@link
557 * SecurityManager#checkDelete(String) checkDelete} method is
558 * invoked to check delete access if the file is opened with the
559 * {@code DELETE_ON_CLOSE} option.
560 */
561 public abstract SeekableByteChannel newByteChannel(Path path,
562 Set<? extends OpenOption> options, FileAttribute<?>... attrs) throws IOException;
563
564 /**
565 * Opens a directory, returning a {@code DirectoryStream} to iterate over
566 * the entries in the directory. This method works in exactly the manner
567 * specified by the {@link
568 * Files#newDirectoryStream(java.nio.file.Path, java.nio.file.DirectoryStream.Filter)}
569 * method.
570 *
571 * @param dir
572 * the path to the directory
573 * @param filter
574 * the directory stream filter
575 *
576 * @return a new and open {@code DirectoryStream} object
577 *
578 * @throws NotDirectoryException
579 * if the file could not otherwise be opened because it is not
580 * a directory <i>(optional specific exception)</i>
581 * @throws IOException
582 * if an I/O error occurs
583 * @throws SecurityException
584 * In the case of the default provider, and a security manager is
585 * installed, the {@link SecurityManager#checkRead(String) checkRead}
586 * method is invoked to check read access to the directory.
587 */
588 public abstract DirectoryStream<Path> newDirectoryStream(Path dir,
589 DirectoryStream.Filter<? super Path> filter) throws IOException;
590
591 /**
592 * Creates a new directory. This method works in exactly the manner
593 * specified by the {@link Files#createDirectory} method.
594 *
595 * @param dir
596 * the directory to create
597 * @param attrs
598 * an optional list of file attributes to set atomically when
599 * creating the directory
600 *
601 * @throws UnsupportedOperationException
602 * if the array contains an attribute that cannot be set atomically
603 * when creating the directory
604 * @throws FileAlreadyExistsException
605 * if a directory could not otherwise be created because a file of
606 * that name already exists <i>(optional specific exception)</i>
607 * @throws IOException
608 * if an I/O error occurs or the parent directory does not exist
609 * @throws SecurityException
610 * In the case of the default provider, and a security manager is
611 * installed, the {@link SecurityManager#checkWrite(String) checkWrite}
612 * method is invoked to check write access to the new directory.
613 */
614 public abstract void createDirectory(Path dir, FileAttribute<?>... attrs)
615 throws IOException;
616
617 /**
618 * Creates a symbolic link to a target. This method works in exactly the
619 * manner specified by the {@link Files#createSymbolicLink} method.
620 *
621 * <p> The default implementation of this method throws {@code
622 * UnsupportedOperationException}.
623 *
624 * @param link
625 * the path of the symbolic link to create
626 * @param target
627 * the target of the symbolic link
628 * @param attrs
629 * the array of attributes to set atomically when creating the
630 * symbolic link
631 *
632 * @throws UnsupportedOperationException
633 * if the implementation does not support symbolic links or the
634 * array contains an attribute that cannot be set atomically when
635 * creating the symbolic link
636 * @throws FileAlreadyExistsException
637 * if a file with the name already exists <i>(optional specific
638 * exception)</i>
639 * @throws IOException
640 * if an I/O error occurs
641 * @throws SecurityException
642 * In the case of the default provider, and a security manager
643 * is installed, it denies {@link LinkPermission}<tt>("symbolic")</tt>
644 * or its {@link SecurityManager#checkWrite(String) checkWrite}
645 * method denies write access to the path of the symbolic link.
646 */
647 public void createSymbolicLink(Path link, Path target, FileAttribute<?>... attrs)
648 throws IOException
649 {
650 throw new UnsupportedOperationException();
651 }
652
653 /**
654 * Creates a new link (directory entry) for an existing file. This method
655 * works in exactly the manner specified by the {@link Files#createLink}
656 * method.
657 *
658 * <p> The default implementation of this method throws {@code
659 * UnsupportedOperationException}.
660 *
661 * @param link
662 * the link (directory entry) to create
663 * @param existing
664 * a path to an existing file
665 *
666 * @throws UnsupportedOperationException
667 * if the implementation does not support adding an existing file
668 * to a directory
669 * @throws FileAlreadyExistsException
670 * if the entry could not otherwise be created because a file of
671 * that name already exists <i>(optional specific exception)</i>
672 * @throws IOException
673 * if an I/O error occurs
674 * @throws SecurityException
675 * In the case of the default provider, and a security manager
676 * is installed, it denies {@link LinkPermission}<tt>("hard")</tt>
677 * or its {@link SecurityManager#checkWrite(String) checkWrite}
678 * method denies write access to either the link or the
679 * existing file.
680 */
681 public void createLink(Path link, Path existing) throws IOException {
682 throw new UnsupportedOperationException();
683 }
684
685 /**
686 * Deletes a file. This method works in exactly the manner specified by the
687 * {@link Files#delete} method.
688 *
689 * @param path
690 * the path to the file to delete
691 *
692 * @throws NoSuchFileException
693 * if the file does not exist <i>(optional specific exception)</i>
694 * @throws DirectoryNotEmptyException
695 * if the file is a directory and could not otherwise be deleted
696 * because the directory is not empty <i>(optional specific
697 * exception)</i>
698 * @throws IOException
699 * if an I/O error occurs
700 * @throws SecurityException
701 * In the case of the default provider, and a security manager is
702 * installed, the {@link SecurityManager#checkDelete(String)} method
703 * is invoked to check delete access to the file
704 */
705 public abstract void delete(Path path) throws IOException;
706
707 /**
708 * Deletes a file if it exists. This method works in exactly the manner
709 * specified by the {@link Files#deleteIfExists} method.
710 *
711 * <p> The default implementation of this method simply invokes {@link
712 * #delete} ignoring the {@code NoSuchFileException} when the file does not
713 * exist. It may be overridden where appropriate.
714 *
715 * @param path
716 * the path to the file to delete
717 *
718 * @return {@code true} if the file was deleted by this method; {@code
719 * false} if the file could not be deleted because it did not
720 * exist
721 *
722 * @throws DirectoryNotEmptyException
723 * if the file is a directory and could not otherwise be deleted
724 * because the directory is not empty <i>(optional specific
725 * exception)</i>
726 * @throws IOException
727 * if an I/O error occurs
728 * @throws SecurityException
729 * In the case of the default provider, and a security manager is
730 * installed, the {@link SecurityManager#checkDelete(String)} method
731 * is invoked to check delete access to the file
732 */
733 public boolean deleteIfExists(Path path) throws IOException {
734 try {
735 delete(path);
736 return true;
737 } catch (NoSuchFileException ignore) {
738 return false;
739 }
740 }
741
742 /**
743 * Reads the target of a symbolic link. This method works in exactly the
744 * manner specified by the {@link Files#readSymbolicLink} method.
745 *
746 * <p> The default implementation of this method throws {@code
747 * UnsupportedOperationException}.
748 *
749 * @param link
750 * the path to the symbolic link
751 *
752 * @throws UnsupportedOperationException
753 * if the implementation does not support symbolic links
754 * @throws NotLinkException
755 * if the target could otherwise not be read because the file
756 * is not a symbolic link <i>(optional specific exception)</i>
757 * @throws IOException
758 * if an I/O error occurs
759 * @throws SecurityException
760 * In the case of the default provider, and a security manager
761 * is installed, it checks that {@code FilePermission} has been
762 * granted with the "{@code readlink}" action to read the link.
763 */
764 public Path readSymbolicLink(Path link) throws IOException {
765 throw new UnsupportedOperationException();
766 }
767
768 /**
769 * Copy a file to a target file. This method works in exactly the manner
770 * specified by the {@link Files#copy(Path,Path,CopyOption[])} method
771 * except that both the source and target paths must be associated with
772 * this provider.
773 *
774 * @param source
775 * the path to the file to copy
776 * @param target
777 * the path to the target file
778 * @param options
779 * options specifying how the copy should be done
780 *
781 * @throws UnsupportedOperationException
782 * if the array contains a copy option that is not supported
783 * @throws FileAlreadyExistsException
784 * if the target file exists but cannot be replaced because the
785 * {@code REPLACE_EXISTING} option is not specified <i>(optional
786 * specific exception)</i>
787 * @throws DirectoryNotEmptyException
788 * the {@code REPLACE_EXISTING} option is specified but the file
789 * cannot be replaced because it is a non-empty directory
790 * <i>(optional specific exception)</i>
791 * @throws IOException
792 * if an I/O error occurs
793 * @throws SecurityException
794 * In the case of the default provider, and a security manager is
795 * installed, the {@link SecurityManager#checkRead(String) checkRead}
796 * method is invoked to check read access to the source file, the
797 * {@link SecurityManager#checkWrite(String) checkWrite} is invoked
798 * to check write access to the target file. If a symbolic link is
799 * copied the security manager is invoked to check {@link
800 * LinkPermission}{@code ("symbolic")}.
801 */
802 public abstract void copy(Path source, Path target, CopyOption... options)
803 throws IOException;
804
805 /**
806 * Move or rename a file to a target file. This method works in exactly the
807 * manner specified by the {@link Files#move} method except that both the
808 * source and target paths must be associated with this provider.
809 *
810 * @param source
811 * the path to the file to move
812 * @param target
813 * the path to the target file
814 * @param options
815 * options specifying how the move should be done
816 *
817 * @throws UnsupportedOperationException
818 * if the array contains a copy option that is not supported
819 * @throws FileAlreadyExistsException
820 * if the target file exists but cannot be replaced because the
821 * {@code REPLACE_EXISTING} option is not specified <i>(optional
822 * specific exception)</i>
823 * @throws DirectoryNotEmptyException
824 * the {@code REPLACE_EXISTING} option is specified but the file
825 * cannot be replaced because it is a non-empty directory
826 * <i>(optional specific exception)</i>
827 * @throws AtomicMoveNotSupportedException
828 * if the options array contains the {@code ATOMIC_MOVE} option but
829 * the file cannot be moved as an atomic file system operation.
830 * @throws IOException
831 * if an I/O error occurs
832 * @throws SecurityException
833 * In the case of the default provider, and a security manager is
834 * installed, the {@link SecurityManager#checkWrite(String) checkWrite}
835 * method is invoked to check write access to both the source and
836 * target file.
837 */
838 public abstract void move(Path source, Path target, CopyOption... options)
839 throws IOException;
840
841 /**
842 * Tests if two paths locate the same file. This method works in exactly the
843 * manner specified by the {@link Files#isSameFile} method.
844 *
845 * @param path
846 * one path to the file
847 * @param path2
848 * the other path
849 *
850 * @return {@code true} if, and only if, the two paths locate the same file
851 *
852 * @throws IOException
853 * if an I/O error occurs
854 * @throws SecurityException
855 * In the case of the default provider, and a security manager is
856 * installed, the {@link SecurityManager#checkRead(String) checkRead}
857 * method is invoked to check read access to both files.
858 */
859 public abstract boolean isSameFile(Path path, Path path2)
860 throws IOException;
861
862 /**
863 * Tells whether or not a file is considered <em>hidden</em>. This method
864 * works in exactly the manner specified by the {@link Files#isHidden}
865 * method.
866 *
867 * <p> This method is invoked by the {@link Files#isHidden isHidden} method.
868 *
869 * @param path
870 * the path to the file to test
871 *
872 * @return {@code true} if the file is considered hidden
873 *
874 * @throws IOException
875 * if an I/O error occurs
876 * @throws SecurityException
877 * In the case of the default provider, and a security manager is
878 * installed, the {@link SecurityManager#checkRead(String) checkRead}
879 * method is invoked to check read access to the file.
880 */
881 public abstract boolean isHidden(Path path) throws IOException;
882
883 /**
884 * Returns the {@link FileStore} representing the file store where a file
885 * is located. This method works in exactly the manner specified by the
886 * {@link Files#getFileStore} method.
887 *
888 * @param path
889 * the path to the file
890 *
891 * @return the file store where the file is stored
892 *
893 * @throws IOException
894 * if an I/O error occurs
895 * @throws SecurityException
896 * In the case of the default provider, and a security manager is
897 * installed, the {@link SecurityManager#checkRead(String) checkRead}
898 * method is invoked to check read access to the file, and in
899 * addition it checks {@link RuntimePermission}<tt>
900 * ("getFileStoreAttributes")</tt>
901 */
902 public abstract FileStore getFileStore(Path path) throws IOException;
903
904 /**
905 * Checks the existence, and optionally the accessibility, of a file.
906 *
907 * <p> This method may be used by the {@link Files#isReadable isReadable},
908 * {@link Files#isWritable isWritable} and {@link Files#isExecutable
909 * isExecutable} methods to check the accessibility of a file.
910 *
911 * <p> This method checks the existence of a file and that this Java virtual
912 * machine has appropriate privileges that would allow it access the file
913 * according to all of access modes specified in the {@code modes} parameter
914 * as follows:
915 *
916 * <table border=1 cellpadding=5 summary="">
917 * <tr> <th>Value</th> <th>Description</th> </tr>
918 * <tr>
919 * <td> {@link AccessMode#READ READ} </td>
920 * <td> Checks that the file exists and that the Java virtual machine has
921 * permission to read the file. </td>
922 * </tr>
923 * <tr>
924 * <td> {@link AccessMode#WRITE WRITE} </td>
925 * <td> Checks that the file exists and that the Java virtual machine has
926 * permission to write to the file, </td>
927 * </tr>
928 * <tr>
929 * <td> {@link AccessMode#EXECUTE EXECUTE} </td>
930 * <td> Checks that the file exists and that the Java virtual machine has
931 * permission to {@link Runtime#exec execute} the file. The semantics
932 * may differ when checking access to a directory. For example, on UNIX
933 * systems, checking for {@code EXECUTE} access checks that the Java
934 * virtual machine has permission to search the directory in order to
935 * access file or subdirectories. </td>
936 * </tr>
937 * </table>
938 *
939 * <p> If the {@code modes} parameter is of length zero, then the existence
940 * of the file is checked.
941 *
942 * <p> This method follows symbolic links if the file referenced by this
943 * object is a symbolic link. Depending on the implementation, this method
944 * may require to read file permissions, access control lists, or other
945 * file attributes in order to check the effective access to the file. To
946 * determine the effective access to a file may require access to several
947 * attributes and so in some implementations this method may not be atomic
948 * with respect to other file system operations.
949 *
950 * @param path
951 * the path to the file to check
952 * @param modes
953 * The access modes to check; may have zero elements
954 *
955 * @throws UnsupportedOperationException
956 * an implementation is required to support checking for
957 * {@code READ}, {@code WRITE}, and {@code EXECUTE} access. This
958 * exception is specified to allow for the {@code Access} enum to
959 * be extended in future releases.
960 * @throws NoSuchFileException
961 * if a file does not exist <i>(optional specific exception)</i>
962 * @throws AccessDeniedException
963 * the requested access would be denied or the access cannot be
964 * determined because the Java virtual machine has insufficient
965 * privileges or other reasons. <i>(optional specific exception)</i>
966 * @throws IOException
967 * if an I/O error occurs
968 * @throws SecurityException
969 * In the case of the default provider, and a security manager is
970 * installed, the {@link SecurityManager#checkRead(String) checkRead}
971 * is invoked when checking read access to the file or only the
972 * existence of the file, the {@link SecurityManager#checkWrite(String)
973 * checkWrite} is invoked when checking write access to the file,
974 * and {@link SecurityManager#checkExec(String) checkExec} is invoked
975 * when checking execute access.
976 */
977 public abstract void checkAccess(Path path, AccessMode... modes)
978 throws IOException;
979
980 /**
981 * Returns a file attribute view of a given type. This method works in
982 * exactly the manner specified by the {@link Files#getFileAttributeView}
983 * method.
984 *
985 * @param path
986 * the path to the file
987 * @param type
988 * the {@code Class} object corresponding to the file attribute view
989 * @param options
990 * options indicating how symbolic links are handled
991 *
992 * @return a file attribute view of the specified type, or {@code null} if
993 * the attribute view type is not available
994 */
995 public abstract <V extends FileAttributeView> V
996 getFileAttributeView(Path path, Class<V> type, LinkOption... options);
997
998 /**
999 * Reads a file's attributes as a bulk operation. This method works in
1000 * exactly the manner specified by the {@link
1001 * Files#readAttributes(Path,Class,LinkOption[])} method.
1002 *
1003 * @param path
1004 * the path to the file
1005 * @param type
1006 * the {@code Class} of the file attributes required
1007 * to read
1008 * @param options
1009 * options indicating how symbolic links are handled
1010 *
1011 * @return the file attributes
1012 *
1013 * @throws UnsupportedOperationException
1014 * if an attributes of the given type are not supported
1015 * @throws IOException
1016 * if an I/O error occurs
1017 * @throws SecurityException
1018 * In the case of the default provider, a security manager is
1019 * installed, its {@link SecurityManager#checkRead(String) checkRead}
1020 * method is invoked to check read access to the file
1021 */
1022 public abstract <A extends BasicFileAttributes> A
1023 readAttributes(Path path, Class<A> type, LinkOption... options) throws IOException;
1024
1025 /**
1026 * Reads a set of file attributes as a bulk operation. This method works in
1027 * exactly the manner specified by the {@link
1028 * Files#readAttributes(Path,String,LinkOption[])} method.
1029 *
1030 * @param path
1031 * the path to the file
1032 * @param attributes
1033 * the attributes to read
1034 * @param options
1035 * options indicating how symbolic links are handled
1036 *
1037 * @return a map of the attributes returned; may be empty. The map's keys
1038 * are the attribute names, its values are the attribute values
1039 *
1040 * @throws UnsupportedOperationException
1041 * if the attribute view is not available
1042 * @throws IllegalArgumentException
1043 * if no attributes are specified or an unrecognized attributes is
1044 * specified
1045 * @throws IOException
1046 * If an I/O error occurs
1047 * @throws SecurityException
1048 * In the case of the default provider, and a security manager is
1049 * installed, its {@link SecurityManager#checkRead(String) checkRead}
1050 * method denies read access to the file. If this method is invoked
1051 * to read security sensitive attributes then the security manager
1052 * may be invoke to check for additional permissions.
1053 */
1054 public abstract Map<String,Object> readAttributes(Path path, String attributes,
1055 LinkOption... options)
1056 throws IOException;
1057
1058 /**
1059 * Sets the value of a file attribute. This method works in exactly the
1060 * manner specified by the {@link Files#setAttribute} method.
1061 *
1062 * @param path
1063 * the path to the file
1064 * @param attribute
1065 * the attribute to set
1066 * @param value
1067 * the attribute value
1068 * @param options
1069 * options indicating how symbolic links are handled
1070 *
1071 * @throws UnsupportedOperationException
1072 * if the attribute view is not available
1073 * @throws IllegalArgumentException
1074 * if the attribute name is not specified, or is not recognized, or
1075 * the attribute value is of the correct type but has an
1076 * inappropriate value
1077 * @throws ClassCastException
1078 * If the attribute value is not of the expected type or is a
1079 * collection containing elements that are not of the expected
1080 * type
1081 * @throws IOException
1082 * If an I/O error occurs
1083 * @throws SecurityException
1084 * In the case of the default provider, and a security manager is
1085 * installed, its {@link SecurityManager#checkWrite(String) checkWrite}
1086 * method denies write access to the file. If this method is invoked
1087 * to set security sensitive attributes then the security manager
1088 * may be invoked to check for additional permissions.
1089 */
1090 public abstract void setAttribute(Path path, String attribute,
1091 Object value, LinkOption... options)
1092 throws IOException;
1093 }