/*

 * 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.io.File;

import java.io.IOException;

import java.net.URI;

import java.util.Iterator;

/**

 * An object that may be used to locate a file in a file system. It will

 * typically represent a system dependent file path.

 *

 * <p> A {@code Path} represents a path that is hierarchical and composed of a

 * sequence of directory and file name elements separated by a special separator

 * or delimiter. A <em>root component</em>, that identifies a file system

 * hierarchy, may also be present. The name element that is <em>farthest</em>

 * from the root of the directory hierarchy is the name of a file or directory.

 * The other name elements are directory names. A {@code Path} can represent a

 * root, a root and a sequence of names, or simply one or more name elements.

 * A {@code Path} is considered to be an <i>empty path</i> if it consists

 * solely of one name element that is empty. Accessing a file using an

 * <i>empty path</i> is equivalent to accessing the default directory of the

 * file system. {@code Path} defines the {@link #getFileName() getFileName},

 * {@link #getParent getParent}, {@link #getRoot getRoot}, and {@link #subpath

 * subpath} methods to access the path components or a subsequence of its name

 * elements.

 *

 * <p> In addition to accessing the components of a path, a {@code Path} also

 * defines the {@link #resolve(Path) resolve} and {@link #resolveSibling(Path)

 * resolveSibling} methods to combine paths. The {@link #relativize relativize}

 * method that can be used to construct a relative path between two paths.

 * Paths can be {@link #compareTo compared}, and tested against each other using

 * the {@link #startsWith startsWith} and {@link #endsWith endWith} methods.

 *

 * <p> This interface extends {@link Watchable} interface so that a directory

 * located by a path can be {@link #register registered} with a {@link

 * WatchService} and entries in the directory watched. </p>

 *

 * <p> <b>WARNING:</b> This interface is only intended to be implemented by

 * those developing custom file system implementations. Methods may be added to

 * this interface in future releases. </p>

 *

 * <a name="interop"><h4>Accessing Files</h4></a>

 * <p> Paths may be used with the {@link Files} class to operate on files,

 * directories, and other types of files. For example, suppose we want a {@link

 * java.io.BufferedReader} to read text from a file "{@code access.log}". The

 * file is located in a directory "{@code logs}" relative to the current working

 * directory and is UTF-8 encoded.

 * <pre>

 *     Path path = FileSystems.getDefault().getPath("logs", "access.log");

 *     BufferReader reader = Files.newBufferedReader(path, Charset.forName("UTF-8"));

 * </pre>

 *

 * <a name="interop"><h4>Interoperability</h4></a>

 * <p> Paths associated with the default {@link

 * java.nio.file.spi.FileSystemProvider provider} are generally interoperable

 * with the {@link java.io.File java.io.File} class. Paths created by other

 * providers are unlikely to be interoperable with the abstract path names

 * represented by {@code java.io.File}. The {@link java.io.File#toPath toPath}

 * method may be used to obtain a {@code Path} from the abstract path name

 * represented by a {@code java.io.File} object. The resulting {@code Path} can

 * be used to operate on the same file as the {@code java.io.File} object. In

 * addition, the {@link #toFile toFile} method is useful to construct a {@code

 * File} from the {@code String} representation of a {@code Path}.

 *

 * <h4>Concurrency</h4></a>

 * <p> Implementations of this interface are immutable and safe for use by

 * multiple concurrent threads.

 *

 * @since 1.7

 * @see Paths

 */

public interface Path

    extends Comparable<Path>, Iterable<Path>, Watchable

