/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.apache.commons.vfs2;

import java.io.Closeable;
import java.net.URI;
import java.net.URL;
import java.nio.file.Path;
import java.nio.file.Paths;
import java.util.Comparator;
import java.util.List;

import org.apache.commons.vfs2.operations.FileOperations;

/**
 * Represents a file, and is used to access the content and structure of the file.
 * <p>
 * Files are arranged in a hierarchy. Each hierarchy forms a <em>file system</em>. A file system represents things like a
 * local OS file system, a windows share, an HTTP server, or the contents of a Zip file.
 * </p>
 * <p>
 * There are two types of files: <em>Folders</em>, which contain other files, and <em>normal files</em>, which contain data,
 * or <em>content</em>. A folder may not have any content, and a normal file cannot contain other files.
 * </p>
 *
 * <h2>File Naming</h2>
 *
 * <p>
 * TODO - write this.
 * </p>
 *
 * <h2>Reading and Writing a File</h2>
 *
 * <p>
 * Reading and writing a file, and all other operations on the file's <em>content</em>, is done using the
 * {@link FileContent} object returned by {@link #getContent}.
 * </p>
 *
 * <h2>Creating and Deleting a File</h2>
 *
 * <p>
 * A file is created using either {@link #createFolder}, {@link #createFile}, or by writing to the file using one of the
 * {@link FileContent} methods.
 * </p>
 * <p>
 * A file is deleted using {@link #delete}. Recursive deletion can be done using {@link #delete(FileSelector)}.
 * </p>
 *
 * <h2>Finding Files</h2>
 *
 * <p>
 * Other files in the <em>same</em> file system as this file can be found using:
 * </p>
 * <ul>
 * <li>{@link #findFiles} to find a set of matching descendants in the same file system.</li>
 * <li>{@link #getChildren} and {@link #getChild} to find the children of this file.</li>
 * <li>{@link #getParent} to find the folder containing this file.</li>
 * <li>{@link #getFileSystem} to find another file in the same file system.</li>
 * <li>{@link #resolveFile} to find another file relative to this file.</li>
 * </ul>
 * <p>
 * To find files in another file system, use a {@link FileSystemManager}.
 * </p>
 *
 * <h2>Iterating Files</h2>
 *
 * <p>
 * You can iterate over a FileObject using the Java "foreach" statement, which provides all descendants of a File
 * Object.
 * </p>
 *
 * <h2>Sorting Files</h2>
 *
 * <p>
 * Files may be sorted using {@link java.util.Arrays#sort(Object[]) Arrays.sort()} and
 * {@link List#sort(Comparator) List.sort()}.
 * </p>
 *
 * @see FileSystemManager
 * @see FileContent
 * @see FileName
 */
public interface FileObject extends Comparable<FileObject>, Iterable<FileObject>, Closeable {

    /**
     * An empty immutable {@code FileObject} array.
     *
     * @since 2.8.0
     */
    FileObject[] EMPTY_ARRAY = {};

    /**
     * Closes the given file object.
     *
     * @param fileObject a file object, may be null.
     * @throws FileSystemException See {@link FileObject#close()}.
     * @since 2.11.0
     */
    static void close(final FileObject fileObject) throws FileSystemException {
        if (fileObject != null) {
            fileObject.close();
        }
    }

    /**
     * Queries the file if it is possible to rename it to newfile.
     *
     * @param newfile the new file(-name)
     * @return true it this is the case
     */
    boolean canRenameTo(FileObject newfile);

    /**
     * Closes this file, and its content. This method is a hint to the implementation that it can release any resources
     * associated with the file.
     * <p>
     * The file object can continue to be used after this method is called.
     * </p>
     *
     * @throws FileSystemException On error closing the file.
     * @see FileContent#close
     */
    @Override
    void close() throws FileSystemException;

    /**
     * Copies another file, and all its descendants, to this file.
     * <p>
     * If this file does not exist, it is created. Its parent folder is also created, if necessary. If this file does
     * exist, it is deleted first.
     * </p>
     * <p>
     * This method is not transactional. If it fails and throws an exception, this file will potentially only be
     * partially copied.
     * </p>
     *
     * @param srcFile The source file to copy.
     * @param selector The selector to use to select which files to copy.
     * @throws FileSystemException If this file is read-only, or if the source file does not exist, or on error copying
     *             the file.
     */
    void copyFrom(FileObject srcFile, FileSelector selector) throws FileSystemException;

    /**
     * Creates this file, if it does not exist. Also creates any ancestor folders which do not exist. This method does
     * nothing if the file already exists and is a file.
     *
     * @throws FileSystemException If the file already exists with the wrong type, or the parent folder is read-only, or
     *             on error creating this file or one of its ancestors.
     */
    void createFile() throws FileSystemException;

    /**
     * Creates this folder, if it does not exist. Also creates any ancestor folders which do not exist. This method does
     * nothing if the folder already exists.
     *
     * @throws FileSystemException If the folder already exists with the wrong type, or the parent folder is read-only,
     *             or on error creating this folder or one of its ancestors.
     */
    void createFolder() throws FileSystemException;

