/*
 * Title:        CloudSim Toolkit
 * Description:  CloudSim (Cloud Simulation) Toolkit for Modeling and Simulation of Clouds
 * Licence:      GPL - http://www.gnu.org/copyleft/gpl.html
 *
 * Copyright (c) 2009-2010, The University of Melbourne, Australia
 */

package org.cloudbus.cloudsim;

import java.util.List;

/**
 * An interface which defines the desired functionality of a storage system in
 * a Data Cloud. The classes that implement this interface should simulate the
 * characteristics of different storage systems by setting the capacity of the
 * storage and the maximum transfer rate. The transfer rate defines the time
 * required to execute some common operations on the storage, e.g. storing a
 * file, getting a file and deleting a file.
 *
 * @author		Uros Cibej
 * @author		Anthony Sulistio
 * @since		CloudSim Toolkit 1.0
 */
public interface Storage {

    /**
     * Gets the name of the storage.
     *
     * @return  the name of this storage
     */
    String getName();

    /**
     * Gets the total capacity of the storage in MByte.
     *
     * @return  the capacity of the storage in MB
     */
    double getCapacity();

    /**
     * Gets the current size of the storage in MByte.
     *
     * @return  the current size of the storage in MB
     */
    double getCurrentSize();

    /**
     * Gets the maximum transfer rate of the storage in MByte/sec.
     *
     * @return  the maximum transfer rate in MB/sec
     */
    double getMaxTransferRate();

    /**
     * Gets the available space on this storage in MByte.
     *
     * @return  the available space in MB
     */
    double getAvailableSpace();

    /**
     * Sets the maximum transfer rate of this storage system in MByte/sec.
     *
     * @param rate the maximum transfer rate in MB/sec
     *
     * @return <tt>true</tt> if the setting succeeded, <tt>false</tt>
     * otherwise
     */
    boolean setMaxTransferRate(int rate);

    /**
     * Checks if the storage is full or not.
     *
     * @return  <tt>true</tt> if the storage is full, <tt>false</tt>
     * otherwise
     */
    boolean isFull();

    /**
     * Gets the number of files stored on this storage.
     *
     * @return the number of stored files
     */
    int getNumStoredFile();

    /**
     * Makes a reservation of the space on the storage to store a file.
     *
     * @param fileSize  the size to be reserved in MB
     *
     * @return <tt>true</tt> if reservation succeeded, <tt>false</tt>
     * otherwise
     */
    boolean reserveSpace(int fileSize);

    /**
     * Adds a file for which the space has already been reserved.
     * The time taken (in seconds) for adding the specified file can also be
     * found using {@link gridsim.datagrid.File#getTransactionTime()}.
     *
     * @param file  the file to be added
     *
     * @return the time (in seconds) required to add the file
     */
    double addReservedFile(File file);

    /**
     * Checks whether there is enough space on the storage for a certain file.
     *
     * @param fileSize  a FileAttribute object to compare to
     *
     * @return <tt>true</tt> if enough space available, <tt>false</tt>
     * otherwise
     */
    boolean hasPotentialAvailableSpace(int fileSize);

    /**
     * Gets the file with the specified name.
     * The time taken (in seconds) for getting the specified file can also be
     * found using {@link gridsim.datagrid.File#getTransactionTime()}.
     *
     * @param fileName the name of the needed file
     *
     * @return the file with the specified filename
     */
    File getFile(String fileName);

    /**
     * Gets the list of file names located on this storage.
     *
     * @return a List of file names
     */
    List<String> getFileNameList();

    /**
     * Adds a file to the storage.
     * The time taken (in seconds) for adding the specified file can also be
     * found using {@link gridsim.datagrid.File#getTransactionTime()}.
     *
     * @param file the file to be added
     *
     * @return the time taken (in seconds) for adding the specified file
     */
    double addFile(File file);

    /**
     * Adds a set of files to the storage.
     * The time taken (in seconds) for adding each file can also be
     * found using {@link gridsim.datagrid.File#getTransactionTime()}.
     *
     * @param list the files to be added
     *
     * @return the time taken (in seconds) for adding the specified files
     */
    double addFile(List<File> list);

    /**
     * Removes a file from the storage.
     * The time taken (in seconds) for deleting the specified file can be
     * found using {@link gridsim.datagrid.File#getTransactionTime()}.
     *
     * @param fileName the name of the file to be removed
     *
     * @return the deleted file.
     */
    File deleteFile(String fileName);

    /**
     * Removes a file from the storage.
     * The time taken (in seconds) for deleting the specified file can also be
     * found using {@link gridsim.datagrid.File#getTransactionTime()}.
     *
     * @param fileName the name of the file to be removed
     * @param file the file which is removed from the storage is returned
     * through this parameter
     *
     * @return the time taken (in seconds) for deleting the specified file
     */
    double deleteFile(String fileName, File file);

    /**
     * Removes a file from the storage.
     * The time taken (in seconds) for deleting the specified file can also be
     * found using {@link gridsim.datagrid.File#getTransactionTime()}.
     *
     * @param file the file which is removed from the storage is returned
     * through this parameter
     *
     * @return the time taken (in seconds) for deleting the specified file
     */
    double deleteFile(File file);

    /**
     * Checks whether a file is stored in the storage or not.
     *
     * @param fileName the name of the file we are looking for
     *
     * @return <tt>true</tt> if the file is in the storage, <tt>false</tt>
     * otherwise
     */
    boolean contains(String fileName);

    /**
     * Checks whether a file is stored in the storage or not.
     *
     * @param file the file we are looking for
     *
     * @return <tt>true</tt> if the file is in the storage, <tt>false</tt>
     * otherwise
     */
    boolean contains(File file);

    /**
     * Renames a file on the storage.
     * The time taken (in seconds) for renaming the specified file can also be
     * found using {@link gridsim.datagrid.File#getTransactionTime()}.
     *
     * @param file the file we would like to rename
     * @param newName the new name of the file
     *
     * @return <tt>true</tt> if the renaming succeeded, <tt>false</tt>
     * otherwise
     */
    boolean renameFile(File file, String newName);

}
