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 (&#92;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>&#47;home&#47;*&#47;*</tt>
 339      *   <td>Matches <tt>&#47;home&#47;gus&#47;data</tt> on UNIX platforms</td>
 340      * </tr>
 341      * <tr>
 342      *   <td><tt>&#47;home&#47;**</tt>
 343      *   <td>Matches <tt>&#47;home&#47;gus</tt> and
 344      *   <tt>&#47;home&#47;gus&#47;data</tt> on UNIX platforms</td>
 345      * </tr>
 346      * <tr>
 347      *   <td><tt>C:&#92;&#92;*</tt>
 348      *   <td>Matches <tt>C:&#92;foo</tt> and <tt>C:&#92;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:&#92;&#92;&#92;&#92*"</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>&#47;</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 }