/*

 * 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;

import java.util.NoSuchElementException;

/**

 * 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 endsWith} 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>

 *

 * <h2>Accessing Files</h2>

 * <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");

 *     BufferedReader reader = Files.newBufferedReader(path, StandardCharsets.UTF_8);

 * </pre>

 *

 * <a id="interop"></a><h2>Interoperability</h2>

 * <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}.

 *

 * <h2>Concurrency</h2>

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

 * multiple concurrent threads.

 *

 * @since 1.7

 */

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 more than one element, 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}".

     *

     * @implSpec

     * The default implementation is equivalent for this path to:

     * <pre>{@code

     *     startsWith(getFileSystem().getPath(other));

     * }</pre>

     *

     * @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.

     */

    default boolean startsWith(String other) {

        return startsWith(getFileSystem().getPath(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}.

     *

     * @implSpec

     * The default implementation is equivalent for this path to:

     * <pre>{@code

     *     endsWith(getFileSystem().getPath(other));

     * }</pre>

     *

     * @param   other

     *          the given path string

     *

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

     *          {@code false}

     *

     * @throws  InvalidPathException

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

     */

    default boolean endsWith(String other) {

        return endsWith(getFileSystem().getPath(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 it is 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 not 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}".

     *

     * @implSpec

     * The default implementation is equivalent for this path to:

     * <pre>{@code