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
      *