/*

 * Copyright (c) 2007, 2010, Oracle and/or its affiliates. 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.  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.file.spi.FileSystemProvider;

import java.nio.file.spi.FileTypeDetector;

import java.nio.channels.SeekableByteChannel;

import java.io.InputStream;

import java.io.OutputStream;

import java.io.Reader;

import java.io.Writer;

import java.io.BufferedReader;

import java.io.BufferedWriter;

import java.io.InputStreamReader;

import java.io.OutputStreamWriter;

import java.io.IOException;

import java.util.*;

import java.security.AccessController;

import java.security.PrivilegedAction;

import java.nio.charset.Charset;

import java.nio.charset.CharsetDecoder;

import java.nio.charset.CharsetEncoder;

/**

 * This class consists exclusively of static methods that operate on files,

 * directories, or other types of files.

 *

 * <p> In most cases, the methods defined here will delegate to the associated

 * file system provider to perform the file operations.

 *

 * @since 1.7

 */

public final class Files {

    private Files() { }

    /**

     * Returns the {@code FileSystemProvider} to delegate to.

     */

    private static FileSystemProvider provider(Path path) {

        return path.getFileSystem().provider();

    }

    // -- File contents --

    /**

     * Opens a file, returning an input stream to read from the file. The stream

     * will not be buffered, and is not required to support the {@link

     * InputStream#mark mark} or {@link InputStream#reset reset} methods. The

     * stream will be safe for access by multiple concurrent threads. Reading

     * commences at the beginning of the file. Whether the returned stream is

     * <i>asynchronously closeable</i> and/or <i>interruptible</i> is highly

     * file system provider specific and therefore not specified.

     *

     * <p> The {@code options} parameter determines how the file is opened.

     * If no options are present then it is equivalent to opening the file with

     * the {@link StandardOpenOption#READ READ} option. In addition to the {@code

     * READ} option, an implementation may also support additional implementation

     * specific options.

     *

     * @param   path

     *          the path to the file to open

     * @param   options

     *          options specifying how the file is opened

     *

     * @return  a new input stream

     *

     * @throws  IllegalArgumentException

     *          if an invalid combination of options is specified

     * @throws  UnsupportedOperationException

     *          if an unsupported option is specified

     * @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#checkRead(String) checkRead}

     *          method is invoked to check read access to the file.

     */

    public static InputStream newInputStream(Path path, OpenOption... options)

        throws IOException

    {

        return provider(path).newInputStream(path, options);

    }

    /**

     * Opens or creates a file, returning an output stream that may be used to

     * write bytes to the file. The resulting stream will not be buffered. The

     * stream will be safe for access by multiple concurrent threads. Whether

     * the returned stream is <i>asynchronously closeable</i> and/or

     * <i>interruptible</i> is highly file system provider specific and

     * therefore not specified.

     *

     * <p> This method opens or creates a file in exactly the manner specified

     * by the {@link #newByteChannel(Path,Set,FileAttribute[]) newByteChannel}

     * method with the exception that the {@link StandardOpenOption#READ READ}

     * option may not be present in the array of options. If no options are

     * present then this method works as if the {@link StandardOpenOption#CREATE

     * CREATE}, {@link StandardOpenOption#TRUNCATE_EXISTING TRUNCATE_EXISTING},

     * and {@link StandardOpenOption#WRITE WRITE} options are present. In other

     * words, it opens the file for writing, creating the file if it doesn't

     * exist, or initially truncating an existing {@link #isRegularFile

     * regular-file} to a size of {@code 0} if it exists.

     *

     * <p> <b>Usage Examples:</b>

     * <pre>

     *     Path path = ...

     *

     *     // truncate and overwrite an existing file, or create the file if

     *     // it doesn't initially exist

     *     OutputStream out = Files.newOutputStream(path);

     *

     *     // append to an existing file, fail if the file does not exist

     *     out = Files.newOutputStream(path, APPEND);

     *

     *     // append to an existing file, create file if it doesn't initially exist

     *     out = Files.newOutputStream(path, CREATE, APPEND);

     *

     *     // always create new file, failing if it already exists

     *     out = Files.newOutputStream(path, CREATE_NEW);

     * </pre>

     *

     * @param   path

     *          the path to the file to open or create

     * @param   options

     *          options specifying how the file is opened

     *

     * @return  a new output stream

     *

     * @throws  IllegalArgumentException

     *          if {@code options} contains an invalid combination of options

     * @throws  UnsupportedOperationException

     *          if an unsupported option is specified

     * @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#checkWrite(String) checkWrite}

     *          method is invoked to check write access to the file. The {@link

     *          SecurityManager#checkDelete(String) checkDelete} method is

     *          invoked to check delete access if the file is opened with the

     *          {@code DELETE_ON_CLOSE} option.

     */

