/*

 * 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.nio.file.attribute.*;

import java.nio.channels.SeekableByteChannel;

import java.io.IOException;

import java.io.OutputStream;

import java.net.URI;

import java.util.Iterator;

import java.util.Set;

/**

 * A file reference that locates a file using a system dependent path. The file

 * is not required to exist.

 *

 * <p> On many platforms a <em>path</em> is the means to locate and access files

 * in a file system. A path is hierarchical and composed of a sequence of

 * directory and file name elements separated by a special separator or

 * delimiter.

 *

 * <h4>Path operations</h4>

 *

 * <p> A system dependent path represented by this class is conceptually a

 * sequence of name elements and optionally a <em>root component</em>. The name

 * that is <em>farthest</em> from the root of the directory hierarchy is the

 * name of a file or directory. The other elements are directory names. The root

 * component typically identifies a file system hierarchy. A {@code Path} can

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

 * elements. It defines the {@link #getName() getName}, {@link #getParent

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

 * to access the components or a subsequence of its name elements.

 *

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

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

 * operations. Paths can also be {@link #compareTo compared}, and tested

 * against each other using using the {@link #startsWith startsWith} and {@link

 * #endsWith endWith} methods.

 *

 * <h4>File operations</h4>

 *

 * <p> A {@code Path} is either <em>absolute</em> or <em>relative</em>. An

 * absolute path is complete in that does not need to be combined with another

 * path in order to locate a file. All operations on relative paths are first

 * resolved against a file system's default directory as if by invoking the

 * {@link #toAbsolutePath toAbsolutePath} method.

 *

 * <p> In addition to the operations defined by the {@link FileRef} interface,

 * this class defines the following operations:

 *

 * <ul>

 *   <li><p> The {@link #newByteChannel newByteChannel} method

 *     may be used to open a file and obtain a byte channel for reading or

 *     writing. </p></li>

 *   <li><p> Files may be {@link #createFile(FileAttribute[]) created}, or

 *     directories may be {@link #createDirectory(FileAttribute[]) created}.

 *     </p></li>

 *   <li><p> The {@link #delete delete} method may be used to delete a file.

 *     </p></li>

 *   <li><p> The {@link #checkAccess checkAccess} method may be used to check

 *     the existence or accessibility of a file. </p></li>

 *   <li><p> The {@link #isSameFile isSameFile} method may be used to test if

 *     two file references locate the same file. </p></li>

 *   <li><p> The {@link #getFileStore getFileStore} method may be used to

 *     obtain the {@link FileStore} representing the storage where a file is

 *     located. </p></li>

 *   <li><p> Directories can be {@link #newDirectoryStream opened} so as to

 *      iterate over the entries in the directory. </p></li>

 *   <li><p> Files can be {@link #copyTo(Path,CopyOption[]) copied} or

 *     {@link #moveTo(Path,CopyOption[]) moved}. </p></li>

 *   <li><p> Symbolic links may be {@link #createSymbolicLink created}, or the

 *     target of a symbolic link may be {@link #readSymbolicLink read}. </p></li>

 *   <li><p> The {@link #toRealPath real} path of an existing file may be

 *     obtained. </li></p>

 * </ul>

 *

 * <p> This class implements {@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.

 *

 * <h4>File attributes</h4>

 *

 * In addition to the {@link #setAttribute setAttribute} and {@link #getAttribute

 * getAttribute} methods, the <a href="attribute/package-summary.html">{@code

 * java.nio.file.attribute}</a> package provides type-safe and efficient access

 * to file attributes or <em>meta-data</em> associated with files. The {@link

 * Attributes Attributes} class defines methods that operate on or return file

 * attributes. For example, the file type, size, timestamps, and other

 * <em>basic</em> meta-data are obtained, in bulk, by invoking the {@link

 * Attributes#readBasicFileAttributes Attributes.readBasicFileAttributes} method:

 * <pre>

 *     Path file = ...

 *     BasicFileAttributes attrs = Attributes.readBasicFileAttributes(file);

 * </pre>

 *

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

 *

 * <p> Paths created by file systems 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

 * File.toPath} method may be used to obtain a {@code Path} from the abstract

 * path name represented by a {@code java.io.File java.io.File} object. The

 * resulting {@code Path} can be used to operate on the same file as the {@code

 * java.io.File} object.

 *

 * <p> Path objects created by file systems associated with the default

 * provider are interoperable with objects created by other file systems created

 * by the same provider. Path objects created by file systems associated with

 * other providers may not be interoperable with other file systems created by

 * the same provider. The reasons for this are provider specific.

 *

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

 *

 * <p> Instances of this class are immutable and safe for use by multiple concurrent

 * threads.

 *

 * @since 1.7

 */

public abstract class Path

    implements FileRef, Comparable<Path>, Iterable<Path>, Watchable

