/*
 * Created on Jul 27, 2006
 * 
 * (C) Copyright TANDBERG Television Ltd.
 */

package com.tandbergtv.workflow.webservice.filesubsystem;

import java.io.File;

/**
 * Defines the different File Management methods offered.
 * 
 * @author Vijay Silva
 */
public interface FileManagementService
{
	/**
	 * Checks if the file exists
	 * 
	 * @param filePath
	 *            the path of the file
	 * @return true, if the file exists. false if the file doesn't exist or is a folder
	 */
	boolean fileExists(String filePath);

	/**
	 * Method to move a file to a specified destination. If the destination is a Directory, the name
	 * of the file is preserved.
	 * 
	 * @param filePath
	 *            The complete Path to the File.
	 * @param destinationPath
	 *            The path to the move destination.
	 * 
	 * @throws FileManagementException
	 *             Exception if the File doesn't exist, isn't a File, if the destination is an
	 *             existing File or if the move operation fails.
	 */
	void moveFile(String filePath, String destinationPath) throws FileManagementException;

	/**
	 * Method to copy a file to a specified destination. If the destination is a Directory, the name
	 * of the file is preserved.
	 * 
	 * @param filePath
	 *            The complete Path to the File.
	 * @param destinationPath
	 *            The path to the copy destination.
	 * 
	 * @throws FileManagementException
	 *             Exception if the File doesn't exist, isn't a File, if the destination is an
	 *             existing File or if the copy operation fails.
	 */
	void copyFile(String filePath, String destinationPath) throws FileManagementException;

	/**
	 * Method to rename a File on the File Systme.
	 * 
	 * @param filePath
	 *            The complete Path to the file.
	 * @param newFileName
	 *            The new name of the File.
	 * 
	 * @throws FileManagementException
	 *             Exception if the File doesn't exist, is not a File, or if the new File name
	 *             already exists.
	 */
	void renameFile(String filePath, String newFileName) throws FileManagementException;

	/**
	 * Method to get the size of a File on the File System
	 * 
	 * @param filePath
	 *            The complete Path to the file.
	 * @return The Size of the File
	 * 
	 * @throws FileManagementException
	 *             Exception if the File doesn't exist or is not a File.
	 */
	long getFileSize(String filePath) throws FileManagementException;

	/**
	 * Method to remove the File from the File System.
	 * 
	 * @param filePath
	 *            The complete Path to the file to be removed.
	 * 
	 * @throws FileManagementException
	 *             Exception if the File doesn't exist or is not a File.
	 */
	void removeFile(String filePath) throws FileManagementException;

	/**
	 * Method to calculate the total disk space (in bytes) occupied by a Folder and all its files
	 * and subfolders.
	 * 
	 * @param folderPath
	 *            The Path to the Folder
	 * @return The number of bytes occupied by the Folder.
	 * 
	 * @throws FileManagementException
	 *             Exception if the folder doesn't exist.
	 */
	long getFolderSize(String folderPath) throws FileManagementException;

	/**
	 * Calculates the free space of the specified drive
	 * 
	 * @param drive the Windows drive letter or a UNIX volume path
	 * @return The total free space on the Drive (in bytes)
	 * @throws FileManagementException if there is a problem retrieving the free space
	 */
	long getDriveFreeSpace(String drive) throws FileManagementException;
	
	/**
	 * Calculates the capacity of the specified drive
	 * 
	 * @param drive the Windows drive letter or a UNIX volume path
	 * @return The total space on the Drive (in bytes)
	 * @throws FileManagementException if there is a problem retrieving the total capacity
	 */
	long getDriveTotalSpace(String drive) throws FileManagementException;
	
	/**
	 * Method to get a listing of all the Files or Folders that are children of the current folder.
	 * 
	 * @param folderPath
	 *            The Path to the Folder
	 * @param filesOnly
	 *            get only files or only folders (true for files, false for folders)
	 * @return An Array of the child files. Empty array if the directory is empty. Returns null if
	 *         this abstract pathname does not denote a directory, or if an I/O error occurs.
	 * 
	 * @throws FileManagementException
	 *             Failure to get the file list.
	 * 
	 * @see java.io.File#listFiles()
	 */
	File[] getFileList(String folderPath, boolean filesOnly) throws FileManagementException;

	/**
	 * Downloads a file specified in sourcePath to the location specified in destinationPath using FTP
	 * 
	 * @param sourcePath
	 * 			The file to be downloaded (eg: /test/robots.txt)
	 * @param destinationPath
	 * 			The destination where the file will be downloaded (eg: C:\\robots.txt)
	 * @param host
	 * 			The host name of the FTP server 
	 * @param username
	 * 			The username to be used to logon to the FTP server
	 * @param password
	 * 			The password to be used to logon to the FTP server
	 * @throws FileManagementException 
	 * 
	 */
	void ftpDownload(String sourcePath, String destinationPath, String host, String username, String password) throws FileManagementException;

	/**
	 * Uploads a file specified in sourcePath to the location specified in destinationPath using FTP
	 * 
	 * @param sourcePath
	 * 			The file to be uploaded (eg: C:\\robots.txt)
	 * @param destinationPath
	 * 			The destination where the file will be uploaded (eg: /test/robots.txt)
	 * @param host
	 * 			The host name of the FTP server 
	 * @param username
	 * 			The username to be used to logon to the FTP server
	 * @param password
	 * 			The password to be used to logon to the FTP server
	 * @throws FileManagementException 
	 * 
	 */
	void ftpUpload(String sourcePath, String destinationPath, String host, String username, String password) throws FileManagementException;
	
	/**
	 * Archives the files specified in sourceFiles to the location specified in destinationPath.
	 * The extension of the destinationPath determines the desired archive type (tar, zip, gz, ...)
	 * 
	 * @param sourceFiles
	 * 			The comma-separated list of files, the folder that contains files/folders, or a single file to be archived
	 * @param destinationPath
	 * 			The location of the resulting archive file
	 * @throws FileManagementException 
	 * 			Failure to archive the files
	 */
	void archiveFiles (String sourceFiles, String destinationPath) throws FileManagementException;

	/**
	 * Calculates the MD5 checksum for a given file
	 * 
	 * @param filePath
	 * @return checksum
	 * @throws FileManagementException 
	 */
	String computeMD5Checksum(String filePath) throws FileManagementException;

	/**
	 * Extracts the file specified by filePath to a directory specified by
	 * destinationDirectory
	 * 
	 * @param filePath
	 * @param destinationDirectory
	 * @throws FileManagementException 
	 */
	void extractFile(String filePath, String destinationDirectory) throws FileManagementException;
}