History

My first initial commit with all of mine experimental changes.

Dmitry Kabak (userdima committed 13 years ago

Commit d37b88d1 parent 3f5b46618352 files · +2598093 −-8690Browse files

Showing the changes to java/pkg/java/nio/file/FileSystem.java (1 of 18352 files). Show all

Unified · Split

java/pkg/java/nio/file/FileSystem.java+469−0
@@ -0,0 +1,469 @@
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+}