{

    /**

     * Initializes a new instance of this class.

     */

    protected Path() { }

    /**

     * Returns the file system that created this object.

     *

     * @return  the file system that created this object

     */

    public abstract 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

     */

    public abstract 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}

     */

    public abstract Path getRoot();

    /**

     * Returns the name of the file or directory denoted by this path. 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

     */

    public abstract Path getName();

    /**

     * 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

     */

    public abstract 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

     */

    public abstract int getNameCount();

   /**

     * Returns a name element of this path.

     *

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

     */

    public abstract 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.

     */

    public abstract 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.

     *

     * @param   other

     *          the given path

     *

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

     *          {@code false}

     */

    public abstract boolean startsWith(Path 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.

     *

     * @param   other

     *          the given path

     *

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

     *          {@code false}

     */

    public abstract boolean endsWith(Path 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, or {@code null} if this path does not

     *          have a root component and all name elements are redundant

     *

     * @see #getParent

     * @see #toRealPath

     */

    public abstract 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 {@code null} then this path is returned. 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; can be {@code null}

     *

     * @return  the resulting path

     *

     * @see #relativize

     */

    public abstract 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.

     *

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

     */

    public abstract Path resolve(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 {@code null} is returned.

     *

     * <p> For any two 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 #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 {@code null} if both paths are

     *          equal

     *

     * @throws  IllegalArgumentException

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

     *          against this path

     */

    public abstract Path relativize(Path other);

    // -- file operations --

    /**

     * Deletes the file located by this path.

     *

     * <p> An implementation may require to examine the file to determine if the

     * file is a directory. Consequently this method may not be atomic with respect

     * to other file system operations.  If the file is a symbolic link then the

     * symbolic link itself, not the final target of the link, is deleted.

     *

     * <p> If the file is a directory then the directory must be empty. In some

     * implementations a directory has entries for special files or links that

     * are created when the directory is created. In such implementations a

     * directory is considered empty when only the special entries exist.

     *

     * <p> On some operating systems it may not be possible to remove a file when

     * it is open and in use by this Java virtual machine or other programs.

     *

     * @throws  NoSuchFileException

     *          if the file does not exist <i>(optional specific exception)</i>

     * @throws  DirectoryNotEmptyException

     *          if the file is a directory and could not otherwise be deleted

     *          because the directory is not empty <i>(optional specific

     *          exception)</i>

     * @throws  IOException

     *          if an I/O error occurs

     * @throws  SecurityException

     *          In the case of the default provider, and a security manager is

     *          installed, the {@link SecurityManager#checkDelete(String)} method

     *          is invoked to check delete access to the file

     */

    public abstract void delete() throws IOException;

    /**

     * Deletes the file located by this path, if it exists.

     *

     * <p> As with the {@link #delete delete()} method, an implementation may

     * need to examine the file to determine if the file is a directory.

     * Consequently this method may not be atomic with respect to other file

     * system operations.  If the file is a symbolic link, then the symbolic

     * link itself, not the final target of the link, is deleted.

     *

     * <p> If the file is a directory then the directory must be empty. In some

     * implementations a directory has entries for special files or links that

     * are created when the directory is created. In such implementations a

     * directory is considered empty when only the special entries exist.

     *

     * <p> On some operating systems it may not be possible to remove a file when

     * it is open and in use by this Java virtual machine or other programs.

     *

     * @throws  DirectoryNotEmptyException

     *          if the file is a directory and could not otherwise be deleted

     *          because the directory is not empty <i>(optional specific

     *          exception)</i>

     * @throws  IOException

     *          if an I/O error occurs

     * @throws  SecurityException

     *          In the case of the default provider, and a security manager is

     *          installed, the {@link SecurityManager#checkDelete(String)} method

     *          is invoked to check delete access to the file.

     */

    public abstract void deleteIfExists() throws IOException;

    /**

     * Creates a symbolic link to a target <i>(optional operation)</i>.

     *

     * <p> The {@code target} parameter is the target of the link. It may be an

     * {@link Path#isAbsolute absolute} or relative path and may not exist. When

     * the target is a relative path then file system operations on the resulting

     * link are relative to the path of the link.

     *

     * <p> The {@code attrs} parameter is an optional array of {@link FileAttribute

     * attributes} to set atomically when creating the link. Each attribute is

     * identified by its {@link FileAttribute#name name}. If more than one attribute

     * of the same name is included in the array then all but the last occurrence

     * is ignored.

     *

     * <p> Where symbolic links are supported, but the underlying {@link FileStore}

     * does not support symbolic links, then this may fail with an {@link

     * IOException}. Additionally, some operating systems may require that the

     * Java virtual machine be started with implementation specific privileges to

     * create symbolic links, in which case this method may throw {@code IOException}.

     *

     * @param   target

     *          the target of the symbolic link

     * @param   attrs

     *          the array of attributes to set atomically when creating the

     *          symbolic link

     *

     * @return  this path