    /**
     * Deletes this file. Does nothing if this file does not exist of if it is a folder that has children. Does not
     * delete any descendants of this file, use {@link #delete(FileSelector)} or {@link #deleteAll()} for that.
     *
     * @return true if this object has been deleted
     * @throws FileSystemException If this file is a non-empty folder, or if this file is read-only, or on error
     *             deleteing this file.
     */
    boolean delete() throws FileSystemException;

    /**
     * Deletes all descendants of this file that match a selector. Does nothing if this file does not exist.
     *
     * <p>
     * This method is not transactional. If it fails and throws an exception, this file will potentially only be
     * partially deleted.
     * </p>
     *
     * @param selector The selector to use to select which files to delete.
     * @return the number of deleted objects
     * @throws FileSystemException If this file or one of its descendants is read-only, or on error deleting this file
     *             or one of its descendants.
     */
    int delete(FileSelector selector) throws FileSystemException;

    /**
     * Deletes this file and all children.
     *
     * @return the number of deleted files.
     * @throws FileSystemException if an error occurs.
     * @see #delete(FileSelector)
     * @see Selectors#SELECT_ALL
     */
    int deleteAll() throws FileSystemException;

    /**
     * Determines if this file exists.
     *
     * @return {@code true} if this file exists, {@code false} if not.
     * @throws FileSystemException On error determining if this file exists.
     */
    boolean exists() throws FileSystemException;

    /**
     * Finds the set of matching descendants of this file, in depthwise order.
     *
     * @param selector The selector to use to select matching files.
     * @return The matching files. The files are returned in depthwise order (that is, a child appears in the list
     *         before its parent).
     * @throws FileSystemException if an error occurs.
     */
    FileObject[] findFiles(FileSelector selector) throws FileSystemException;

    /**
     * Finds the set of matching descendants of this file.
     *
     * @param selector the selector used to determine if the file should be selected
     * @param depthwise controls the ordering in the list. e.g. deepest first
     * @param selected container for selected files. list needs not to be empty.
     * @throws FileSystemException if an error occurs.
     */
    void findFiles(FileSelector selector, boolean depthwise, List<FileObject> selected) throws FileSystemException;

    /**
     * Gets a child of this file. Note that this method returns {@code null} when the child does not exist. This
     * differs from {@link #resolveFile(String, NameScope)} which never returns null.
     *
     * @param name The name of the child.
     * @return The child, or null if there is no such child.
     * @throws FileSystemException If this file does not exist, or is not a folder, or on error determining this file's
     *             children.
     */
    FileObject getChild(String name) throws FileSystemException;

    /**
     * Gets a lists of children of this file.
     *
     * @return An array containing the children of this file. The array is unordered. If the file does not have any
     *         children, a zero-length array is returned. This method never returns null.
     * @throws FileSystemException If this file does not exist, or is not a folder, or on error listing this file's
     *             children.
     */
    FileObject[] getChildren() throws FileSystemException;

    /**
     * Gets this file's content. The {@link FileContent} returned by this method can be used to read and write the
     * content of the file.
     *
     * <p>
     * This method can be called if the file does not exist, and the returned {@link FileContent} can be used to create
     * the file by writing its content.
     * </p>
     *
     * @return This file's content.
     * @throws FileSystemException On error getting this file's content.
     */
    FileContent getContent() throws FileSystemException;

    /**
     * Gets this instance's FileOperations.
     *
     * @return FileOperations interface that provides access to the operations API.
     * @throws FileSystemException if an error occurs.
     */
    FileOperations getFileOperations() throws FileSystemException;

    /**
     * Gets the file system that contains this file.
     *
     * @return The file system.
     */
    FileSystem getFileSystem();

    /**
     * Gets the name of this file.
     *
     * @return the FileName, not {@code null}.
     */
    FileName getName();

    /**
     * Gets the folder that contains this file.
     *
     * @return The folder that contains this file. Returns null if this file is the root of a file system.
     * @throws FileSystemException On error finding the file's parent.
     */
    FileObject getParent() throws FileSystemException;

    /**
     * Gets a Path representing this file.
     *
     * @return the Path for the file.
     * @since 2.7.0
     */
    default Path getPath() {
        return Paths.get(getURI());
    }

    /**
     * Gets the receiver as a URI String for public display, like, without a password.
     *
     * @return A URI String without a password, never {@code null}.
     */
    String getPublicURIString();

    /**
     * Gets this file's type.
     *
     * @return One of the {@link FileType} constants. Never returns null.
     * @throws FileSystemException On error determining the file's type.
     */
    FileType getType() throws FileSystemException;

    /**
     * Gets a URI representing this file.
     *
     * @return the URI for the file, not {@code null}.
     * @since 2.7.0
     */
    default URI getURI() {
        return URI.create(URI.create(getName().getURI()).toASCIIString());
    }