    public static OutputStream newOutputStream(Path path, OpenOption... options)

        throws IOException

    {

        return provider(path).newOutputStream(path, options);

    }

    /**

     * Opens or creates a file, returning a seekable byte channel to access the

     * file.

     *

     * <p> The {@code options} parameter determines how the file is opened.

     * The {@link StandardOpenOption#READ READ} and {@link

     * StandardOpenOption#WRITE WRITE} options determine if the file should be

     * opened for reading and/or writing. If neither option (or the {@link

     * StandardOpenOption#APPEND APPEND} option) is present then the file is

     * opened for reading. By default reading or writing commence at the

     * beginning of the file.

     *

     * <p> In the addition to {@code READ} and {@code WRITE}, the following

     * options may be present:

     *

     * <table border=1 cellpadding=5 summary="">

     * <tr> <th>Option</th> <th>Description</th> </tr>

     * <tr>

     *   <td> {@link StandardOpenOption#APPEND APPEND} </td>

     *   <td> If this option is present then the file is opened for writing and

     *     each invocation of the channel's {@code write} method first advances

     *     the position to the end of the file and then writes the requested

     *     data. Whether the advancement of the position and the writing of the

     *     data are done in a single atomic operation is system-dependent and

     *     therefore unspecified. This option may not be used in conjunction

     *     with the {@code READ} or {@code TRUNCATE_EXISTING} options. </td>

     * </tr>

     * <tr>

     *   <td> {@link StandardOpenOption#TRUNCATE_EXISTING TRUNCATE_EXISTING} </td>

     *   <td> If this option is present then the existing file is truncated to

     *   a size of 0 bytes. This option is ignored when the file is opened only

     *   for reading. </td>

     * </tr>

     * <tr>

     *   <td> {@link StandardOpenOption#CREATE_NEW CREATE_NEW} </td>

     *   <td> If this option is present then a new file is created, failing if

     *   the file already exists or is a symbolic link. When creating a file the

     *   check for the existence of the file and the creation of the file if it

     *   does not exist is atomic with respect to other file system operations.

     *   This option is ignored when the file is opened only for reading. </td>

     * </tr>

     * <tr>

     *   <td > {@link StandardOpenOption#CREATE CREATE} </td>

     *   <td> If this option is present then an existing file is opened if it

     *   exists, otherwise a new file is created. This option is ignored if the

     *   {@code CREATE_NEW} option is also present or the file is opened only

     *   for reading. </td>

     * </tr>

     * <tr>

     *   <td > {@link StandardOpenOption#DELETE_ON_CLOSE DELETE_ON_CLOSE} </td>

     *   <td> When this option is present then the implementation makes a

     *   <em>best effort</em> attempt to delete the file when closed by the

     *   {@link SeekableByteChannel#close close} method. If the {@code close}

     *   method is not invoked then a <em>best effort</em> attempt is made to

     *   delete the file when the Java virtual machine terminates. </td>

     * </tr>

     * <tr>

     *   <td>{@link StandardOpenOption#SPARSE SPARSE} </td>

     *   <td> When creating a new file this option is a <em>hint</em> that the

     *   new file will be sparse. This option is ignored when not creating

     *   a new file. </td>

     * </tr>

     * <tr>

     *   <td> {@link StandardOpenOption#SYNC SYNC} </td>

     *   <td> Requires that every update to the file's content or metadata be

     *   written synchronously to the underlying storage device. (see <a

     *   href="package-summary.html#integrity"> Synchronized I/O file

     *   integrity</a>). </td>

     * <tr>

     * <tr>

     *   <td> {@link StandardOpenOption#DSYNC DSYNC} </td>

     *   <td> Requires that every update to the file's content be written

     *   synchronously to the underlying storage device. (see <a

     *   href="package-summary.html#integrity"> Synchronized I/O file

     *   integrity</a>). </td>

     * </tr>

     * </table>

     *

     * <p> An implementation may also support additional implementation specific

     * options.

     *

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

     * file-attributes} to set atomically when a new file is created.

     *

     * <p> In the case of the default provider, the returned seekable byte channel

     * is a {@link java.nio.channels.FileChannel}.

     *

     * <p> <b>Usage Examples:</b>

     * <pre>

     *     Path path = ...

     *

     *     // open file for reading

     *     ReadableByteChannel rbc = Files.newByteChannel(path, EnumSet.of(READ)));

     *

     *     // open file for writing to the end of an existing file, creating

     *     // the file if it doesn't already exist

     *     WritableByteChannel wbc = Files.newByteChannel(path, EnumSet.of(CREATE,APPEND));

     *

     *     // create file with initial permissions, opening it for both reading and writing

     *     {@code FileAttribute<<SetPosixFilePermission>> perms = ...}

     *     SeekableByteChannel sbc = Files.newByteChannel(path, EnumSet.of(CREATE_NEW,READ,WRITE), perms);

     * </pre>

     *

     * @param   path

     *          the path to the file to open or create

     * @param   options

     *          options specifying how the file is opened

     * @param   attrs

     *          an optional list of file attributes to set atomically when

     *          creating the file

     *

     * @return  a new seekable byte channel

     *

     * @throws  IllegalArgumentException

     *          if the set contains an invalid combination of options

     * @throws  UnsupportedOperationException

     *          if an unsupported open option is specified or the array contains

     *          attributes that cannot be set atomically when creating the file

     * @throws  FileAlreadyExistsException

     *          if a file of that name already exists and the {@link

     *          StandardOpenOption#CREATE_NEW CREATE_NEW} option is specified

     *          <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#checkRead(String) checkRead}

     *          method is invoked to check read access to the path if the file is

     *          opened for reading. The {@link SecurityManager#checkWrite(String)

     *          checkWrite} method is invoked to check write access to the path

     *          if the file is opened for writing. The {@link

     *          SecurityManager#checkDelete(String) checkDelete} method is

     *          invoked to check delete access if the file is opened with the

     *          {@code DELETE_ON_CLOSE} option.

     *

     * @see java.nio.channels.FileChannel#open(Path,Set,FileAttribute[])

     */

