package org.apache.hadoop.fs;

import java.io.FileNotFoundException;
import java.io.IOException;
import java.net.URI;

import org.apache.hadoop.conf.Configuration;
import org.apache.hadoop.fs.permission.FsPermission;
import org.apache.hadoop.util.Progressable;

/**
 * The Files class provides an interface to the application writer for
 * using the Hadoop file system.
 * It provides a set of static methods for the usual operation: create, open, 
 * list, etc 
 * 
 * *** Path Names ***
 * 
 * The Hadoop file system supports a URI name space and path names.
 *   TBD - explain more here.
 * Two common Hadoop file systems implementations are
 *   the local file system: file:///path
 *   the hdfs file system hdfs://nnAddress:nnPort/path
 *   
 * In addition, the user can set a default filesystem (i.e scheme and authority)
 * so that slash-relative names are resolved relative to that default.
 * Similarly a user can also have working-directory-relative names.
 * 
 *  Hence Hadoop path names can be one of:
 *       fully qualified URI:  scheme://authority/path
 *       slash relative names: /path    - relative to the default file system
 *       wd-relative names:    path        - relative to the working dir
 *  
 *  
 *  
 *  *** Configuration and defaults: ***
 *  The default configuration is obtained from the application config
 *  (@see xxx for details).
 *  The config contains defaults for
 *    - default file system
 *    - replication factor
 *    - block size
 *    - buffer size
 *    - etc.
 *
 * These defaults can be overridden by specifying the parameters as part of the
 * the specific methods (such as create) or by setting them via the appropriate
 * setDefaultXX methods below.
 * 
 *    
 */

/**
 * TBD: The methods have not been filled out yet.
 * Also the exceptions thrown by the methods have better specified.
 */
public class Files {
  

  public static final String LOCAL_FS_URI = "file:///";
  
  /**
   * To use the server side defaults for Replication factor and block size
   * specify -1.
   */
  public static final short SERVER_DEFAULT = -1;
  /**
   * To use the config  defaults for buff size, Replication factor & block size
   * specify -2.
   */
  public static final short CONFIG_DEFAULT = -2;
 
  
  /**
   * Slash-relative pathnames are opened relative to the default file system.
   * 
   * This method sets the default file system, overiding what was derived from
   * the config file.
   * 
   * @param uri - the default file system 
   * 
   * TBD
   *   Q: Should the type be string or path instead?
   *   Q: Shall we call this "setRootFileSystem" instead? 
   */
  public static void setDefaultFileSystem(URI uri) {
    //TBD
  }
  
  /**
   * Set the working directory for wd-relative names (such a "foo/bar")
   * @param p
   * @throws IOException
   */
  public static void setWorkingDir(Path p) throws IOException {
    // tbd
  }
  
  
  /**
   * Sets the default block size for newly created files, overriding what
   * was derived from the config file.
   * 
   * @param blksize  
   *     value of SERVER_DEFAULT implies use the default block size of the
   * target file server at which the file is created.
   */
  public static void setDefaultBlockSize(final int blksize) {
    
  }
  
  /**
   * Sets the default replication factor newly created files, overriding what
   * was derived from the config file.
   * 
   * @param repFac
   *     value of SERVER_DEFAULT  means  use the default replication factor
   * of the target file server at which the file is created.
   */
  public static void setDefaultReplicationFactor(final short repFac) {
    
  }
  
  /**
   * This method exports the default config.
   * 
   * The following keys are exported:
   * 
   * 
   * @param exportIntoThis - the key and values of the default config are
   *   inserted into exportIntoThis. If it contained the same keys their values
   *   would be replaced, other wise new keys and values would be inserted.
   */
  public static void exportConfig(Configuration exportIntoThis) {
    //TBD
  }
  
  /**
   * This default config is derived from the supplied config.
   * @param config - from where to import.
   * If config does not have the required keys then  
   */
  public void importConfig(final Configuration config) {
    //TBD
  }
  
  
  
  /**
   * Create or overwrite file on indicated path and returns an output stream
   *   for writing into the file.
   * @param f the file name to open
   * @param permission
   * @param overwrite if true and file exists, the file is overwritten,
   *                  if false and file exists,  error is thrown.
   * @throws IOException
   * 
   * @see #setPermission(Path, FsPermission)
   */
  public static FSDataOutputStream create(Path f,
                                    FsPermission permission,
                                    boolean overwrite) throws IOException {
    return null; //TBD
  }
  