    /**
     * Gets a URL representing this file.
     *
     * @return the URL for the file.
     * @throws FileSystemException if an error occurs.
     */
    URL getURL() throws FileSystemException;

    /**
     * Tests whether the fileObject is attached.
     *
     * @return true if the FileObject is attached.
     */
    boolean isAttached();

    /**
     * Tests whether someone reads/write to this file.
     *
     * @return true if the file content is open.
     */
    boolean isContentOpen();

    /**
     * Tests whether this file is executable.
     *
     * @return {@code true} if this file is executable, {@code false} if not.
     * @throws FileSystemException On error determining if this file exists.
     */
    boolean isExecutable() throws FileSystemException;

    /**
     * Tests whether this file is a regular file.
     *
     * @return true if this file is a regular file.
     * @throws FileSystemException if an error occurs.
     * @see #getType()
     * @see FileType#FILE
     * @since 2.1
     */
    boolean isFile() throws FileSystemException;

    /**
     * Tests whether this file is a folder.
     *
     * @return true if this file is a folder.
     * @throws FileSystemException if an error occurs.
     * @see #getType()
     * @see FileType#FOLDER
     * @since 2.1
     */
    boolean isFolder() throws FileSystemException;

    /**
     * Tests whether this file is hidden.
     *
     * @return {@code true} if this file is hidden, {@code false} if not.
     * @throws FileSystemException On error determining if this file exists.
     */
    boolean isHidden() throws FileSystemException;

    /**
     * Tests whether this file can be read.
     *
     * @return {@code true} if this file is readable, {@code false} if not.
     * @throws FileSystemException On error determining if this file exists.
     */
    boolean isReadable() throws FileSystemException;

    /**
     * Tests whether this file is a symbolic link.
     *
     * @return {@code true} if this file is a symbolic link, {@code false} if not.
     * @throws FileSystemException On error determining if this file exists.
     * @since 2.4
     */
    @SuppressWarnings("unused") // FileSystemException actually thrown in implementations.
    default boolean isSymbolicLink() throws FileSystemException {
        return false;
    }

    /**
     * Tests whether this file can be written to.
     *
     * @return {@code true} if this file is writable, {@code false} if not.
     * @throws FileSystemException On error determining if this file exists.
     */
    boolean isWriteable() throws FileSystemException;

    /**
     * Move this file.
     *
     * <p>
     * If the destFile exists, it is deleted first.
     * </p>
     *
     * @param destFile the New file name.
     * @throws FileSystemException If this file is read-only, or if the source file does not exist, or on error copying
     *             the file.
     */
    void moveTo(FileObject destFile) throws FileSystemException;

    /**
     * This will prepare the fileObject to get resynchronized with the underlying file system if required.
     *
     * @throws FileSystemException if an error occurs.
     */
    void refresh() throws FileSystemException;

    /**
     * Finds a file, relative to this file. Equivalent to calling {@code resolveFile( path, NameScope.FILE_SYSTEM )}.
     *
     * @param path The path of the file to locate. Can either be a relative path or an absolute path.
     * @return The file.
     * @throws FileSystemException On error parsing the path, or on error finding the file.
     */
    FileObject resolveFile(String path) throws FileSystemException;

    /**
     * Finds a file relative to this file.
     *
     * Refer to {@link NameScope} for a description of how names are resolved in the different scopes.
     *
     * @param name The name to resolve.
     * @param scope the NameScope for the file.
     * @return The file.
     * @throws FileSystemException On error parsing the path, or on error finding the file.
     */
    FileObject resolveFile(String name, NameScope scope) throws FileSystemException;

    /**
     * Sets the owner's (or everybody's) write permission.
     *
     * @param executable True to allow read access, false to disallow.
     * @param ownerOnly If {@code true}, the permission applies only to the owner; otherwise, it applies to everybody.
     * @return true if the operation succeeded.
     * @throws FileSystemException On error determining if this file exists.
     * @since 2.1
     */
    boolean setExecutable(boolean executable, boolean ownerOnly) throws FileSystemException;

    /**
     * Sets the owner's (or everybody's) read permission.
     *
     * @param readable True to allow read access, false to disallow
     * @param ownerOnly If {@code true}, the permission applies only to the owner; otherwise, it applies to everybody.
     * @return true if the operation succeeded
     * @throws FileSystemException On error determining if this file exists.
     * @since 2.1
     */
    boolean setReadable(boolean readable, boolean ownerOnly) throws FileSystemException;

    /**
     * Sets the owner's (or everybody's) write permission.
     *
     * @param writable True to allow read access, false to disallow
     * @param ownerOnly If {@code true}, the permission applies only to the owner; otherwise, it applies to everybody.
     * @return true if the operation succeeded
     * @throws FileSystemException On error determining if this file exists.
     * @since 2.1
     */
    boolean setWritable(boolean writable, boolean ownerOnly) throws FileSystemException;
}