    public static SeekableByteChannel newByteChannel(Path path,

                                                     Set<? extends OpenOption> options,

                                                     FileAttribute<?>... attrs)

        throws IOException

    {

        return provider(path).newByteChannel(path, options, attrs);

    }

    /**

     * Opens or creates a file, returning a seekable byte channel to access the

     * file.

     *

     * <p> This method opens or creates a file in exactly the manner specified

     * by the {@link #newByteChannel(Path,Set,FileAttribute[]) newByteChannel}

     * method.

     *

     * @param   path

     *          the path to the file to open or create

     * @param   options

     *          options specifying how the file is opened

     *

     * @return  a new seekable byte channel

     *

     * @throws  IllegalArgumentException

     *          if the set contains an invalid combination of options

     * @throws  UnsupportedOperationException

     *          if an unsupported open option is specified

     * @throws  FileAlreadyExistsException

     *          if a file of that name already exists and the {@link

     *          StandardOpenOption#CREATE_NEW CREATE_NEW} option is specified

     *          <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#checkRead(String) checkRead}

     *          method is invoked to check read access to the path if the file is

     *          opened for reading. The {@link SecurityManager#checkWrite(String)

     *          checkWrite} method is invoked to check write access to the path

     *          if the file is opened for writing. The {@link

     *          SecurityManager#checkDelete(String) checkDelete} method is

     *          invoked to check delete access if the file is opened with the

     *          {@code DELETE_ON_CLOSE} option.

     *

     * @see java.nio.channels.FileChannel#open(Path,OpenOption[])

     */

    public static SeekableByteChannel newByteChannel(Path path, OpenOption... options)

        throws IOException

    {

        Set<OpenOption> set = new HashSet<OpenOption>(options.length);

        Collections.addAll(set, options);

        return newByteChannel(path, set);

    }

    // -- Directories --

