/*
 * Syncany, www.syncany.org
 * Copyright (C) 2011-2016 Philipp C. Heckel <philipp.heckel@gmail.com>
 *
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * This program 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 for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program.  If not, see <http://www.gnu.org/licenses/>.
 */
package org.syncany.plugins.transfer;

import java.io.File;
import java.util.Map;

import org.syncany.plugins.transfer.files.DatabaseRemoteFile;
import org.syncany.plugins.transfer.files.MultichunkRemoteFile;
import org.syncany.plugins.transfer.files.RemoteFile;
import org.syncany.plugins.transfer.files.SyncanyRemoteFile;

/**
 * The transfer manager synchronously connects to the remote storage. It is
 * responsible for file upload, download and deletion.
 *
 * <p>All its operations are strictly <b>synchronous</b> and throw a
 * {@code StorageException} if they fail. The implementations have to make sure
 * that
 * <ul>
 *   <li>the repository is not corrupted, e.g. duplicate files or corrupt files
 *   <li>files matching the specified file format are complete, i.e. fully uploaded
 *   <li>methods that need an established connections re-connect if necessary
 * </ul>
 *
 * <p>A transfer manager may organize files according to their type or name as
 * it is optimal for the given storage. {@link RemoteFile}s can be classified
 * by their sub-type. For network-transfer optimization reasons, it might be
 * useful to place {@link MultichunkRemoteFile}s and {@link DatabaseRemoteFile}s
 * in a separate sub-folder on the remote storage.
 *
 * @author Philipp C. Heckel (philipp.heckel@gmail.com)
 */
public interface TransferManager {
        /**
         * Establish a connection with the remote storage.
         *
         * <p>This method does not validate the correctness of the repository and
         * it does not create any folders. The former is done by {@link #test(boolean)}, the
         * latter is done by {@link #init(boolean)}.
         *
         * @throws StorageException If the connection fails due to no Internet connection,
         *         authentication errors, etc.
         */
        public void connect() throws StorageException;

        /**
         * Disconnect from the remote storage.
         *
         * @throws StorageException If the connection fails due to no Internet connection,
         *         authentication errors, etc.
         */
        public void disconnect() throws StorageException;

        /**
         * Initialize remote storage. This method is called to set up a new repository.
         *
         * @param  createIfRequired true if the method should handle repo creation
         * @throws StorageException If the connection drops, or any other
         *         exception occurs.
         */
        public void init(boolean createIfRequired) throws StorageException;

        /**
         * Download an existing remote file to the local disk.
         *
         * <p>The file is either downloaded completely or nothing at all. In the latter
         * case, a {@code StorageException} is thrown.
         *
         * <p>Implementations must make sure that if a file matches the specified name
         * schema, it must be complete and consistent.
         *
         * <p>If remoteFile does not exist, a {@link StorageFileNotFoundException} is thrown.
         *
         * @param remoteFile Existing source file on the remote storage.
         *        The only required property of the remote file is the name.
         * @param localFile Not existing local file to which the remote file is
         *        going to be downloaded.
         * @throws StorageException If the connection fails due to no Internet connection,
         *         authentication errors, etc.
         */
        public void download(RemoteFile remoteFile, File localFile) throws StorageException;

        /**
         * Update an existing local file to the online storage.
         *
         * <p>The file is either uploaded completely or nothing at all. In the latter
         * case, a {@code StorageException} is thrown.
         *
         * <p>Implementations must make sure that if a file matches the specified name
         * schema, it must be complete and consistent.
         *
         * <p>Implementations must NOT upload a file if it already exists and has
         * the same file size as the local file.
         *
         * @param localFile Existing local file that is going to be uploaded.
         * @param remoteFile Not existing destination file on the remote storage.
         *        The only required property of the remote file is the name.
         * @throws StorageException If the connection fails due to no Internet connection,
         *         authentication errors, etc.
         */
        public void upload(File localFile, RemoteFile remoteFile) throws StorageException;

        /**
         * Moves an existing file in the online storage.
         *
         * <p> If the sourceFile does not exists, a {@link StorageMoveException} is thrown.
         *
         * @param sourceFile Existing remote file that is to be moved.
         * @param targetFile Destination for the remote file.
         * @throws StorageException If the connection fails due to no Internet connection,
         *         authentication errors, etc.
         */
        public void move(RemoteFile sourceFile, RemoteFile targetFile) throws StorageException;

        /**
         * Deletes an existing file from the remote storage permanently.
         *
         * <p>In case the remote file does not exist, it returns immediately without
         * any notice. If the file cannot be deleted or the connection breaks,
         * a {@code StorageException} is thrown.
         *
         * @param remoteFile Existing remote file to be deleted.
         *        The only required property of the remote file is the name.
         * @throws StorageException If the connection fails due to no Internet connection,
         *         authentication errors, etc
         */
        public boolean delete(RemoteFile remoteFile) throws StorageException;

