/* Copyright (C) 2009  CSE,IIT Bombay  http://www.cse.iitb.ac.in

This file is part of the ConStore open source storage facility for concept-nets.

ConStore is free software and distributed under the 
Creative Commons Attribution-Noncommercial-No Derivative Works 3.0 Unported License;
you can copy, distribute and transmit the work
with the work attribution in the manner specified by the author or licensor.
You may not use this work for commercial purposes and may not alter, 
transform, or build upon this work.

Please refer the legal code of the license, available at
http://creativecommons.org/licenses/by-nc-nd/3.0/legalcode

ConStore 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.  */

package iitb.con.io;

import java.io.IOException;
import java.nio.ByteBuffer;

/**
 * Interface to handle IO operations with file.
 * 
 * @author Prathab K
 * @see ByteBuffer
 */
public interface IOAdapter {
    
    /**
     * Reads the contents and return it as byte array.
     * @param location location of the content in file
     * @param length length of the content to read from the specified location
     * @return contents in a byte array
     */
    public byte[] read(long location, int length) throws IOException;
    
    /**
     * Reads the contents into the temporary buffer and returns it as ByteBuffer
     * @param location location to be read
     * @return contents as ByteBuffer
     * @throws IOException if file operation fails
     */
    public ByteBuffer readIntoBuffer(long location) throws IOException;
    
    /**
     * Reads the entire contents of the file as ByteBuffer array.<br>
     * The contents as divided as block based on the block size value
     * @return contents as ByteBuffer array
     * @throws IOException if file operation fails
     */
    public ByteBuffer[] readFileAsBlocks() throws IOException;

    /**
     * Writes the contents to the specified location.
     * @param block the content block as bytes
     * @param location location to be written
     * @throws IOException if file operation fails
     */
    public void write(byte[] block, long location) throws IOException;
    
    /**
     * Writes the contents to the specified location.
     * @param block the content block
     * @param location location to be written
     * @throws IOException if file operation fails
     */
    public void write(ByteBuffer block, long location) throws IOException;
    
    /**
     * Writes the contents provided as array to the specified location.
     * @param blocks contents as array of blocks
     * @param location location to be written
     * @throws IOException if file operation fails
     */
    public void write(ByteBuffer[] blocks, long location) throws IOException;
    
    /**
     * Returns the length of the file
     * @return file length
     */
    public long getFileLength();
    
    /**
     * Closes the IO Adapter
     * @throws IOException if file operation fails
     */
    public void close() throws IOException;

}