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 file
42 * 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 *
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 * FileStoreSpaceAttributes attrs = Attributes.readFileStoreSpaceAttributes(store);
218 * long total = attrs.totalSpace() / 1024;
219 * long used = (attrs.totalSpace() - attrs.unallocatedSpace()) / 1024;
220 * long avail = attrs.usableSpace() / 1024;
221 * System.out.format("%-20s %12d %12d %12d%n", store, total, used, avail);
222 * }
223 * </pre>
224 *
225 * @return An object to iterate over the backing file stores
226 */
227 public abstract Iterable<FileStore> getFileStores();
228
229 /**
230 * Returns the set of the {@link FileAttributeView#name names} of the file
231 * attribute views supported by this {@code FileSystem}.
232 *
233 * <p> The {@link BasicFileAttributeView} is required to be supported and
234 * therefore the set contains at least one element, "basic".
235 *
236 * <p> The {@link FileStore#supportsFileAttributeView(String)
237 * supportsFileAttributeView(String)} method may be used to test if an
238 * underlying {@link FileStore} supports the file attributes identified by a
239 * file attribute view.
240 *
241 * @return An unmodifiable set of the names of the supported file attribute
242 * views
243 */
244 public abstract Set<String> supportedFileAttributeViews();
245
246 /**
247 * Converts a path string to a {@code Path}.
248 *
249 * <p> The parsing and conversion to a path object is inherently
250 * implementation dependent. In the simplest case, the path string is rejected,
251 * and {@link InvalidPathException} thrown, if the path string contains
252 * characters that cannot be converted to characters that are <em>legal</em>
253 * to the file store. For example, on UNIX systems, the NUL (\u0000)
254 * character is not allowed to be present in a path. An implementation may
255 * choose to reject path strings that contain names that are longer than those
256 * allowed by any file store, and where an implementation supports a complex
257 * path syntax, it may choose to reject path strings that are <em>badly
258 * formed</em>.
259 *
260 * <p> In the case of the default provider, path strings are parsed based
261 * on the definition of paths at the platform or virtual file system level.
262 * For example, an operating system may not allow specific characters to be
263 * present in a file name, but a specific underlying file store may impose
264 * different or additional restrictions on the set of legal
265 * characters.
266 *
267 * <p> This method throws {@link InvalidPathException} when the path string
268 * cannot be converted to a path. Where possible, and where applicable,
269 * the exception is created with an {@link InvalidPathException#getIndex
270 * index} value indicating the first position in the {@code path} parameter
271 * that caused the path string to be rejected.
272 *
273 * <p> Invoking this method with an empty path string throws
274 * {@code InvalidPathException}.
275 *
276 * @param path
277 * The path string
278 *
279 * @return A {@code Path} object
280 *
281 * @throws InvalidPathException
282 * If the path string cannot be converted
283 */
284 public abstract Path getPath(String path);
285
286 /**
287 * Returns a {@code PathMatcher} that performs match operations on the
288 * {@code String} representation of {@link Path} objects by interpreting a
289 * given pattern.
290 *
291 * The {@code syntaxAndPattern} parameter identifies the syntax and the
292 * pattern and takes the form:
293 * <blockquote>
294 * <i>syntax</i><b>:</b><i>pattern</i>
295 * </blockquote>
296 * where {@code ':'} stands for itself.
297 *
298 * <p> A {@code FileSystem} implementation supports the "{@code glob}" and
299 * "{@code regex}" syntaxes, and may support others. The value of the syntax
300 * component is compared without regard to case.
301 *
302 * <p> When the syntax is "{@code glob}" then the {@code String}
303 * representation of the path is matched using a limited pattern language
304 * that resembles regular expressions but with a simpler syntax. For example:
392 * <p> When the syntax is "{@code regex}" then the pattern component is a
393 * regular expression as defined by the {@link java.util.regex.Pattern}
394 * class.
395 *
396 * <p> For both the glob and regex syntaxes, the matching details, such as
397 * whether the matching is case sensitive, are implementation-dependent
398 * and therefore not specified.
399 *
400 * @param syntaxAndPattern
401 * The syntax and pattern
402 *
403 * @return A path matcher that may be used to match paths against the pattern
404 *
405 * @throws IllegalArgumentException
406 * If the parameter does not take the form: {@code syntax:pattern}
407 * @throws java.util.regex.PatternSyntaxException
408 * If the pattern is invalid
409 * @throws UnsupportedOperationException
410 * If the pattern syntax is not known to the implementation
411 *
412 * @see Path#newDirectoryStream(String)
413 */
414 public abstract PathMatcher getPathMatcher(String syntaxAndPattern);
415
416 /**
417 * Returns the {@code UserPrincipalLookupService} for this file system
418 * <i>(optional operation)</i>. The resulting lookup service may be used to
419 * lookup user or group names.
420 *
421 * <p> <b>Usage Example:</b>
422 * Suppose we want to make "joe" the owner of a file:
423 * <pre>
424 * Path file = ...
425 * UserPrincipal joe = file.getFileSystem().getUserPrincipalLookupService()
426 * .lookupPrincipalByName("joe");
427 * Attributes.setOwner(file, joe);
428 * </pre>
429 *
430 * @throws UnsupportedOperationException
431 * If this {@code FileSystem} does not does have a lookup service
432 *
433 * @return The {@code UserPrincipalLookupService} for this file system
434 */
435 public abstract UserPrincipalLookupService getUserPrincipalLookupService();
436
437 /**
438 * Constructs a new {@link WatchService} <i>(optional operation)</i>.
439 *
440 * <p> This method constructs a new watch service that may be used to watch
441 * registered objects for changes and events.
442 *
443 * @return a new watch service
444 *
445 * @throws UnsupportedOperationException
446 * If this {@code FileSystem} does not support watching file system
447 * objects for changes and events. This exception is not thrown
|
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 *
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>
305 * <i>syntax</i><b>:</b><i>pattern</i>
306 * </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:
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 */
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 */
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
|