Showing the changes to java/pkg/java/nio/file/FileSystem.java (1 of 18352 files). Show all
Unified · Split
| @@ -0,0 +1,469 @@ | |||
| 1 | /* | ||
| 2 | * Copyright (c) 2007, 2011, Oracle and/or its affiliates. All rights reserved. | ||
| 3 | * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. | ||
| 4 | * | ||
| 5 | * This code is free software; you can redistribute it and/or modify it | ||
| 6 | * under the terms of the GNU General Public License version 2 only, as | ||
| 7 | * published by the Free Software Foundation. Oracle designates this | ||
| 8 | * particular file as subject to the "Classpath" exception as provided | ||
| 9 | * by Oracle in the LICENSE file that accompanied this code. | ||
| 10 | * | ||
| 11 | * This code is distributed in the hope that it will be useful, but WITHOUT | ||
| 12 | * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or | ||
| 13 | * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License | ||
| 14 | * version 2 for more details (a copy is included in the LICENSE file that | ||
| 15 | * accompanied this code). | ||
| 16 | * | ||
| 17 | * You should have received a copy of the GNU General Public License version | ||
| 18 | * 2 along with this work; if not, write to the Free Software Foundation, | ||
| 19 | * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. | ||
| 20 | * | ||
| 21 | * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA | ||
| 22 | * or visit www.oracle.com if you need additional information or have any | ||
| 23 | * questions. | ||
| 24 | */ | ||
| 25 | |||
| 26 | package java.nio.file; | ||
| 27 | |||
| 28 | import java.nio.file.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 | */ | ||
| 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 | */ | ||
| 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 | ||
| 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 | */ | ||
| 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 | */ | ||
| 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 | */ | ||
| 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 | */ | ||
| 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 | */ | ||
| 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 | */ | ||
| 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 | */ | ||
| 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"> | ||
| 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 | * <tr> | ||
| 329 | * <td>{@code *.{java,class}}</td> | ||
| 330 | * <td>Matches file names ending with {@code .java} or {@code .class}</td> | ||
| 331 | * </tr> | ||
| 332 | * <tr> | ||
| 333 | * <td>{@code foo.?}</td> | ||
| 334 | * <td>Matches file names starting with {@code foo.} and a single | ||
| 335 | * character extension</td> | ||
| 336 | * </tr> | ||
| 337 | * <tr> | ||
| 338 | * <td><tt>/home/*/*</tt> | ||
| 339 | * <td>Matches <tt>/home/gus/data</tt> on UNIX platforms</td> | ||
| 340 | * </tr> | ||
| 341 | * <tr> | ||
| 342 | * <td><tt>/home/**</tt> | ||
| 343 | * <td>Matches <tt>/home/gus</tt> and | ||
| 344 | * <tt>/home/gus/data</tt> on UNIX platforms</td> | ||
| 345 | * </tr> | ||
| 346 | * <tr> | ||
| 347 | * <td><tt>C:\\*</tt> | ||
| 348 | * <td>Matches <tt>C:\foo</tt> and <tt>C:\bar</tt> on the Windows | ||
| 349 | * platform (note that the backslash is escaped; as a string literal in the | ||
| 350 | * Java Language the pattern would be <tt>"C:\\\\*"</tt>) </td> | ||
| 351 | * </tr> | ||
| 352 | * | ||
| 353 | * </table> | ||
| 354 | * </blockquote> | ||
| 355 | * | ||
| 356 | * <p> The following rules are used to interpret glob patterns: | ||
| 357 | * | ||
| 358 | * <p> <ul> | ||
| 359 | * <li><p> The {@code *} character matches zero or more {@link Character | ||
| 360 | * characters} of a {@link Path#getName(int) name} component without | ||
| 361 | * crossing directory boundaries. </p></li> | ||
| 362 | * | ||
| 363 | * <li><p> The {@code **} characters matches zero or more {@link Character | ||
| 364 | * characters} crossing directory boundaries. </p></li> | ||
| 365 | * | ||
| 366 | * <li><p> The {@code ?} character matches exactly one character of a | ||
| 367 | * name component.</p></li> | ||
| 368 | * | ||
| 369 | * <li><p> The backslash character ({@code \}) is used to escape characters | ||
| 370 | * that would otherwise be interpreted as special characters. The expression | ||
| 371 | * {@code \\} matches a single backslash and "\{" matches a left brace | ||
| 372 | * for example. </p></li> | ||
| 373 | * | ||
| 374 | * <li><p> The {@code [ ]} characters are a <i>bracket expression</i> that | ||
| 375 | * match a single character of a name component out of a set of characters. | ||
| 376 | * For example, {@code [abc]} matches {@code "a"}, {@code "b"}, or {@code "c"}. | ||
| 377 | * The hyphen ({@code -}) may be used to specify a range so {@code [a-z]} | ||
| 378 | * specifies a range that matches from {@code "a"} to {@code "z"} (inclusive). | ||
| 379 | * These forms can be mixed so [abce-g] matches {@code "a"}, {@code "b"}, | ||
| 380 | * {@code "c"}, {@code "e"}, {@code "f"} or {@code "g"}. If the character | ||
| 381 | * after the {@code [} is a {@code !} then it is used for negation so {@code | ||
| 382 | * [!a-c]} matches any character except {@code "a"}, {@code "b"}, or {@code | ||
| 383 | * "c"}. | ||
| 384 | * <p> Within a bracket expression the {@code *}, {@code ?} and {@code \} | ||
| 385 | * characters match themselves. The ({@code -}) character matches itself if | ||
| 386 | * it is the first character within the brackets, or the first character | ||
| 387 | * after the {@code !} if negating.</p></li> | ||
| 388 | * | ||
| 389 | * <li><p> The {@code { }} characters are a group of subpatterns, where | ||
| 390 | * the group matches if any subpattern in the group matches. The {@code ","} | ||
| 391 | * character is used to separate the subpatterns. Groups cannot be nested. | ||
| 392 | * </p></li> | ||
| 393 | * | ||
| 394 | * <li><p> Leading period<tt>/</tt>dot characters in file name are | ||
| 395 | * treated as regular characters in match operations. For example, | ||
| 396 | * the {@code "*"} glob pattern matches file name {@code ".login"}. | ||
| 397 | * The {@link Files#isHidden} method may be used to test whether a file | ||
| 398 | * is considered hidden. | ||
| 399 | * </p></li> | ||
| 400 | * | ||
| 401 | * <li><p> All other characters match themselves in an implementation | ||
| 402 | * dependent manner. This includes characters representing any {@link | ||
| 403 | * FileSystem#getSeparator name-separators}. </p></li> | ||
| 404 | * | ||
| 405 | * <li><p> The matching of {@link Path#getRoot root} components is highly | ||
| 406 | * implementation-dependent and is not specified. </p></li> | ||
| 407 | * | ||
| 408 | * </ul> | ||
| 409 | * | ||
| 410 | * <p> When the syntax is "{@code regex}" then the pattern component is a | ||
| 411 | * regular expression as defined by the {@link java.util.regex.Pattern} | ||
| 412 | * class. | ||
| 413 | * | ||
| 414 | * <p> For both the glob and regex syntaxes, the matching details, such as | ||
| 415 | * whether the matching is case sensitive, are implementation-dependent | ||
| 416 | * and therefore not specified. | ||
| 417 | * | ||
| 418 | * @param syntaxAndPattern | ||
| 419 | * The syntax and pattern | ||
| 420 | * | ||
| 421 | * @return A path matcher that may be used to match paths against the pattern | ||
| 422 | * | ||
| 423 | * @throws IllegalArgumentException | ||
| 424 | * If the parameter does not take the form: {@code syntax:pattern} | ||
| 425 | * @throws java.util.regex.PatternSyntaxException | ||
| 426 | * If the pattern is invalid | ||
| 427 | * @throws UnsupportedOperationException | ||
| 428 | * If the pattern syntax is not known to the implementation | ||
| 429 | * | ||
| 430 | * @see Files#newDirectoryStream(Path,String) | ||
| 431 | */ | ||
| 432 | public abstract PathMatcher getPathMatcher(String syntaxAndPattern); | ||
| 433 | |||
| 434 | /** | ||
| 435 | * Returns the {@code UserPrincipalLookupService} for this file system | ||
| 436 | * <i>(optional operation)</i>. The resulting lookup service may be used to | ||
| 437 | * lookup user or group names. | ||
| 438 | * | ||
| 439 | * <p> <b>Usage Example:</b> | ||
| 440 | * Suppose we want to make "joe" the owner of a file: | ||
| 441 | * <pre> | ||
| 442 | * UserPrincipalLookupService lookupService = FileSystems.getDefault().getUserPrincipalLookupService(); | ||
| 443 | * Files.setOwner(path, lookupService.lookupPrincipalByName("joe")); | ||
| 444 | * </pre> | ||
| 445 | * | ||
| 446 | * @throws UnsupportedOperationException | ||
| 447 | * If this {@code FileSystem} does not does have a lookup service | ||
| 448 | * | ||
| 449 | * @return The {@code UserPrincipalLookupService} for this file system | ||
| 450 | */ | ||
| 451 | public abstract UserPrincipalLookupService getUserPrincipalLookupService(); | ||
| 452 | |||
| 453 | /** | ||
| 454 | * Constructs a new {@link WatchService} <i>(optional operation)</i>. | ||
| 455 | * | ||
| 456 | * <p> This method constructs a new watch service that may be used to watch | ||
| 457 | * registered objects for changes and events. | ||
| 458 | * | ||
| 459 | * @return a new watch service | ||
| 460 | * | ||
| 461 | * @throws UnsupportedOperationException | ||
| 462 | * If this {@code FileSystem} does not support watching file system | ||
| 463 | * objects for changes and events. This exception is not thrown | ||
| 464 | * by {@code FileSystems} created by the default provider. | ||
| 465 | * @throws IOException | ||
| 466 | * If an I/O error occurs | ||
| 467 | */ | ||
| 468 | public abstract WatchService newWatchService() throws IOException; | ||
| 469 | } | ||