1 /* 2 * Copyright (c) 2007, 2013, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 26 package java.nio.file; 27 28 import java.nio.file.attribute.*; 29 import java.nio.file.spi.FileSystemProvider; 30 import java.util.Set; 31 import java.io.Closeable; 32 import java.io.IOException; 33 34 /** 35 * Provides an interface to a file system and is the factory for objects to 36 * access files and other objects in the file system. 37 * 38 * <p> The default file system, obtained by invoking the {@link FileSystems#getDefault 39 * FileSystems.getDefault} method, provides access to the file system that is 40 * accessible to the Java virtual machine. The {@link FileSystems} class defines 41 * methods to create file systems that provide access to other types of (custom) 42 * file systems. 43 * 44 * <p> A file system is the factory for several types of objects: 45 * 46 * <ul> 47 * <li><p> The {@link #getPath getPath} method converts a system dependent 48 * <em>path string</em>, returning a {@link Path} object that may be used 49 * to locate and access a file. </p></li> 50 * <li><p> The {@link #getPathMatcher getPathMatcher} method is used 51 * to create a {@link PathMatcher} that performs match operations on 52 * paths. </p></li> 53 * <li><p> The {@link #getFileStores getFileStores} method returns an iterator 54 * over the underlying {@link FileStore file-stores}. </p></li> 55 * <li><p> The {@link #getUserPrincipalLookupService getUserPrincipalLookupService} 56 * method returns the {@link UserPrincipalLookupService} to lookup users or 57 * groups by name. </p></li> 58 * <li><p> The {@link #newWatchService newWatchService} method creates a 59 * {@link WatchService} that may be used to watch objects for changes and 60 * events. </p></li> 61 * </ul> 62 * 63 * <p> File systems vary greatly. In some cases the file system is a single 64 * hierarchy of files with one top-level root directory. In other cases it may 65 * have several distinct file hierarchies, each with its own top-level root 66 * directory. The {@link #getRootDirectories getRootDirectories} method may be 67 * used to iterate over the root directories in the file system. A file system 68 * is typically composed of one or more underlying {@link FileStore file-stores} 69 * that provide the storage for the files. Theses file stores can also vary in 70 * the features they support, and the file attributes or <em>meta-data</em> that 71 * they associate with files. 72 * 73 * <p> A file system is open upon creation and can be closed by invoking its 74 * {@link #close() close} method. Once closed, any further attempt to access 75 * objects in the file system cause {@link ClosedFileSystemException} to be 76 * thrown. File systems created by the default {@link FileSystemProvider provider} 77 * cannot be closed. 78 * 79 * <p> A {@code FileSystem} can provide read-only or read-write access to the 80 * file system. Whether or not a file system provides read-only access is 81 * established when the {@code FileSystem} is created and can be tested by invoking 82 * its {@link #isReadOnly() isReadOnly} method. Attempts to write to file stores 83 * by means of an object associated with a read-only file system throws {@link 84 * ReadOnlyFileSystemException}. 85 * 86 * <p> File systems are safe for use by multiple concurrent threads. The {@link 87 * #close close} method may be invoked at any time to close a file system but 88 * whether a file system is <i>asynchronously closeable</i> is provider specific 89 * and therefore unspecified. In other words, if a thread is accessing an 90 * object in a file system, and another thread invokes the {@code close} method 91 * then it may require to block until the first operation is complete. Closing 92 * a file system causes all open channels, watch services, and other {@link 93 * Closeable closeable} objects associated with the file system to be closed. 94 * 95 * @since 1.7 96 */ 97 98 public abstract class FileSystem 99 implements Closeable 100 { 101 /** 102 * Initializes a new instance of this class. 103 */ FileSystem()104 protected FileSystem() { 105 } 106 107 /** 108 * Returns the provider that created this file system. 109 * 110 * @return The provider that created this file system. 111 */ provider()112 public abstract FileSystemProvider provider(); 113 114 /** 115 * Closes this file system. 116 * 117 * <p> After a file system is closed then all subsequent access to the file 118 * system, either by methods defined by this class or on objects associated 119 * with this file system, throw {@link ClosedFileSystemException}. If the 120 * file system is already closed then invoking this method has no effect. 121 * 122 * <p> Closing a file system will close all open {@link 123 * java.nio.channels.Channel channels}, {@link DirectoryStream directory-streams}, 124 * {@link WatchService watch-service}, and other closeable objects associated 125 * with this file system. The {@link FileSystems#getDefault default} file 126 * system cannot be closed. 127 * 128 * @throws IOException 129 * If an I/O error occurs 130 * @throws UnsupportedOperationException 131 * Thrown in the case of the default file system 132 */ 133 @Override close()134 public abstract void close() throws IOException; 135 136 /** 137 * Tells whether or not this file system is open. 138 * 139 * <p> File systems created by the default provider are always open. 140 * 141 * @return {@code true} if, and only if, this file system is open 142 */ isOpen()143 public abstract boolean isOpen(); 144 145 /** 146 * Tells whether or not this file system allows only read-only access to 147 * its file stores. 148 * 149 * @return {@code true} if, and only if, this file system provides 150 * read-only access 151 */ isReadOnly()152 public abstract boolean isReadOnly(); 153 154 /** 155 * Returns the name separator, represented as a string. 156 * 157 * <p> The name separator is used to separate names in a path string. An 158 * implementation may support multiple name separators in which case this 159 * method returns an implementation specific <em>default</em> name separator. 160 * This separator is used when creating path strings by invoking the {@link 161 * Path#toString() toString()} method. 162 * 163 * <p> In the case of the default provider, this method returns the same 164 * separator as {@link java.io.File#separator}. 165 * 166 * @return The name separator 167 */ getSeparator()168 public abstract String getSeparator(); 169 170 /** 171 * Returns an object to iterate over the paths of the root directories. 172 * 173 * <p> A file system provides access to a file store that may be composed 174 * of a number of distinct file hierarchies, each with its own top-level 175 * root directory. Unless denied by the security manager, each element in 176 * the returned iterator corresponds to the root directory of a distinct 177 * file hierarchy. The order of the elements is not defined. The file 178 * hierarchies may change during the lifetime of the Java virtual machine. 179 * For example, in some implementations, the insertion of removable media 180 * may result in the creation of a new file hierarchy with its own 181 * top-level directory. 182 * 183 * <p> When a security manager is installed, it is invoked to check access 184 * to the each root directory. If denied, the root directory is not returned 185 * by the iterator. In the case of the default provider, the {@link 186 * SecurityManager#checkRead(String)} method is invoked to check read access 187 * to each root directory. It is system dependent if the permission checks 188 * are done when the iterator is obtained or during iteration. 189 * 190 * @return An object to iterate over the root directories 191 */ getRootDirectories()192 public abstract Iterable<Path> getRootDirectories(); 193 194 /** 195 * Returns an object to iterate over the underlying file stores. 196 * 197 * <p> The elements of the returned iterator are the {@link 198 * FileStore FileStores} for this file system. The order of the elements is 199 * not defined and the file stores may change during the lifetime of the 200 * Java virtual machine. When an I/O error occurs, perhaps because a file 201 * store is not accessible, then it is not returned by the iterator. 202 * 203 * <p> In the case of the default provider, and a security manager is 204 * installed, the security manager is invoked to check {@link 205 * RuntimePermission}<tt>("getFileStoreAttributes")</tt>. If denied, then 206 * no file stores are returned by the iterator. In addition, the security 207 * manager's {@link SecurityManager#checkRead(String)} method is invoked to 208 * check read access to the file store's <em>top-most</em> directory. If 209 * denied, the file store is not returned by the iterator. It is system 210 * dependent if the permission checks are done when the iterator is obtained 211 * or during iteration. 212 * 213 * <p> <b>Usage Example:</b> 214 * Suppose we want to print the space usage for all file stores: 215 * <pre> 216 * for (FileStore store: FileSystems.getDefault().getFileStores()) { 217 * long total = store.getTotalSpace() / 1024; 218 * long used = (store.getTotalSpace() - store.getUnallocatedSpace()) / 1024; 219 * long avail = store.getUsableSpace() / 1024; 220 * System.out.format("%-20s %12d %12d %12d%n", store, total, used, avail); 221 * } 222 * </pre> 223 * 224 * @return An object to iterate over the backing file stores 225 */ getFileStores()226 public abstract Iterable<FileStore> getFileStores(); 227 228 /** 229 * Returns the set of the {@link FileAttributeView#name names} of the file 230 * attribute views supported by this {@code FileSystem}. 231 * 232 * <p> The {@link BasicFileAttributeView} is required to be supported and 233 * therefore the set contains at least one element, "basic". 234 * 235 * <p> The {@link FileStore#supportsFileAttributeView(String) 236 * supportsFileAttributeView(String)} method may be used to test if an 237 * underlying {@link FileStore} supports the file attributes identified by a 238 * file attribute view. 239 * 240 * @return An unmodifiable set of the names of the supported file attribute 241 * views 242 */ supportedFileAttributeViews()243 public abstract Set<String> supportedFileAttributeViews(); 244 245 /** 246 * Converts a path string, or a sequence of strings that when joined form 247 * a path string, to a {@code Path}. If {@code more} does not specify any 248 * elements then the value of the {@code first} parameter is the path string 249 * to convert. If {@code more} specifies one or more elements then each 250 * non-empty string, including {@code first}, is considered to be a sequence 251 * of name elements (see {@link Path}) and is joined to form a path string. 252 * The details as to how the Strings are joined is provider specific but 253 * typically they will be joined using the {@link #getSeparator 254 * name-separator} as the separator. For example, if the name separator is 255 * "{@code /}" and {@code getPath("/foo","bar","gus")} is invoked, then the 256 * path string {@code "/foo/bar/gus"} is converted to a {@code Path}. 257 * A {@code Path} representing an empty path is returned if {@code first} 258 * is the empty string and {@code more} does not contain any non-empty 259 * strings. 260 * 261 * <p> The parsing and conversion to a path object is inherently 262 * implementation dependent. In the simplest case, the path string is rejected, 263 * and {@link InvalidPathException} thrown, if the path string contains 264 * characters that cannot be converted to characters that are <em>legal</em> 265 * to the file store. For example, on UNIX systems, the NUL (\u0000) 266 * character is not allowed to be present in a path. An implementation may 267 * choose to reject path strings that contain names that are longer than those 268 * allowed by any file store, and where an implementation supports a complex 269 * path syntax, it may choose to reject path strings that are <em>badly 270 * formed</em>. 271 * 272 * <p> In the case of the default provider, path strings are parsed based 273 * on the definition of paths at the platform or virtual file system level. 274 * For example, an operating system may not allow specific characters to be 275 * present in a file name, but a specific underlying file store may impose 276 * different or additional restrictions on the set of legal 277 * characters. 278 * 279 * <p> This method throws {@link InvalidPathException} when the path string 280 * cannot be converted to a path. Where possible, and where applicable, 281 * the exception is created with an {@link InvalidPathException#getIndex 282 * index} value indicating the first position in the {@code path} parameter 283 * that caused the path string to be rejected. 284 * 285 * @param first 286 * the path string or initial part of the path string 287 * @param more 288 * additional strings to be joined to form the path string 289 * 290 * @return the resulting {@code Path} 291 * 292 * @throws InvalidPathException 293 * If the path string cannot be converted 294 */ getPath(String first, String... more)295 public abstract Path getPath(String first, String... more); 296 297 /** 298 * Returns a {@code PathMatcher} that performs match operations on the 299 * {@code String} representation of {@link Path} objects by interpreting a 300 * given pattern. 301 * 302 * The {@code syntaxAndPattern} parameter identifies the syntax and the 303 * pattern and takes the form: 304 * <blockquote><pre> 305 * <i>syntax</i><b>:</b><i>pattern</i> 306 * </pre></blockquote> 307 * where {@code ':'} stands for itself. 308 * 309 * <p> A {@code FileSystem} implementation supports the "{@code glob}" and 310 * "{@code regex}" syntaxes, and may support others. The value of the syntax 311 * component is compared without regard to case. 312 * 313 * <p> When the syntax is "{@code glob}" then the {@code String} 314 * representation of the path is matched using a limited pattern language 315 * that resembles regular expressions but with a simpler syntax. For example: 316 * 317 * <blockquote> 318 * <table border="0" summary="Pattern Language"> 319 * <tr> 320 * <td>{@code *.java}</td> 321 * <td>Matches a path that represents a file name ending in {@code .java}</td> 322 * </tr> 323 * <tr> 324 * <td>{@code *.*}</td> 325 * <td>Matches file names containing a dot</td> 326 * </tr> 327 * <tr> 328 * <td>{@code *.{java,class}}</td> 329 * <td>Matches file names ending with {@code .java} or {@code .class}</td> 330 * </tr> 331 * <tr> 332 * <td>{@code foo.?}</td> 333 * <td>Matches file names starting with {@code foo.} and a single 334 * character extension</td> 335 * </tr> 336 * <tr> 337 * <td><tt>/home/*/*</tt> 338 * <td>Matches <tt>/home/gus/data</tt></td> 339 * </tr> 340 * <tr> 341 * <td><tt>/home/**</tt> 342 * <td>Matches <tt>/home/gus</tt> and 343 * <tt>/home/gus/data</tt></td> 344 * </tr> 345 * 346 * </table> 347 * </blockquote> 348 * 349 * <p> The following rules are used to interpret glob patterns: 350 * 351 * <ul> 352 * <li><p> The {@code *} character matches zero or more {@link Character 353 * characters} of a {@link Path#getName(int) name} component without 354 * crossing directory boundaries. </p></li> 355 * 356 * <li><p> The {@code **} characters matches zero or more {@link Character 357 * characters} crossing directory boundaries. </p></li> 358 * 359 * <li><p> The {@code ?} character matches exactly one character of a 360 * name component.</p></li> 361 * 362 * <li><p> The backslash character ({@code \}) is used to escape characters 363 * that would otherwise be interpreted as special characters. The expression 364 * {@code \\} matches a single backslash and "\{" matches a left brace 365 * for example. </p></li> 366 * 367 * <li><p> The {@code [ ]} characters are a <i>bracket expression</i> that 368 * match a single character of a name component out of a set of characters. 369 * For example, {@code [abc]} matches {@code "a"}, {@code "b"}, or {@code "c"}. 370 * The hyphen ({@code -}) may be used to specify a range so {@code [a-z]} 371 * specifies a range that matches from {@code "a"} to {@code "z"} (inclusive). 372 * These forms can be mixed so [abce-g] matches {@code "a"}, {@code "b"}, 373 * {@code "c"}, {@code "e"}, {@code "f"} or {@code "g"}. If the character 374 * after the {@code [} is a {@code !} then it is used for negation so {@code 375 * [!a-c]} matches any character except {@code "a"}, {@code "b"}, or {@code 376 * "c"}. 377 * <p> Within a bracket expression the {@code *}, {@code ?} and {@code \} 378 * characters match themselves. The ({@code -}) character matches itself if 379 * it is the first character within the brackets, or the first character 380 * after the {@code !} if negating.</p></li> 381 * 382 * <li><p> The {@code { }} characters are a group of subpatterns, where 383 * the group matches if any subpattern in the group matches. The {@code ","} 384 * character is used to separate the subpatterns. Groups cannot be nested. 385 * </p></li> 386 * 387 * <li><p> Leading period<tt>/</tt>dot characters in file name are 388 * treated as regular characters in match operations. For example, 389 * the {@code "*"} glob pattern matches file name {@code ".login"}. 390 * The {@link Files#isHidden} method may be used to test whether a file 391 * is considered hidden. 392 * </p></li> 393 * 394 * <li><p> All other characters match themselves in an implementation 395 * dependent manner. This includes characters representing any {@link 396 * FileSystem#getSeparator name-separators}. </p></li> 397 * 398 * <li><p> The matching of {@link Path#getRoot root} components is highly 399 * implementation-dependent and is not specified. </p></li> 400 * 401 * </ul> 402 * 403 * <p> When the syntax is "{@code regex}" then the pattern component is a 404 * regular expression as defined by the {@link java.util.regex.Pattern} 405 * class. 406 * 407 * <p> For both the glob and regex syntaxes, the matching details, such as 408 * whether the matching is case sensitive, are implementation-dependent 409 * and therefore not specified. 410 * 411 * @param syntaxAndPattern 412 * The syntax and pattern 413 * 414 * @return A path matcher that may be used to match paths against the pattern 415 * 416 * @throws IllegalArgumentException 417 * If the parameter does not take the form: {@code syntax:pattern} 418 * @throws java.util.regex.PatternSyntaxException 419 * If the pattern is invalid 420 * @throws UnsupportedOperationException 421 * If the pattern syntax is not known to the implementation 422 * 423 * @see Files#newDirectoryStream(Path,String) 424 */ getPathMatcher(String syntaxAndPattern)425 public abstract PathMatcher getPathMatcher(String syntaxAndPattern); 426 427 /** 428 * Returns the {@code UserPrincipalLookupService} for this file system 429 * <i>(optional operation)</i>. The resulting lookup service may be used to 430 * lookup user or group names. 431 * 432 * <p> <b>Usage Example:</b> 433 * Suppose we want to make "joe" the owner of a file: 434 * <pre> 435 * UserPrincipalLookupService lookupService = FileSystems.getDefault().getUserPrincipalLookupService(); 436 * Files.setOwner(path, lookupService.lookupPrincipalByName("joe")); 437 * </pre> 438 * 439 * @throws UnsupportedOperationException 440 * If this {@code FileSystem} does not does have a lookup service 441 * 442 * @return The {@code UserPrincipalLookupService} for this file system 443 */ getUserPrincipalLookupService()444 public abstract UserPrincipalLookupService getUserPrincipalLookupService(); 445 446 /** 447 * Constructs a new {@link WatchService} <i>(optional operation)</i>. 448 * 449 * <p> This method constructs a new watch service that may be used to watch 450 * registered objects for changes and events. 451 * 452 * @return a new watch service 453 * 454 * @throws UnsupportedOperationException 455 * If this {@code FileSystem} does not support watching file system 456 * objects for changes and events. This exception is not thrown 457 * by {@code FileSystems} created by the default provider. 458 * @throws IOException 459 * If an I/O error occurs 460 */ newWatchService()461 public abstract WatchService newWatchService() throws IOException; 462 } 463