        /**
         * Retrieves a list of all files in the remote repository, filtered by
         * the type of the desired file, i.e. by a sub-class of {@link RemoteFile}.
         *
         * @param remoteFileClass Filter class: <code>RemoteFile</code> or a sub-type thereof
         * @return Returns a list of remote files. In the map, the key is the file name,
         *         the value the entire {@link RemoteFile} object.
         * @throws StorageException If the connection fails due to no Internet connection,
         *         authentication errors, etc
         */
        public <T extends RemoteFile> Map<String, T> list(Class<T> remoteFileClass) throws StorageException;

        /**
         * Tests whether the repository parameters are valid. In particular, the method tests
         * whether a target (folder, bucket, etc.) exists or, if not, whether it can be created.
         * It furthermore tests whether a repository at the target already exists by checking if the
         * {@link SyncanyRemoteFile} exists.
         *
         * <p>The relevant result is determined by the following methods:
         *
         * <ul>
         *  <li>{@link #testTargetExists()}: Tests whether the target exists.</li>
         *  <li>{@link #testTargetCanWrite()}: Tests whether the target is writable.</li>
         *  <li>{@link #testTargetCanCreate()}: Tests whether the target can be created if it does not
         *      exist already. This is only called if <code>testCreateTarget</code> is set.</li>
         *  <li>{@link #testRepoFileExists()}: Tests whether the repo file exists.</li>
         * </ul>
         *
         * @return Returns the result of testing the repository.
         * @param testCreateTarget If <code>true</code>, the test will test if the target can be created in case
         *        it does not exist. If <code>false</code>, this test will be skipped.
         * @see StorageTestResult
         */
        public StorageTestResult test(boolean testCreateTarget);

        /**
         * Tests whether the target path/folder <b>exists</b>. This might be done by listing the parent path/folder
         * or by retrieving metadata about the target. The method returns <code>true</code> if the target exists,
         * <code>false</code> otherwise.
         *
         * <p>This method is called by the {@link #test(boolean)} method (only during repository initialization
         * or initial connection).
         *
         * @return Returns <code>true</code> if the target exists, <code>false</code> otherwise
         * @throws StorageException If the test cannot be performed, e.g. due to a connection failure
         */
        public boolean testTargetExists() throws StorageException;

        /**
         * Tests whether the target path/folder is <b>writable</b> by the application. This method may either
         * check the write permissions of the target or actually write a test file to check write access. If the
         * target does not exist, <code>false</code> is returned. If the target exists and is writable, <code>true</code>
         * is returned.
         *
         * <p>This method is called by the {@link #test(boolean)} method (only during repository initialization
         * or initial connection).
         *
         * @return Returns <code>true</code> if the target can be written to, <code>false</code> otherwise
         * @throws StorageException If the test cannot be performed, e.g. due to a connection failure
         */
        public boolean testTargetCanWrite() throws StorageException;

        /**
         * Tests whether the target path/folder <b>can be created</b> (if it <b>does not exist already</b>). This method
         * may either check the permissions of the parent path/folder or actually create and delete the target to
         * determine create permissions.
         *
         * <p>If the target already exists, the method returns <code>true</code>. If it does not, but it can be created
         * (according to tests of this method), it also returns <code>true</code>. In all other cases, <code>false</code> is returned.
         *
         * <p>This method is called by the {@link #test(boolean)} method, <b>but only if</b> the <code>testCreateTarget</code> flag
         * is set to <code>true</code>!
         *
         * @return Returns <code>true</code> if the target can be created or already exists, <code>false</code> otherwise
         * @throws StorageException If the test cannot be performed, e.g. due to a connection failure
         */
        public boolean testTargetCanCreate() throws StorageException;

        /**
         * Tests whether the <b>repository file exists</b> (see {@link SyncanyRemoteFile}). This method is called by the {@link #test(boolean)} method
         * (only during repository initialization (or initial connection).
         *
         * <p>This method is called by the {@link #test(boolean)} method (only during repository initialization
         * or initial connection).
         *
         * @return Returns <code>true</code> if the repository is valid, <code>false</code> otherwise
         * @throws StorageException If the test cannot be performed, e.g. due to a connection failure
         */
        public boolean testRepoFileExists() throws StorageException;

        /**
         * Return the path for a concrete {@link org.syncany.plugins.transfer.files.RemoteFile} implementation as it is stored on the
         * remote side
         * *
         * @param remoteFileClass The class to provide the path for
         * @return A string pointing to the folder where a file is stored
         */
        public String getRemoteFilePath(Class<? extends RemoteFile> remoteFileClass);
        
}