    /**

     * Opens a directory, returning a {@link DirectoryStream} to iterate over

     * all entries in the directory. The elements returned by the directory

     * stream's {@link DirectoryStream#iterator iterator} are of type {@code

     * Path}, each one representing an entry in the directory. The {@code Path}

     * objects are obtained as if by {@link Path#resolve(Path) resolving} the

     * name of the directory entry against {@code dir}.

     *

     * <p> When not using the try-with-resources construct, then directory

     * stream's {@code close} method should be invoked after iteration is

     * completed so as to free any resources held for the open directory.

     *

     * <p> When an implementation supports operations on entries in the

     * directory that execute in a race-free manner then the returned directory

     * stream is a {@link SecureDirectoryStream}.

     *

     * @param   dir

     *          the path to the directory

     *

     * @return  a new and open {@code DirectoryStream} object

     *

     * @throws  NotDirectoryException

     *          if the file could not otherwise be opened because it is not

     *          a directory <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#checkRead(String) checkRead}

     *          method is invoked to check read access to the directory.

     */

    public static DirectoryStream<Path> newDirectoryStream(Path dir)

        throws IOException

    {

        return provider(dir).newDirectoryStream(dir, new DirectoryStream.Filter<Path>() {

            @Override

            public boolean accept(Path entry) {

                return true;

            }

        });

    }

    /**

     * Opens a directory, returning a {@link DirectoryStream} to iterate over

     * the entries in the directory. The elements returned by the directory

     * stream's {@link DirectoryStream#iterator iterator} are of type {@code

     * Path}, each one representing an entry in the directory. The {@code Path}

     * objects are obtained as if by {@link Path#resolve(Path) resolving} the

     * name of the directory entry against {@code dir}. The entries returned by

     * the iterator are filtered by matching the {@code String} representation

     * of their file names against the given <em>globbing</em> pattern.

     *

     * <p> For example, suppose we want to iterate over the files ending with

     * ".java" in a directory:

     * <pre>

     *     Path dir = ...

     *     try (DirectoryStream<Path> stream = Files.newDirectoryStream(dir, "*.java")) {

     *         :

     *     }

     * </pre>

     *

     * <p> The globbing pattern is specified by the {@link

     * FileSystem#getPathMatcher getPathMatcher} method.

     *

     * <p> When not using the try-with-resources construct, then directory

     * stream's {@code close} method should be invoked after iteration is

     * completed so as to free any resources held for the open directory.

     *

     * <p> When an implementation supports operations on entries in the

     * directory that execute in a race-free manner then the returned directory

     * stream is a {@link SecureDirectoryStream}.

     *

     * @param   dir

     *          the path to the directory

     * @param   glob

     *          the glob pattern

     *

     * @return  a new and open {@code DirectoryStream} object

     *

     * @throws  java.util.regex.PatternSyntaxException

     *          if the pattern is invalid

     * @throws  NotDirectoryException

     *          if the file could not otherwise be opened because it is not

     *          a directory <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#checkRead(String) checkRead}

     *          method is invoked to check read access to the directory.

     */

    public static DirectoryStream<Path> newDirectoryStream(Path dir, String glob)

        throws IOException

    {

        // avoid creating a matcher if all entries are required.

        if (glob.equals("*"))

            return newDirectoryStream(dir);

        // create a matcher and return a filter that uses it.

        FileSystem fs = dir.getFileSystem();

        final PathMatcher matcher = fs.getPathMatcher("glob:" + glob);

        DirectoryStream.Filter<Path> filter = new DirectoryStream.Filter<Path>() {

            @Override

            public boolean accept(Path entry)  {

                return matcher.matches(entry.getFileName());

            }

        };

        return fs.provider().newDirectoryStream(dir, filter);

    }

    /**

     * Opens a directory, returning a {@link DirectoryStream} to iterate over

     * the entries in the directory. The elements returned by the directory

     * stream's {@link DirectoryStream#iterator iterator} are of type {@code

     * Path}, each one representing an entry in the directory. The {@code Path}

     * objects are obtained as if by {@link Path#resolve(Path) resolving} the

     * name of the directory entry against {@code dir}. The entries returned by

     * the iterator are filtered by the given {@link DirectoryStream.Filter

     * filter}.

     *

     * <p> When not using the try-with-resources construct, then directory

     * stream's {@code close} method should be invoked after iteration is

     * completed so as to free any resources held for the open directory.

     *

     * <p> Where the filter terminates due to an uncaught error or runtime

     * exception then it is propagated to the {@link Iterator#hasNext()

     * hasNext} or {@link Iterator#next() next} method. Where an {@code

     * IOException} is thrown, it results in the {@code hasNext} or {@code

     * next} method throwing a {@link DirectoryIteratorException} with the

     * {@code IOException} as the cause.

     *