47 * file system. {@code Path} defines the {@link #getFileName() getFileName},
48 * {@link #getParent getParent}, {@link #getRoot getRoot}, and {@link #subpath
49 * subpath} methods to access the path components or a subsequence of its name
50 * elements.
51 *
52 * <p> In addition to accessing the components of a path, a {@code Path} also
53 * defines the {@link #resolve(Path) resolve} and {@link #resolveSibling(Path)
54 * resolveSibling} methods to combine paths. The {@link #relativize relativize}
55 * method that can be used to construct a relative path between two paths.
56 * Paths can be {@link #compareTo compared}, and tested against each other using
57 * the {@link #startsWith startsWith} and {@link #endsWith endsWith} methods.
58 *
59 * <p> This interface extends {@link Watchable} interface so that a directory
60 * located by a path can be {@link #register registered} with a {@link
61 * WatchService} and entries in the directory watched. </p>
62 *
63 * <p> <b>WARNING:</b> This interface is only intended to be implemented by
64 * those developing custom file system implementations. Methods may be added to
65 * this interface in future releases. </p>
66 *
67 * <a name="interop"><h4>Accessing Files</h4></a>
68 * <p> Paths may be used with the {@link Files} class to operate on files,
69 * directories, and other types of files. For example, suppose we want a {@link
70 * java.io.BufferedReader} to read text from a file "{@code access.log}". The
71 * file is located in a directory "{@code logs}" relative to the current working
72 * directory and is UTF-8 encoded.
73 * <pre>
74 * Path path = FileSystems.getDefault().getPath("logs", "access.log");
75 * BufferedReader reader = Files.newBufferedReader(path, StandardCharsets.UTF_8);
76 * </pre>
77 *
78 * <a name="interop"><h4>Interoperability</h4></a>
79 * <p> Paths associated with the default {@link
80 * java.nio.file.spi.FileSystemProvider provider} are generally interoperable
81 * with the {@link java.io.File java.io.File} class. Paths created by other
82 * providers are unlikely to be interoperable with the abstract path names
83 * represented by {@code java.io.File}. The {@link java.io.File#toPath toPath}
84 * method may be used to obtain a {@code Path} from the abstract path name
85 * represented by a {@code java.io.File} object. The resulting {@code Path} can
86 * be used to operate on the same file as the {@code java.io.File} object. In
87 * addition, the {@link #toFile toFile} method is useful to construct a {@code
88 * File} from the {@code String} representation of a {@code Path}.
89 *
90 * <h4>Concurrency</h4></a>
91 * <p> Implementations of this interface are immutable and safe for use by
92 * multiple concurrent threads.
93 *
94 * @since 1.7
95 * @see Paths
96 */
97
98 public interface Path
99 extends Comparable<Path>, Iterable<Path>, Watchable
100 {
101 /**
102 * Returns the file system that created this object.
103 *
104 * @return the file system that created this object
105 */
106 FileSystem getFileSystem();
107
108 /**
109 * Tells whether or not this path is absolute.
110 *
|
47 * file system. {@code Path} defines the {@link #getFileName() getFileName},
48 * {@link #getParent getParent}, {@link #getRoot getRoot}, and {@link #subpath
49 * subpath} methods to access the path components or a subsequence of its name
50 * elements.
51 *
52 * <p> In addition to accessing the components of a path, a {@code Path} also
53 * defines the {@link #resolve(Path) resolve} and {@link #resolveSibling(Path)
54 * resolveSibling} methods to combine paths. The {@link #relativize relativize}
55 * method that can be used to construct a relative path between two paths.
56 * Paths can be {@link #compareTo compared}, and tested against each other using
57 * the {@link #startsWith startsWith} and {@link #endsWith endsWith} methods.
58 *
59 * <p> This interface extends {@link Watchable} interface so that a directory
60 * located by a path can be {@link #register registered} with a {@link
61 * WatchService} and entries in the directory watched. </p>
62 *
63 * <p> <b>WARNING:</b> This interface is only intended to be implemented by
64 * those developing custom file system implementations. Methods may be added to
65 * this interface in future releases. </p>
66 *
67 * <h4>Accessing Files</h4>
68 * <p> Paths may be used with the {@link Files} class to operate on files,
69 * directories, and other types of files. For example, suppose we want a {@link
70 * java.io.BufferedReader} to read text from a file "{@code access.log}". The
71 * file is located in a directory "{@code logs}" relative to the current working
72 * directory and is UTF-8 encoded.
73 * <pre>
74 * Path path = FileSystems.getDefault().getPath("logs", "access.log");
75 * BufferedReader reader = Files.newBufferedReader(path, StandardCharsets.UTF_8);
76 * </pre>
77 *
78 * <a name="interop"><h4>Interoperability</h4></a>
79 * <p> Paths associated with the default {@link
80 * java.nio.file.spi.FileSystemProvider provider} are generally interoperable
81 * with the {@link java.io.File java.io.File} class. Paths created by other
82 * providers are unlikely to be interoperable with the abstract path names
83 * represented by {@code java.io.File}. The {@link java.io.File#toPath toPath}
84 * method may be used to obtain a {@code Path} from the abstract path name
85 * represented by a {@code java.io.File} object. The resulting {@code Path} can
86 * be used to operate on the same file as the {@code java.io.File} object. In
87 * addition, the {@link #toFile toFile} method is useful to construct a {@code
88 * File} from the {@code String} representation of a {@code Path}.
89 *
90 * <h4>Concurrency</h4>
91 * <p> Implementations of this interface are immutable and safe for use by
92 * multiple concurrent threads.
93 *
94 * @since 1.7
95 * @see Paths
96 */
97
98 public interface Path
99 extends Comparable<Path>, Iterable<Path>, Watchable
100 {
101 /**
102 * Returns the file system that created this object.
103 *
104 * @return the file system that created this object
105 */
106 FileSystem getFileSystem();
107
108 /**
109 * Tells whether or not this path is absolute.
110 *
|