1 /*
2 * Copyright (c) 2007, 2013, 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.io.File;
29 import java.io.IOException;
30 import java.net.URI;
31 import java.util.Iterator;
32 import java.util.NoSuchElementException;
33
34 /**
35 * An object that may be used to locate a file in a file system. It will
36 * typically represent a system dependent file path.
37 *
38 * <p> A {@code Path} represents a path that is hierarchical and composed of a
39 * sequence of directory and file name elements separated by a special separator
40 * or delimiter. A <em>root component</em>, that identifies a file system
41 * hierarchy, may also be present. The name element that is <em>farthest</em>
42 * from the root of the directory hierarchy is the name of a file or directory.
43 * The other name elements are directory names. A {@code Path} can represent a
44 * root, a root and a sequence of names, or simply one or more name elements.
45 * A {@code Path} is considered to be an <i>empty path</i> if it consists
46 * solely of one name element that is empty. Accessing a file using an
47 * <i>empty path</i> is equivalent to accessing the default directory of the
48 * file system. {@code Path} defines the {@link #getFileName() getFileName},
49 * {@link #getParent getParent}, {@link #getRoot getRoot}, and {@link #subpath
50 * subpath} methods to access the path components or a subsequence of its name
76 * BufferedReader reader = Files.newBufferedReader(path, StandardCharsets.UTF_8);
77 * </pre>
78 *
79 * <a id="interop"></a><h2>Interoperability</h2>
80 * <p> Paths associated with the default {@link
81 * java.nio.file.spi.FileSystemProvider provider} are generally interoperable
82 * with the {@link java.io.File java.io.File} class. Paths created by other
83 * providers are unlikely to be interoperable with the abstract path names
84 * represented by {@code java.io.File}. The {@link java.io.File#toPath toPath}
85 * method may be used to obtain a {@code Path} from the abstract path name
86 * represented by a {@code java.io.File} object. The resulting {@code Path} can
87 * be used to operate on the same file as the {@code java.io.File} object. In
88 * addition, the {@link #toFile toFile} method is useful to construct a {@code
89 * File} from the {@code String} representation of a {@code Path}.
90 *
91 * <h2>Concurrency</h2>
92 * <p> Implementations of this interface are immutable and safe for use by
93 * multiple concurrent threads.
94 *
95 * @since 1.7
96 * @see Paths
97 */
98
99 public interface Path
100 extends Comparable<Path>, Iterable<Path>, Watchable
101 {
102 /**
103 * Returns the file system that created this object.
104 *
105 * @return the file system that created this object
106 */
107 FileSystem getFileSystem();
108
109 /**
110 * Tells whether or not this path is absolute.
111 *
112 * <p> An absolute path is complete in that it doesn't need to be combined
113 * with other path information in order to locate a file.
114 *
115 * @return {@code true} if, and only if, this path is absolute
116 */
117 boolean isAbsolute();
118
119 /**
120 * Returns the root component of this path as a {@code Path} object,
121 * or {@code null} if this path does not have a root component.
122 *
510 * <p> This method constructs an absolute {@link URI} with a {@link
511 * URI#getScheme() scheme} equal to the URI scheme that identifies the
512 * provider. The exact form of the scheme specific part is highly provider
513 * dependent.
514 *
515 * <p> In the case of the default provider, the URI is hierarchical with
516 * a {@link URI#getPath() path} component that is absolute. The query and
517 * fragment components are undefined. Whether the authority component is
518 * defined or not is implementation dependent. There is no guarantee that
519 * the {@code URI} may be used to construct a {@link java.io.File java.io.File}.
520 * In particular, if this path represents a Universal Naming Convention (UNC)
521 * path, then the UNC server name may be encoded in the authority component
522 * of the resulting URI. In the case of the default provider, and the file
523 * exists, and it can be determined that the file is a directory, then the
524 * resulting {@code URI} will end with a slash.
525 *
526 * <p> The default provider provides a similar <em>round-trip</em> guarantee
527 * to the {@link java.io.File} class. For a given {@code Path} <i>p</i> it
528 * is guaranteed that
529 * <blockquote>
530 * {@link Paths#get(URI) Paths.get}{@code (}<i>p</i>{@code .toUri()).equals(}<i>p</i>
531 * {@code .}{@link #toAbsolutePath() toAbsolutePath}{@code ())}
532 * </blockquote>
533 * so long as the original {@code Path}, the {@code URI}, and the new {@code
534 * Path} are all created in (possibly different invocations of) the same
535 * Java virtual machine. Whether other providers make any guarantees is
536 * provider specific and therefore unspecified.
537 *
538 * <p> When a file system is constructed to access the contents of a file
539 * as a file system then it is highly implementation specific if the returned
540 * URI represents the given path in the file system or it represents a
541 * <em>compound</em> URI that encodes the URI of the enclosing file system.
542 * A format for compound URIs is not defined in this release; such a scheme
543 * may be added in a future release.
544 *
545 * @return the URI representing this path
546 *
547 * @throws java.io.IOError
548 * if an I/O error occurs obtaining the absolute path, or where a
549 * file system is constructed to access the contents of a file as
550 * a file system, and the URI of the enclosing file system cannot be
|
1 /*
2 * Copyright (c) 2007, 2018, 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.io.File;
29 import java.io.IOException;
30 import java.net.URI;
31 import java.nio.file.spi.FileSystemProvider;
32 import java.util.Iterator;
33 import java.util.NoSuchElementException;
34
35 /**
36 * An object that may be used to locate a file in a file system. It will
37 * typically represent a system dependent file path.
38 *
39 * <p> A {@code Path} represents a path that is hierarchical and composed of a
40 * sequence of directory and file name elements separated by a special separator
41 * or delimiter. A <em>root component</em>, that identifies a file system
42 * hierarchy, may also be present. The name element that is <em>farthest</em>
43 * from the root of the directory hierarchy is the name of a file or directory.
44 * The other name elements are directory names. A {@code Path} can represent a
45 * root, a root and a sequence of names, or simply one or more name elements.
46 * A {@code Path} is considered to be an <i>empty path</i> if it consists
47 * solely of one name element that is empty. Accessing a file using an
48 * <i>empty path</i> is equivalent to accessing the default directory of the
49 * file system. {@code Path} defines the {@link #getFileName() getFileName},
50 * {@link #getParent getParent}, {@link #getRoot getRoot}, and {@link #subpath
51 * subpath} methods to access the path components or a subsequence of its name
77 * BufferedReader reader = Files.newBufferedReader(path, StandardCharsets.UTF_8);
78 * </pre>
79 *
80 * <a id="interop"></a><h2>Interoperability</h2>
81 * <p> Paths associated with the default {@link
82 * java.nio.file.spi.FileSystemProvider provider} are generally interoperable
83 * with the {@link java.io.File java.io.File} class. Paths created by other
84 * providers are unlikely to be interoperable with the abstract path names
85 * represented by {@code java.io.File}. The {@link java.io.File#toPath toPath}
86 * method may be used to obtain a {@code Path} from the abstract path name
87 * represented by a {@code java.io.File} object. The resulting {@code Path} can
88 * be used to operate on the same file as the {@code java.io.File} object. In
89 * addition, the {@link #toFile toFile} method is useful to construct a {@code
90 * File} from the {@code String} representation of a {@code Path}.
91 *
92 * <h2>Concurrency</h2>
93 * <p> Implementations of this interface are immutable and safe for use by
94 * multiple concurrent threads.
95 *
96 * @since 1.7
97 */
98
99 public interface Path
100 extends Comparable<Path>, Iterable<Path>, Watchable
101 {
102 /**
103 * Converts a path string, or a sequence of strings that when joined form
104 * a path string, to a {@code Path}. If {@code more} does not specify any
105 * elements then the value of the {@code first} parameter is the path string
106 * to convert. If {@code more} specifies one or more elements then each
107 * non-empty string, including {@code first}, is considered to be a sequence
108 * of name elements and is joined to form a path string.
109 * The details as to how the Strings are joined is provider specific but
110 * typically they will be joined using the {@link FileSystem#getSeparator
111 * name-separator} as the separator. For example, if the name separator is
112 * "{@code /}" and {@code getPath("/foo","bar","gus")} is invoked, then the
113 * path string {@code "/foo/bar/gus"} is converted to a {@code Path}.
114 * A {@code Path} representing an empty path is returned if {@code first}
115 * is the empty string and {@code more} does not contain any non-empty
116 * strings.
117 *
118 * <p> The {@code Path} is obtained by invoking the {@link FileSystem#getPath
119 * getPath} method of the {@link FileSystems#getDefault default} {@link
120 * FileSystem}.
121 *
122 * <p> Note that while this method is very convenient, using it will imply
123 * an assumed reference to the default {@code FileSystem} and limit the
124 * utility of the calling code. Hence it should not be used in library code
125 * intended for flexible reuse. A more flexible alternative is to use an
126 * existing {@code Path} instance as an anchor, such as:
127 * <pre>
128 * Path dir = ...
129 * Path path = dir.resolve("file");
130 * </pre>
131 *
132 * @param first
133 * the path string or initial part of the path string
134 * @param more
135 * additional strings to be joined to form the path string
136 *
137 * @return the resulting {@code Path}
138 *
139 * @throws InvalidPathException
140 * if the path string cannot be converted to a {@code Path}
141 *
142 * @see FileSystem#getPath
143 */
144 public static Path get(String first, String... more) {
145 return FileSystems.getDefault().getPath(first, more);
146 }
147
148 /**
149 * Converts the given URI to a {@link Path} object.
150 *
151 * <p> This method iterates over the {@link FileSystemProvider#installedProviders()
152 * installed} providers to locate the provider that is identified by the
153 * URI {@link URI#getScheme scheme} of the given URI. URI schemes are
154 * compared without regard to case. If the provider is found then its {@link
155 * FileSystemProvider#getPath getPath} method is invoked to convert the
156 * URI.
157 *
158 * <p> In the case of the default provider, identified by the URI scheme
159 * "file", the given URI has a non-empty path component, and undefined query
160 * and fragment components. Whether the authority component may be present
161 * is platform specific. The returned {@code Path} is associated with the
162 * {@link FileSystems#getDefault default} file system.
163 *
164 * <p> The default provider provides a similar <em>round-trip</em> guarantee
165 * to the {@link java.io.File} class. For a given {@code Path} <i>p</i> it
166 * is guaranteed that
167 * <blockquote>{@code
168 * Path.get(}<i>p</i>{@code .}{@link Path#toUri() toUri}{@code ()).equals(}
169 * <i>p</i>{@code .}{@link Path#toAbsolutePath() toAbsolutePath}{@code ())}
170 * </blockquote>
171 * so long as the original {@code Path}, the {@code URI}, and the new {@code
172 * Path} are all created in (possibly different invocations of) the same
173 * Java virtual machine. Whether other providers make any guarantees is
174 * provider specific and therefore unspecified.
175 *
176 * @param uri
177 * the URI to convert
178 *
179 * @return the resulting {@code Path}
180 *
181 * @throws IllegalArgumentException
182 * if preconditions on the {@code uri} parameter do not hold. The
183 * format of the URI is provider specific.
184 * @throws FileSystemNotFoundException
185 * The file system, identified by the URI, does not exist and
186 * cannot be created automatically, or the provider identified by
187 * the URI's scheme component is not installed
188 * @throws SecurityException
189 * if a security manager is installed and it denies an unspecified
190 * permission to access the file system
191 */
192 public static Path get(URI uri) {
193 String scheme = uri.getScheme();
194 if (scheme == null)
195 throw new IllegalArgumentException("Missing scheme");
196
197 // check for default provider to avoid loading of installed providers
198 if (scheme.equalsIgnoreCase("file"))
199 return FileSystems.getDefault().provider().getPath(uri);
200
201 // try to find provider
202 for (FileSystemProvider provider: FileSystemProvider.installedProviders()) {
203 if (provider.getScheme().equalsIgnoreCase(scheme)) {
204 return provider.getPath(uri);
205 }
206 }
207
208 throw new FileSystemNotFoundException("Provider \"" + scheme + "\" not installed");
209 }
210
211 /**
212 * Returns the file system that created this object.
213 *
214 * @return the file system that created this object
215 */
216 FileSystem getFileSystem();
217
218 /**
219 * Tells whether or not this path is absolute.
220 *
221 * <p> An absolute path is complete in that it doesn't need to be combined
222 * with other path information in order to locate a file.
223 *
224 * @return {@code true} if, and only if, this path is absolute
225 */
226 boolean isAbsolute();
227
228 /**
229 * Returns the root component of this path as a {@code Path} object,
230 * or {@code null} if this path does not have a root component.
231 *
619 * <p> This method constructs an absolute {@link URI} with a {@link
620 * URI#getScheme() scheme} equal to the URI scheme that identifies the
621 * provider. The exact form of the scheme specific part is highly provider
622 * dependent.
623 *
624 * <p> In the case of the default provider, the URI is hierarchical with
625 * a {@link URI#getPath() path} component that is absolute. The query and
626 * fragment components are undefined. Whether the authority component is
627 * defined or not is implementation dependent. There is no guarantee that
628 * the {@code URI} may be used to construct a {@link java.io.File java.io.File}.
629 * In particular, if this path represents a Universal Naming Convention (UNC)
630 * path, then the UNC server name may be encoded in the authority component
631 * of the resulting URI. In the case of the default provider, and the file
632 * exists, and it can be determined that the file is a directory, then the
633 * resulting {@code URI} will end with a slash.
634 *
635 * <p> The default provider provides a similar <em>round-trip</em> guarantee
636 * to the {@link java.io.File} class. For a given {@code Path} <i>p</i> it
637 * is guaranteed that
638 * <blockquote>
639 * {@link Path#get(URI) Path.get}{@code (}<i>p</i>{@code .toUri()).equals(}<i>p</i>
640 * {@code .}{@link #toAbsolutePath() toAbsolutePath}{@code ())}
641 * </blockquote>
642 * so long as the original {@code Path}, the {@code URI}, and the new {@code
643 * Path} are all created in (possibly different invocations of) the same
644 * Java virtual machine. Whether other providers make any guarantees is
645 * provider specific and therefore unspecified.
646 *
647 * <p> When a file system is constructed to access the contents of a file
648 * as a file system then it is highly implementation specific if the returned
649 * URI represents the given path in the file system or it represents a
650 * <em>compound</em> URI that encodes the URI of the enclosing file system.
651 * A format for compound URIs is not defined in this release; such a scheme
652 * may be added in a future release.
653 *
654 * @return the URI representing this path
655 *
656 * @throws java.io.IOError
657 * if an I/O error occurs obtaining the absolute path, or where a
658 * file system is constructed to access the contents of a file as
659 * a file system, and the URI of the enclosing file system cannot be
|