package com.sun.media.jfxmedia.locator;

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

/**
 * Connection holders hold and maintain connection do different kinds of sources
 *
 */
public abstract class ConnectionHolder {
    public static final int DEFAULT_BUFFER_SIZE = 4096;
    
    protected final ByteBuffer buffer = ByteBuffer.allocateDirect(DEFAULT_BUFFER_SIZE);

    /**
     * Reads a block of data from the current position of the opened stream to the 
     * buffer.
     *
     * @return The number of bytes read, possibly zero, or -1 if the channel
     * has reached end-of-stream.
     *
     * @throws IOException if an attempt is made to read after
     * closeConnection has been called or any other IO error.
     */
    public abstract int readNextBlock() throws IOException;

    /**
     * @return instance of internal ByteBuffer
     */
    public ByteBuffer getBuffer() {
        return buffer;
    }

    /**
     * Reads a block of data from the arbitrary position of the opened stream to the 
     * buffer. Users must implement this method if isRandomAccess() returns true otherwise
     * it's good enough to throw IOException from the body of the method.
     *
     * @return The number of bytes read, possibly zero, or -1 if the given position
     * is greater than or equal to the file's current size.
     *
     * @throws IOException if an attempt is made to read after 
     * closeConnection has been called or any other IO error.
     */
    public abstract int readBlock(long position, int size) throws IOException;

    /**
     * Detects whether this source needs buffering at the pipeline level.
     * When true the pipeline contains progressbuffer after the source.
     * This allows buffering on client capability. 
     *
     * @return true if the source needs a buffer, false otherwise.
     */
    public abstract boolean needBuffer();

    /**
     * Detects whether the source is seekable.
     * @return true if the source is seekable, false otherwise.
     */
    public abstract boolean isSeekable();

    /**
     * Detects whether the source is a random access source. If the method returns
     * true then the source is capable of working in pull mode. To be able to work
     * in pull mode holder must provide @see #readBlock(long position, int size) implementation.
     * @return true is the source is random access, false otherwise.
     */
    public abstract boolean isRandomAccess();

    /**
     * Performs a seek request to the desired position.
     *
     * @return -1 if the seek request failed or seek is not supported (@see #isSeekable() returns false).
     */
    public abstract long seek(long position);

    /**
     * Closes connection when done.
     */
    public abstract void closeConnection();
}