  /**
   * Create or overwrite file on indicated path and returns an output stream
   *   for writing into the file.
   * @param f the file name to open
   * @param permission
   * @param overwrite if true and file exists, the file is overwritten,
   *                  if false and file exists,  error is thrown.
   * @param bufferSize the size of the buffer;
   *      value of CONFIG_DEFAULT implies use default in config
   * @param replication  block replication for file
   *      value of SERVER_DEFAULT implies use S-Side default
   *      value of CONFIG_DEFAULT implies use default in config
   * @param blockSize
   *      value of SERVER_DEFAULT implies use S-Side default
   *      value of CONFIG_DEFAULT implies use default in config
   * @param progress if non null, used to report progress
   * @throws IOException
   * 
   * @see #setPermission(Path, FsPermission)
   */
  public static FSDataOutputStream create(Path f,
                                    FsPermission permission,
                                    boolean overwrite,
                                    int bufferSize,
                                    short replication,
                                    long blockSize,
                                    Progressable progress) throws IOException {
    return null; //TBD
  }
  

  
  /**
   * Append to an existing file (optional operationX?XX).
   * @param f the existing file to be appended.
   * @param bufferSize the size of the buffer
   *      value of CONFIG_DEFAULT implies use default in config
   * @param progress if non null, used to report progress
   * @throws IOException
   * @throws FileNotFoundException if file does not exist
   */
  public static FSDataOutputStream append(Path f, int bufferSize,
      Progressable progress) throws IOException, FileNotFoundException {
    return null;  //TBD
  }

  
  
  /**
   * This append operation creates the file if does not exist
   * This  functionality is not there today - shall we add it? XXXX
   * 
   * Append to a file (create if it does not exist)
   * @param f the existing file to be appended.
   * @param bufferSize the size of the buffer; 
   *      value of CONFIG_DEFAULT implies use default in config
   * @param progress if non null, used to report progress
   * @param replication  block replication for file
   *      value of SERVER_DEFAULT implies use S-Side default
   *      value of CONFIG_DEFAULT implies use default in config
   * @param blockSize
   *      value of SERVER_DEFAULT implies use S-Side default
   *      value of CONFIG_DEFAULT implies use default in config
   * @throws IOException
   */
  public static FSDataOutputStream append(Path f, int bufferSize,
      Progressable progress, short replication, long blockSize) throws IOException  {
    return null;  //TBD
  }
  
  /**
   * Make the given file and all non-existent parents into
   * directories. Has the semantics of Unix 'mkdir -p'.
   * Existence of the directory hierarchy is not an error.
   */
  public static boolean mkdirs(Path f, FsPermission permission
      ) throws IOException {
    return false;  //TBD
  }

  /** Delete a file.
  *
  * @param f the path to delete.
  * @param recursive if path is a directory and set to 
  * true, the directory is deleted else throws an exception. In
  * case of a file the recursive can be set to either true or false. 
  * @return  true if delete is successful else false. 
  * @throws IOException
  */
  public static boolean delete(Path f, boolean recursive) throws IOException {
    return false;  //TBD
  }
 
 /**
  * Set replication for an existing file.
  * 
  * @param src file name
  * @param replication new replication
  * @throws IOException
  * @return true if successful;
  *         false if file does not exist or is a directory
  */
  public static boolean setReplication(Path src, short replication)
   throws IOException {
   return true;  //TBD
  }

 /**
  * Renames Path src to Path dst.  Can take place on local fs
  * or remote DFS.
  */
  public static boolean rename(Path src, Path dst) throws IOException {
  return false;  //TBD
  }
  
  /**
   * Set permission of a path.
   * @param p
   * @param permission
   */
  public void setPermission(Path p, FsPermission permission
      ) throws IOException {
  }

  /**
   * Set owner of a path (i.e. a file or a directory).
   * The parameters username and groupname cannot both be null.
   * @param p The path
   * @param username If it is null, the original username remains unchanged.
   * @param groupname If it is null, the original groupname remains unchanged.
   */
  public void setOwner(Path p, String username, String groupname
      ) throws IOException {
  }
  
  
  /**
   * Opens an FSDataInputStream at the indicated Path.
   * @param f the file name to open
   * @param bufferSize the size of the buffer to be used.
   *     value of CONFIG_DEFAULT implies use default in config
   */
  public static FSDataInputStream open(Path f, int bufferSize)
    throws IOException {
    return null;  //TBD
  }
  
  
  /**
   * Return a file status object that represents the path.
   * @param f The path we want information from
   * @return a FileStatus object
   * @throws FileNotFoundException when the path does not exist;
   *         IOException see specific implementation
   */
  public static FileStatus getFileStatus(Path f) throws IOException {
    return null;  //TBD
  }
  
  /**
   * Return an array containing hostnames, offset and size of 
   * portions of the given file.  For a nonexistent 
   * file or regions, null will be returned.
   *
   * This call is most helpful with DFS, where it returns 
   * hostnames of machines that contain the given file.
   *
   * The FileSystem will simply return an elt containing 'localhost'.
   */
  public static BlockLocation[] getFileBlockLocations(FileStatus file, 
    long start, long len) throws IOException {
      return null;  //TBD
  }
    
  /**
   * Copy file from src to target
   * @param src
   * @param target
   * @throws IOException
   */
  public void copy(final Path src, final Path target)  throws IOException {
    // TBD
  }
}