/*

 * Copyright 2007-2009 Sun Microsystems, Inc.  All Rights Reserved.

 * 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.  Sun designates this

 * particular file as subject to the "Classpath" exception as provided

 * by Sun 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 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,

 * CA 95054 USA or visit www.sun.com if you need additional information or

 * have any questions.

 */

package java.nio.file;

import java.nio.file.attribute.*;

import java.nio.channels.*;

import java.io.*;

import java.net.URI;

import java.util.*;

/**

 * 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 names 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> Files may be {@link #createFile(FileAttribute[]) created}, or

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

 *     </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 link may be {@link #readSymbolicLink read}. </p></li>

 *   <li><p> {@link #newInputStream InputStream} or {@link #newOutputStream

 *     OutputStream} streams can be created to allow for interoperation with the

 *     <a href="../../../java/io/package-summary.html">{@code java.io}</a> package

 *     where required. </li></p>

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

 *

 * The <a href="attribute/package-summary.html">{@code java.nio.file.attribute}</a>

 * package provides 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 resulting 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> The {@code failIfNotExists} parameter determines how the method

     * behaves when the file does not exist. When {@code true}, and the file

     * does not exist, then the method fails. When {@code false} then the method

     * does not fail.

     *

     * <p> As with the {@link FileRef#delete delete()} method, 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 link is

     * deleted and not the final target of the link.

     *

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

     *

     * @param   failIfNotExists

     *          {@code true} if the method should fail when the file does not

     *          exist

     *

     * @throws  NoSuchFileException

     *          If the value of the {@code failIfNotExists} is {@code true} and

     *          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(boolean failIfNotExists) 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 link

     * @param   attrs

     *          The array of attributes to set atomically when creating the

     *          symbolic link

     *

     * @return  this path

     *

     * @throws  UnsupportedOperationException

     *          If the implementation does not support symbolic links or the

     *          array contains an attribute that cannot be set atomically when

     *          creating the symbolic link

     * @throws  FileAlreadyExistsException

     *          If a file with the name already exists <i>(optional specific

     *          exception)</i>

     * @throws  IOException

     *          If an I/O error occurs

     * @throws  SecurityException

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

     *          is installed, it denies {@link LinkPermission}<tt>("symbolic")</tt>

     *          or its {@link SecurityManager#checkWrite(String) checkWrite}

     *          method denies write access to the path of the symbolic link.

     */

    public abstract Path createSymbolicLink(Path target, FileAttribute<?>... attrs)

        throws IOException;

    /**

     * Creates a new link (directory entry) for an existing file <i>(optional

     * operation)</i>.

     *

     * <p> This path locates the directory entry to create. The {@code existing}

     * parameter is the path to an existing file. This method creates a new

     * directory entry for the file so that it can be accessed using this path.

     * On some file systems this is known as creating a "hard link". Whether the

     * file attributes are maintained for the file or for each directory entry

     * is file system specific and therefore not specified. Typically, a file

     * system requires that all links (directory entries) for a file be on the

     * same file system. Furthermore, on some platforms, the Java virtual machine

     * may require to be started with implementation specific privileges to

     * create hard links or to create links to directories.

     *

     * @param   existing

     *          A reference to an existing file

     *

     * @return  this path

     *

     * @throws  UnsupportedOperationException

     *          If the implementation does not support adding an existing file

     *          to a directory

     * @throws  FileAlreadyExistsException

     *          If the entry could not otherwise be created because a file of

     *          that name already exists <i>(optional specific exception)</i>