1 /*
2 * Copyright (c) 2007, 2009, 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 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 *
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 * 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:
305 *
306 * <blockquote>
307 * <table border="0">
308 * <tr>
309 * <td>{@code *.java}</td>
310 * <td>Matches a path that represents a file name ending in {@code .java}</td>
311 * </tr>
312 * <tr>
313 * <td>{@code *.*}</td>
314 * <td>Matches file names containing a dot</td>
315 * </tr>
316 * <tr>
317 * <tr>
318 * <td>{@code *.{java,class}}</td>
319 * <td>Matches file names ending with {@code .java} or {@code .class}</td>
320 * </tr>
321 * <tr>
322 * <td>{@code foo.?}</td>
323 * <td>Matches file names starting with {@code foo.} and a single
324 * character extension</td>
325 * </tr>
326 * <tr>
327 * <td><tt>/home/*/*</tt>
328 * <td>Matches <tt>/home/gus/data</tt> on UNIX platforms</td>
329 * </tr>
330 * <tr>
331 * <td><tt>/home/**</tt>
332 * <td>Matches <tt>/home/gus</tt> and
333 * <tt>/home/gus/data</tt> on UNIX platforms</td>
334 * </tr>
335 * <tr>
336 * <td><tt>C:\\*</tt>
337 * <td>Matches <tt>C:\foo</tt> and <tt>C:\bar</tt> on the Windows
338 * platform (note that the backslash is escaped; as a string literal in the
339 * Java Language the pattern would be <tt>"C:\\\\*"</tt>) </td>
340 * </tr>
341 *
342 * </table>
343 * </blockquote>
344 *
345 * <p> The following rules are used to interpret glob patterns:
346 *
347 * <p> <ul>
348 * <li><p> The {@code *} character matches zero or more {@link Character
349 * characters} of a {@link Path#getName(int) name} component without
350 * crossing directory boundaries. </p></li>
351 *
352 * <li><p> The {@code **} characters matches zero or more {@link Character
353 * characters} crossing directory boundaries. </p></li>
354 *
355 * <li><p> The {@code ?} character matches exactly one character of a
356 * name component.</p></li>
357 *
358 * <li><p> The backslash character ({@code \}) is used to escape characters
359 * that would otherwise be interpreted as special characters. The expression
360 * {@code \\} matches a single backslash and "\{" matches a left brace
361 * for example. </p></li>
362 *
363 * <li><p> The {@code [ ]} characters are a <i>bracket expression</i> that
364 * match a single character of a name component out of a set of characters.
365 * For example, {@code [abc]} matches {@code "a"}, {@code "b"}, or {@code "c"}.
366 * The hyphen ({@code -}) may be used to specify a range so {@code [a-z]}
367 * specifies a range that matches from {@code "a"} to {@code "z"} (inclusive).
368 * These forms can be mixed so [abce-g] matches {@code "a"}, {@code "b"},
369 * {@code "c"}, {@code "e"}, {@code "f"} or {@code "g"}. If the character
370 * after the {@code [} is a {@code !} then it is used for negation so {@code
371 * [!a-c]} matches any character except {@code "a"}, {@code "b"}, or {@code
372 * "c"}.
373 * <p> Within a bracket expression the {@code *}, {@code ?} and {@code \}
374 * characters match themselves. The ({@code -}) character matches itself if
375 * it is the first character within the brackets, or the first character
376 * after the {@code !} if negating.</p></li>
377 *
378 * <li><p> The {@code { }} characters are a group of subpatterns, where
379 * the group matches if any subpattern in the group matches. The {@code ","}
380 * character is used to separate the subpatterns. Groups cannot be nested.
381 * </p></li>
382 *
383 * <li><p> All other characters match themselves in an implementation
384 * dependent manner. This includes characters representing any {@link
385 * FileSystem#getSeparator name-separators}. </p></li>
386 *
387 * <li><p> The matching of {@link Path#getRoot root} components is highly
388 * implementation-dependent and is not specified. </p></li>
389 *
390 * </ul>
391 *
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
448 * by {@code FileSystems} created by the default provider.
449 * @throws IOException
450 * If an I/O error occurs
451 */
452 public abstract WatchService newWatchService() throws IOException;
453 }