src/share/classes/java/nio/file/FileSystem.java
Print this page
@@ -36,12 +36,12 @@
* access files and other objects in the file system.
*
* <p> The default file system, obtained by invoking the {@link FileSystems#getDefault
* FileSystems.getDefault} method, provides access to the file system that is
* accessible to the Java virtual machine. The {@link FileSystems} class defines
- * methods to create file systems that provide access to other types of file
- * systems.
+ * methods to create file systems that provide access to other types of (custom)
+ * file systems.
*
* <p> A file system is the factory for several types of objects:
*
* <ul>
* <li><p> The {@link #getPath getPath} method converts a system dependent
@@ -212,14 +212,13 @@
*
* <p> <b>Usage Example:</b>
* Suppose we want to print the space usage for all file stores:
* <pre>
* for (FileStore store: FileSystems.getDefault().getFileStores()) {
- * FileStoreSpaceAttributes attrs = Attributes.readFileStoreSpaceAttributes(store);
- * long total = attrs.totalSpace() / 1024;
- * long used = (attrs.totalSpace() - attrs.unallocatedSpace()) / 1024;
- * long avail = attrs.usableSpace() / 1024;
+ * long total = store.getTotalSpace() / 1024;
+ * long used = (store.getTotalSpace() - store.getUnallocatedSpace()) / 1024;
+ * long avail = store.getUsableSpace() / 1024;
* System.out.format("%-20s %12d %12d %12d%n", store, total, used, avail);
* }
* </pre>
*
* @return An object to iterate over the backing file stores
@@ -242,11 +241,24 @@
* views
*/
public abstract Set<String> supportedFileAttributeViews();
/**
- * Converts a path string to a {@code Path}.
+ * Converts a path string, or a sequence of strings that when joined form
+ * a path string, to a {@code Path}. If {@code more} does not specify any
+ * elements then the value of the {@code first} parameter is the path string
+ * to convert. If {@code more} specifies one or more elements then each
+ * non-empty string, including {@code first}, is considered to be a sequence
+ * of name elements (see {@link Path}) and is joined to form a path string.
+ * The details as to how the Strings are joined is provider specific but
+ * typically they will be joined using the {@link #getSeparator
+ * name-separator} as the separator. For example, if the name separator is
+ * "{@code /}" and {@code getPath("/foo","bar","gus")} is invoked, then the
+ * path string {@code "/foo/bar/gus"} is converted to a {@code Path}.
+ * A {@code Path} representing an empty path is returned if {@code first}
+ * is the empty string and {@code more} does not contain any non-empty
+ * strings.
*
* <p> The parsing and conversion to a path object is inherently
* implementation dependent. In the simplest case, the path string is rejected,
* and {@link InvalidPathException} thrown, if the path string contains
* characters that cannot be converted to characters that are <em>legal</em>
@@ -268,22 +280,21 @@
* cannot be converted to a path. Where possible, and where applicable,
* the exception is created with an {@link InvalidPathException#getIndex
* index} value indicating the first position in the {@code path} parameter
* that caused the path string to be rejected.
*
- * <p> Invoking this method with an empty path string throws
- * {@code InvalidPathException}.
+ * @param first
+ * the path string or initial part of the path string
+ * @param more
+ * additional strings to be joined to form the path string
*
- * @param path
- * The path string
+ * @return the resulting {@code Path}
*
- * @return A {@code Path} object
- *
* @throws InvalidPathException
* If the path string cannot be converted
*/
- public abstract Path getPath(String path);
+ public abstract Path getPath(String first, String... more);
/**
* Returns a {@code PathMatcher} that performs match operations on the
* {@code String} representation of {@link Path} objects by interpreting a
* given pattern.
@@ -407,11 +418,11 @@
* @throws java.util.regex.PatternSyntaxException
* If the pattern is invalid
* @throws UnsupportedOperationException
* If the pattern syntax is not known to the implementation
*
- * @see Path#newDirectoryStream(String)
+ * @see Files#newDirectoryStream(Path,String)
*/
public abstract PathMatcher getPathMatcher(String syntaxAndPattern);
/**
* Returns the {@code UserPrincipalLookupService} for this file system
@@ -419,14 +430,12 @@
* lookup user or group names.
*
* <p> <b>Usage Example:</b>
* Suppose we want to make "joe" the owner of a file:
* <pre>
- * Path file = ...
- * UserPrincipal joe = file.getFileSystem().getUserPrincipalLookupService()
- * .lookupPrincipalByName("joe");
- * Attributes.setOwner(file, joe);
+ * UserPrincipalLookupService lookupService = FileSystems.getDefault().getUserPrincipalLookupService();
+ * Files.setOwner(path, lookupService.lookupPrincipalByName("joe"));
* </pre>
*
* @throws UnsupportedOperationException
* If this {@code FileSystem} does not does have a lookup service
*