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