{

    /**

     * Returns the file system that created this object.

     *

     * @return  the file system that created this object

     */

    FileSystem getFileSystem();

    /**

     * Tells whether or not this path is absolute.

     *

     * <p> An absolute path is complete in that it doesn't need to be combined

     * with other path information in order to locate a file.

     *

     * @return  {@code true} if, and only if, this path is absolute

     */

    boolean isAbsolute();

    /**

     * Returns the root component of this path as a {@code Path} object,

     * or {@code null} if this path does not have a root component.

     *

     * @return  a path representing the root component of this path,

     *          or {@code null}

     */

    Path getRoot();

    /**

     * Returns the name of the file or directory denoted by this path as a

     * {@code Path} object. The file name is the <em>farthest</em> element from

     * the root in the directory hierarchy.

     *

     * @return  a path representing the name of the file or directory, or

     *          {@code null} if this path has zero elements

     */

    Path getFileName();

    /**

     * Returns the <em>parent path</em>, or {@code null} if this path does not

     * have a parent.

     *

     * <p> The parent of this path object consists of this path's root

     * component, if any, and each element in the path except for the

     * <em>farthest</em> from the root in the directory hierarchy. This method

     * does not access the file system; the path or its parent may not exist.

     * Furthermore, this method does not eliminate special names such as "."

     * and ".." that may be used in some implementations. On UNIX for example,

     * the parent of "{@code /a/b/c}" is "{@code /a/b}", and the parent of

     * {@code "x/y/.}" is "{@code x/y}". This method may be used with the {@link

     * #normalize normalize} method, to eliminate redundant names, for cases where

     * <em>shell-like</em> navigation is required.

     *

     * <p> If this path has one or more elements, and no root component, then

     * this method is equivalent to evaluating the expression:

     * <blockquote><pre>

     * subpath(0, getNameCount()-1);

     * </pre></blockquote>

     *

     * @return  a path representing the path's parent

     */

    Path getParent();

    /**

     * Returns the number of name elements in the path.

     *

     * @return  the number of elements in the path, or {@code 0} if this path

     *          only represents a root component

     */

    int getNameCount();

    /**

     * Returns a name element of this path as a {@code Path} object.

     *

     * <p> The {@code index} parameter is the index of the name element to return.

     * The element that is <em>closest</em> to the root in the directory hierarchy

     * has index {@code 0}. The element that is <em>farthest</em> from the root

     * has index {@link #getNameCount count}{@code -1}.

     *

     * @param   index

     *          the index of the element

     *

     * @return  the name element

     *

     * @throws  IllegalArgumentException

     *          if {@code index} is negative, {@code index} is greater than or

     *          equal to the number of elements, or this path has zero name

     *          elements

     */

    Path getName(int index);

    /**

     * Returns a relative {@code Path} that is a subsequence of the name

     * elements of this path.

     *

     * <p> The {@code beginIndex} and {@code endIndex} parameters specify the

     * subsequence of name elements. The name that is <em>closest</em> to the root

     * in the directory hierarchy has index {@code 0}. The name that is

     * <em>farthest</em> from the root has index {@link #getNameCount

     * count}{@code -1}. The returned {@code Path} object has the name elements

     * that begin at {@code beginIndex} and extend to the element at index {@code

     * endIndex-1}.

     *

     * @param   beginIndex

     *          the index of the first element, inclusive

     * @param   endIndex

     *          the index of the last element, exclusive

     *

     * @return  a new {@code Path} object that is a subsequence of the name

     *          elements in this {@code Path}

     *

     * @throws  IllegalArgumentException

     *          if {@code beginIndex} is negative, or greater than or equal to

     *          the number of elements. If {@code endIndex} is less than or

     *          equal to {@code beginIndex}, or larger than the number of elements.

     */

    Path subpath(int beginIndex, int endIndex);

    /**

     * Tests if this path starts with the given path.

     *

     * <p> This path <em>starts</em> with the given path if this path's root

     * component <em>starts</em> with the root component of the given path,

     * and this path starts with the same name elements as the given path.

     * If the given path has more name elements than this path then {@code false}

     * is returned.

     *

     * <p> Whether or not the root component of this path starts with the root

     * component of the given path is file system specific. If this path does

     * not have a root component and the given path has a root component then

     * this path does not start with the given path.

     *

     * <p> If the given path is associated with a different {@code FileSystem}

     * to this path then {@code false} is returned.

     *

     * @param   other

     *          the given path

     *

     * @return  {@code true} if this path starts with the given path; otherwise

     *          {@code false}

     */

    boolean startsWith(Path other);

    /**

     * Tests if this path starts with a {@code Path}, constructed by converting

     * the given path string, in exactly the manner specified by the {@link

     * #startsWith(Path) startsWith(Path)} method. On UNIX for example, the path

     * "{@code foo/bar}" starts with "{@code foo}" and "{@code foo/bar}". It

     * does not start with "{@code f}" or "{@code fo}".

     *

     * @param   other

     *          the given path string

     *

     * @return  {@code true} if this path starts with the given path; otherwise

     *          {@code false}

     *

     * @throws  InvalidPathException

     *          If the path string cannot be converted to a Path.

     */

    boolean startsWith(String other);

    /**

     * Tests if this path ends with the given path.

     *

     * <p> If the given path has <em>N</em> elements, and no root component,

     * and this path has <em>N</em> or more elements, then this path ends with

     * the given path if the last <em>N</em> elements of each path, starting at

     * the element farthest from the root, are equal.

     *

     * <p> If the given path has a root component then this path ends with the

     * given path if the root component of this path <em>ends with</em> the root

     * component of the given path, and the corresponding elements of both paths

     * are equal. Whether or not the root component of this path ends with the

     * root component of the given path is file system specific. If this path

     * does not have a root component and the given path has a root component

     * then this path does not end with the given path.

     *

     * <p> If the given path is associated with a different {@code FileSystem}

     * to this path then {@code false} is returned.

     *

     * @param   other

     *          the given path

     *

     * @return  {@code true} if this path ends with the given path; otherwise

     *          {@code false}

     */

    boolean endsWith(Path other);

    /**

     * Tests if this path ends with a {@code Path}, constructed by converting

     * the given path string, in exactly the manner specified by the {@link

     * #endsWith(Path) endsWith(Path)} method. On UNIX for example, the path

     * "{@code foo/bar}" ends with "{@code foo/bar}" and "{@code bar}". It does

     * not end with "{@code r}" or "{@code /bar}". Note that trailing separators

     * are not taken into account, and so invoking this method on the {@code

     * Path}"{@code foo/bar}" with the {@code String} "{@code bar/}" returns

     * {@code true}.

     *

     * @param   other

     *          the given path string

     *

     * @return  {@code true} if this path starts with the given path; otherwise

     *          {@code false}

     *

     * @throws  InvalidPathException

     *          If the path string cannot be converted to a Path.

     */

    boolean endsWith(String other);

    /**

     * Returns a path that is this path with redundant name elements eliminated.

     *

     * <p> The precise definition of this method is implementation dependent but

     * in general it derives from this path, a path that does not contain

     * <em>redundant</em> name elements. In many file systems, the "{@code .}"

     * and "{@code ..}" are special names used to indicate the current directory

     * and parent directory. In such file systems all occurrences of "{@code .}"

     * are considered redundant. If a "{@code ..}" is preceded by a

     * non-"{@code ..}" name then both names are considered redundant (the

     * process to identify such names is repeated until is it no longer

     * applicable).

     *

     * <p> This method does not access the file system; the path may not locate

     * a file that exists. Eliminating "{@code ..}" and a preceding name from a

     * path may result in the path that locates a different file than the original

     * path. This can arise when the preceding name is a symbolic link.

     *

     * @return  the resulting path or this path if it does not contain

     *          redundant name elements; an empty path is returned if this path

     *          does have a root component and all name elements are redundant

     *

     * @see #getParent

     * @see #toRealPath

     */

    Path normalize();

    // -- resolution and relativization --

    /**

     * Resolve the given path against this path.

     *

     * <p> If the {@code other} parameter is an {@link #isAbsolute() absolute}

     * path then this method trivially returns {@code other}. If {@code other}

     * is an <i>empty path</i> then this method trivially returns this path.

     * Otherwise this method considers this path to be a directory and resolves

     * the given path against this path. In the simplest case, the given path

     * does not have a {@link #getRoot root} component, in which case this method

     * <em>joins</em> the given path to this path and returns a resulting path

     * that {@link #endsWith ends} with the given path. Where the given path has

     * a root component then resolution is highly implementation dependent and

     * therefore unspecified.

     *

     * @param   other

     *          the path to resolve against this path

     *

     * @return  the resulting path

     *

     * @see #relativize

     */

    Path resolve(Path other);

    /**

     * Converts a given path string to a {@code Path} and resolves it against

     * this {@code Path} in exactly the manner specified by the {@link

     * #resolve(Path) resolve} method. For example, suppose that the name

     * separator is "{@code /}" and a path represents "{@code foo/bar}", then

     * invoking this method with the path string "{@code gus}" will result in

     * the {@code Path} "{@code foo/bar/gus}".

     *

     * @param   other

     *          the path string to resolve against this path

     *

     * @return  the resulting path

     *

     * @throws  InvalidPathException

     *          if the path string cannot be converted to a Path.

     *

     * @see FileSystem#getPath

     */

    Path resolve(String other);

    /**

     * Resolves the given path against this path's {@link #getParent parent}

     * path. This is useful where a file name needs to be <i>replaced</i> with

     * another file name. For example, suppose that the name separator is

     * "{@code /}" and a path represents "{@code dir1/dir2/foo}", then invoking

     * this method with the {@code Path} "{@code bar}" will result in the {@code

     * Path} "{@code dir1/dir2/bar}". If this path does not have a parent path,

     * or {@code other} is {@link #isAbsolute() absolute}, then this method

     * returns {@code other}. If {@code other} is an empty path then this method

     * returns this path's parent, or where this path doesn't have a parent, the

     * empty path.

     *

     * @param   other

     *          the path to resolve against this path's parent

     *

     * @return  the resulting path

     *

     * @see #resolve(Path)

     */

    Path resolveSibling(Path other);

    /**

     * Converts a given path string to a {@code Path} and resolves it against

     * this path's {@link #getParent parent} path in exactly the manner

     * specified by the {@link #resolveSibling(Path) resolveSibling} method.

     *

     * @param   other

     *          the path string to resolve against this path's parent

     *

     * @return  the resulting path

     *

     * @throws  InvalidPathException

     *          if the path string cannot be converted to a Path.

     *

     * @see FileSystem#getPath

     */

    Path resolveSibling(String other);

    /**

     * Constructs a relative path between this path and a given path.

     *

     * <p> Relativization is the inverse of {@link #resolve(Path) resolution}.

     * This method attempts to construct a {@link #isAbsolute relative} path

     * that when {@link #resolve(Path) resolved} against this path, yields a

     * path that locates the same file as the given path. For example, on UNIX,

     * if this path is {@code "/a/b"} and the given path is {@code "/a/b/c/d"}

     * then the resulting relative path would be {@code "c/d"}. Where this

     * path and the given path do not have a {@link #getRoot root} component,

     * then a relative path can be constructed. A relative path cannot be

     * constructed if only one of the paths have a root component. Where both

     * paths have a root component then it is implementation dependent if a

     * relative path can be constructed. If this path and the given path are

     * {@link #equals equal} then an <i>empty path</i> is returned.

     *

     * <p> For any two {@link #normalize normalized} paths <i>p</i> and

     * <i>q</i>, where <i>q</i> does not have a root component,

     * <blockquote>

     *   <i>p</i><tt>.relativize(</tt><i>p</i><tt>.resolve(</tt><i>q</i><tt>)).equals(</tt><i>q</i><tt>)</tt>

     * </blockquote>

     *

     * <p> When symbolic links are supported, then whether the resulting path,

     * when resolved against this path, yields a path that can be used to locate

     * the {@link Files#isSameFile same} file as {@code other} is implementation

     * dependent. For example, if this path is  {@code "/a/b"} and the given

     * path is {@code "/a/x"} then the resulting relative path may be {@code

     * "../x"}. If {@code "b"} is a symbolic link then is implementation

     * dependent if {@code "a/b/../x"} would locate the same file as {@code "/a/x"}.

     *

     * @param   other

     *          the path to relativize against this path

     *

     * @return  the resulting relative path, or an empty path if both paths are

     *          equal

     *

     * @throws  IllegalArgumentException

     *          if {@code other} is not a {@code Path} that can be relativized

     *          against this path

     */

    Path relativize(Path other);

    /**

     * Returns a URI to represent this path.

     *

     * <p> This method constructs a hierarchical {@link URI} that is absolute

     * with a non-empty path component. Its {@link URI#getScheme() scheme} is

     * equal to the URI scheme that identifies the provider. The exact form of

     * the other URI components is highly provider dependent. In particular, it

     * is implementation dependent if its query, fragment, and authority

     * components are defined or undefined.

     *

     * <p> For the default provider the {@link URI#getPath() path} component

     * will represent the {@link #toAbsolutePath absolute} path; the query,

     * fragment components are undefined. Whether the authority component is

     * defined or not is implementation dependent. There is no guarantee that

     * the {@code URI} may be used to construct a {@link java.io.File java.io.File}.

     * In particular, if this path represents a Universal Naming Convention (UNC)

     * path, then the UNC server name may be encoded in the authority component

     * of the resulting URI. In the case of the default provider, and the file

     * exists, and it can be determined that the file is a directory, then the

     * resulting {@code URI} will end with a slash.

     *

     * <p> The default provider provides a similar <em>round-trip</em> guarantee

     * to the {@link java.io.File} class. For a given {@code Path} <i>p</i> it

     * is guaranteed that

     * <blockquote><tt>

     * {@link Paths#get(URI) Paths.get}(</tt><i>p</i><tt>.toUri()).equals(</tt><i>p</i>

     * <tt>.{@link #toAbsolutePath() toAbsolutePath}())</tt>

     * </blockquote>

     * so long as the original {@code Path}, the {@code URI}, and the new {@code

     * Path} are all created in (possibly different invocations of) the same

     * Java virtual machine. Whether other providers make any guarantees is

     * provider specific and therefore unspecified.

     *

     * <p> When a file system is constructed to access the contents of a file

     * as a file system then it is highly implementation specific if the returned

     * URI represents the given path in the file system or it represents a

     * <em>compound</em> URI that encodes the URI of the enclosing file system.

     * A format for compound URIs is not defined in this release; such a scheme

     * may be added in a future release.

     *

     * @return  an absolute, hierarchical URI with a non-empty path component

     *

     * @throws  java.io.IOError

     *          if an I/O error occurs obtaining the absolute path, or where a

     *          file system is constructed to access the contents of a file as

     *          a file system, and the URI of the enclosing file system cannot be