/*
 * SIP Communicator, the OpenSource Java VoIP and Instant Messaging client.
 *
 * Distributable under LGPL license.
 * See terms of license at gnu.org.
 */
package net.java.sip.communicator.service.fileaccess;

import java.io.File;
import java.io.IOException;

/**
 * A service used to provide the basic functionality required to access the
 * undelying file system.
 * 
 * Note: Never store unencrypted sensitive information, such as passwords,
 * personal data, credit card numbers, etc..
 * 
 * @author Alexander Pelov
 */
public interface FileAccessService {

    /**
     * The key of the system property containing the user home dir
     */
    public static final String SYSPROPERTYKEY_USER_HOME = "user.home";

    /**
     * The key of the configuration property containing the user home dir - if
     * it is not defined the system property is used
     */
    public static final String CONFPROPERTYKEY_USER_HOME = "net.java.sip.communicator.user.home";

    /**
     * The subdirectory of USER_HOME in which all user files will be stored
     */
    public static final String CONFPROPERTYKEY_SIPCOMM_DIRECTORY = "net.java.sip.communicator.user.home.sip-communicator-home";

    /**
     * The default subdirectory
     */
    public static final String DEFAULT_SIPCOMM_DIRECTORY = ".sip-communicator";

    /**
     * This method returns a created temporary file. After you close this file
     * it is not guaranteed that you will be able to open it again nor that it
     * will contain any information.
     * 
     * Note: DO NOT store unencrypted sensitive information in this file
     * 
     * @return The created temporary file
     * @throws IOException
     *             If the file cannot be created
     */
    File getTemporaryFile() throws IOException;

    /**
     * This method returns a created temporary directory. Any file you create in
     * it will be a temporary file.
     * 
     * Note: If there is no opened file in this directory it may be deleted at
     * any time. Note: DO NOT store unencrypted sensitive information in this
     * directory
     * 
     * @return The created directory
     * @throws IOException
     *             If the directory cannot be created
     */
    File getTemporaryDirectory() throws IOException;

    /**
     * This method returns a file specific to the current user. It may not
     * exist, but it is guaranteed that you will have the sufficient rights to
     * create it.
     * 
     * This file should not be considered secure because the implementor may
     * return a file accesible to everyone. Generaly it will reside in current
     * user's homedir, but it may as well reside in a shared directory.
     * 
     * Note: DO NOT store unencrypted sensitive information in this file
     * 
     * @param fileName
     *            The name of the private file you wish to access
     * @return The file
     * @throws Exception
     *             Thrown if there is no suitable location for the persistent
     *             file
     */
    File getPrivatePersistentFile(String fileName) throws Exception;

    /**
     * This method creates a directory specific to the current user.
     * 
     * This directory should not be considered secure because the implementor
     * may return a directory accesible to everyone. Generaly it will reside in
     * current user's homedir, but it may as well reside in a shared directory.
     * 
     * It is guaranteed that you will be able to create files in it.
     * 
     * Note: DO NOT store unencrypted sensitive information in this file
     * 
     * @param dirName
     *            The name of the private directory you wish to access.
     * @return The created directory.
     * @throws Exception
     *             Thrown if there is no suitable location for the persistent
     *             directory.
     */
    File getPrivatePersistentDirectory(String dirName) throws Exception;

    /**
     * This method creates a directory specific to the current user.
     * 
     * {@link #getPrivatePersistentDirectory(String)}
     * 
     * @param dirNames
     *            The name of the private directory you wish to access.
     * @return The created directory.
     * @throws Exception
     *             Thrown if there is no suitable location for the persistent
     *             directory.
     */
    File getPrivatePersistentDirectory(String[] dirNames) throws Exception;
}