/* * Copyright (c) 2007, 2011, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it * under the terms of the GNU General Public License version 2 only, as * published by the Free Software Foundation. Oracle designates this * particular file as subject to the "Classpath" exception as provided * by Oracle in the LICENSE file that accompanied this code. * * This code is distributed in the hope that it will be useful, but WITHOUT * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License * version 2 for more details (a copy is included in the LICENSE file that * accompanied this code). * * You should have received a copy of the GNU General Public License version * 2 along with this work; if not, write to the Free Software Foundation, * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. * * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA * or visit www.oracle.com if you need additional information or have any * questions. */ package java.nio.file; import java.nio.file.attribute.*; import java.nio.file.spi.FileSystemProvider; import java.util.Set; import java.io.Closeable; import java.io.IOException; /** * Provides an interface to a file system and is the factory for objects to * access files and other objects in the file system. * *

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 (custom) * file systems. * *

A file system is the factory for several types of objects: * *

* *

File systems vary greatly. In some cases the file system is a single * hierarchy of files with one top-level root directory. In other cases it may * have several distinct file hierarchies, each with its own top-level root * directory. The {@link #getRootDirectories getRootDirectories} method may be * used to iterate over the root directories in the file system. A file system * is typically composed of one or more underlying {@link FileStore file-stores} * that provide the storage for the files. Theses file stores can also vary in * the features they support, and the file attributes or meta-data that * they associate with files. * *

A file system is open upon creation and can be closed by invoking its * {@link #close() close} method. Once closed, any further attempt to access * objects in the file system cause {@link ClosedFileSystemException} to be * thrown. File systems created by the default {@link FileSystemProvider provider} * cannot be closed. * *

A {@code FileSystem} can provide read-only or read-write access to the * file system. Whether or not a file system provides read-only access is * established when the {@code FileSystem} is created and can be tested by invoking * its {@link #isReadOnly() isReadOnly} method. Attempts to write to file stores * by means of an object associated with a read-only file system throws {@link * ReadOnlyFileSystemException}. * *

File systems are safe for use by multiple concurrent threads. The {@link * #close close} method may be invoked at any time to close a file system but * whether a file system is asynchronously closeable is provider specific * and therefore unspecified. In other words, if a thread is accessing an * object in a file system, and another thread invokes the {@code close} method * then it may require to block until the first operation is complete. Closing * a file system causes all open channels, watch services, and other {@link * Closeable closeable} objects associated with the file system to be closed. * * @since 1.7 */ public abstract class FileSystem implements Closeable { /** * Initializes a new instance of this class. */ protected FileSystem() { } /** * Returns the provider that created this file system. * * @return The provider that created this file system. */ public abstract FileSystemProvider provider(); /** * Closes this file system. * *

After a file system is closed then all subsequent access to the file * system, either by methods defined by this class or on objects associated * with this file system, throw {@link ClosedFileSystemException}. If the * file system is already closed then invoking this method has no effect. * *

Closing a file system will close all open {@link * java.nio.channels.Channel channels}, {@link DirectoryStream directory-streams}, * {@link WatchService watch-service}, and other closeable objects associated * with this file system. The {@link FileSystems#getDefault default} file * system cannot be closed. * * @throws IOException * If an I/O error occurs * @throws UnsupportedOperationException * Thrown in the case of the default file system */ @Override public abstract void close() throws IOException; /** * Tells whether or not this file system is open. * *

File systems created by the default provider are always open. * * @return {@code true} if, and only if, this file system is open */ public abstract boolean isOpen(); /** * Tells whether or not this file system allows only read-only access to * its file stores. * * @return {@code true} if, and only if, this file system provides * read-only access */ public abstract boolean isReadOnly(); /** * Returns the name separator, represented as a string. * *

The name separator is used to separate names in a path string. An * implementation may support multiple name separators in which case this * method returns an implementation specific default name separator. * This separator is used when creating path strings by invoking the {@link * Path#toString() toString()} method. * *

In the case of the default provider, this method returns the same * separator as {@link java.io.File#separator}. * * @return The name separator */ public abstract String getSeparator(); /** * Returns an object to iterate over the paths of the root directories. * *

A file system provides access to a file store that may be composed * of a number of distinct file hierarchies, each with its own top-level * root directory. Unless denied by the security manager, each element in * the returned iterator corresponds to the root directory of a distinct * file hierarchy. The order of the elements is not defined. The file * hierarchies may change during the lifetime of the Java virtual machine. * For example, in some implementations, the insertion of removable media * may result in the creation of a new file hierarchy with its own * top-level directory. * *

When a security manager is installed, it is invoked to check access * to the each root directory. If denied, the root directory is not returned * by the iterator. In the case of the default provider, the {@link * SecurityManager#checkRead(String)} method is invoked to check read access * to each root directory. It is system dependent if the permission checks * are done when the iterator is obtained or during iteration. * * @return An object to iterate over the root directories */ public abstract Iterable getRootDirectories(); /** * Returns an object to iterate over the underlying file stores. * *

The elements of the returned iterator are the {@link * FileStore FileStores} for this file system. The order of the elements is * not defined and the file stores may change during the lifetime of the * Java virtual machine. When an I/O error occurs, perhaps because a file * store is not accessible, then it is not returned by the iterator. * *

In the case of the default provider, and a security manager is * installed, the security manager is invoked to check {@link * RuntimePermission}("getFileStoreAttributes"). If denied, then * no file stores are returned by the iterator. In addition, the security * manager's {@link SecurityManager#checkRead(String)} method is invoked to * check read access to the file store's top-most directory. If * denied, the file store is not returned by the iterator. It is system * dependent if the permission checks are done when the iterator is obtained * or during iteration. * *

Usage Example: * Suppose we want to print the space usage for all file stores: * 

     *     for (FileStore store: FileSystems.getDefault().getFileStores()) {
     *         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);
     *     }
     *
* * @return An object to iterate over the backing file stores */ public abstract Iterable getFileStores(); /** * Returns the set of the {@link FileAttributeView#name names} of the file * attribute views supported by this {@code FileSystem}. * *

The {@link BasicFileAttributeView} is required to be supported and * therefore the set contains at least one element, "basic". * *

The {@link FileStore#supportsFileAttributeView(String) * supportsFileAttributeView(String)} method may be used to test if an * underlying {@link FileStore} supports the file attributes identified by a * file attribute view. * * @return An unmodifiable set of the names of the supported file attribute * views */ public abstract Set supportedFileAttributeViews(); /** * 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. * *

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 legal * to the file store. For example, on UNIX systems, the NUL (\u0000) * character is not allowed to be present in a path. An implementation may * choose to reject path strings that contain names that are longer than those * allowed by any file store, and where an implementation supports a complex * path syntax, it may choose to reject path strings that are badly * formed. * *

In the case of the default provider, path strings are parsed based * on the definition of paths at the platform or virtual file system level. * For example, an operating system may not allow specific characters to be * present in a file name, but a specific underlying file store may impose * different or additional restrictions on the set of legal * characters. * *

This method throws {@link InvalidPathException} when the path string * 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. * * @param first * the path string or initial part of the path string * @param more * additional strings to be joined to form the path string * * @return the resulting {@code Path} * * @throws InvalidPathException * If the path string cannot be converted */ 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. * * The {@code syntaxAndPattern} parameter identifies the syntax and the * pattern and takes the form: * 

     * syntax:pattern
     *
* where {@code ':'} stands for itself. * *

A {@code FileSystem} implementation supports the "{@code glob}" and * "{@code regex}" syntaxes, and may support others. The value of the syntax * component is compared without regard to case. * *

When the syntax is "{@code glob}" then the {@code String} * representation of the path is matched using a limited pattern language * that resembles regular expressions but with a simpler syntax. For example: * *

* * * * * * * * * * * * * * * * * * * * * * * * * * * * *
{@code *.java}Matches a path that represents a file name ending in {@code .java}
{@code *.*}Matches file names containing a dot
{@code *.{java,class}}Matches file names ending with {@code .java} or {@code .class}
{@code foo.?}Matches file names starting with {@code foo.} and a single * character extension
/home/*/* * Matches /home/gus/data on UNIX platforms
/home/** * Matches /home/gus and * /home/gus/data on UNIX platforms
C:\\* * Matches C:\foo and C:\bar on the Windows * platform (note that the backslash is escaped; as a string literal in the * Java Language the pattern would be "C:\\\\*")
*
* *

The following rules are used to interpret glob patterns: * *

* *

When the syntax is "{@code regex}" then the pattern component is a * regular expression as defined by the {@link java.util.regex.Pattern} * class. * *

For both the glob and regex syntaxes, the matching details, such as * whether the matching is case sensitive, are implementation-dependent * and therefore not specified. * * @param syntaxAndPattern * The syntax and pattern * * @return A path matcher that may be used to match paths against the pattern * * @throws IllegalArgumentException * If the parameter does not take the form: {@code syntax:pattern} * @throws java.util.regex.PatternSyntaxException * If the pattern is invalid * @throws UnsupportedOperationException * If the pattern syntax is not known to the implementation * * @see Files#newDirectoryStream(Path,String) */ public abstract PathMatcher getPathMatcher(String syntaxAndPattern); /** * Returns the {@code UserPrincipalLookupService} for this file system * (optional operation). The resulting lookup service may be used to * lookup user or group names. * *

Usage Example: * Suppose we want to make "joe" the owner of a file: * 

     *     UserPrincipalLookupService lookupService = FileSystems.getDefault().getUserPrincipalLookupService();
     *     Files.setOwner(path, lookupService.lookupPrincipalByName("joe"));
     *
* * @throws UnsupportedOperationException * If this {@code FileSystem} does not does have a lookup service * * @return The {@code UserPrincipalLookupService} for this file system */ public abstract UserPrincipalLookupService getUserPrincipalLookupService(); /** * Constructs a new {@link WatchService} (optional operation). * *

This method constructs a new watch service that may be used to watch * registered objects for changes and events. * * @return a new watch service * * @throws UnsupportedOperationException * If this {@code FileSystem} does not support watching file system * objects for changes and events. This exception is not thrown * by {@code FileSystems} created by the default provider. * @throws IOException * If an I/O error occurs */ public abstract WatchService newWatchService() throws IOException; }