// Copyright 2015 The Vanadium Authors. All rights reserved.
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.

package io.v.v23.syncbase.nosql;

import io.v.v23.VIterable;
import io.v.v23.context.VContext;
import io.v.v23.services.syncbase.nosql.BlobFetchStatus;
import io.v.v23.services.syncbase.nosql.BlobRef;
import io.v.v23.verror.VException;

import java.io.InputStream;

/**
 * Interface for reading an (immutable) data blob.
 */
public interface BlobReader {
    /**
     * Returns a reference to the blob being read.
     */
    BlobRef getRef();

    /**
     * Returns the size of the blob.
     *
     * @param ctx         vanadium context
     * @throws VException if the blob size couldn't be determined
     */
    long size(VContext ctx) throws VException;

    /**
     * Returns the {@link InputStream} used for reading the contents of the blob, starting at the
     * given offset.
     * <p>
     * You should be aware of the following constraints on the returned {@link InputStream}:
     * <p><ul>
     *     <li> if the context used to create the {@link InputStream} is
     *          {@link io.v.v23.context.CancelableVContext#cancel canceled}, some of the
     *          subsequent {@link InputStream} {@link InputStream#read reads} may return valid
     *          values.  In fact, there is no hard guarantees that <strong>any</strong> subsequent
     *          reads will fail.
     * </ul><p>
     *
     * @param ctx         vanadium context
     * @param offset      offset at which to read the contents of the blob
     * @return            {@link InputStream} used for reading the contents of the blob
     * @throws VException if the stream couldn't be created (e.g., blob doesn't exist)
     */
    InputStream stream(VContext ctx, long offset) throws VException;

    /**
     * Initiates a blob prefetch, i.e., copying the blob to a local cache.
     * <p>
     * The provided {@code priority} value controls the network priority of the blob.  Higher
     * priority blobs are prefetched before the lower priority ones.  However an ongoing blob
     * transfer is not interrupted.
     * <p>
     * The returned iterator can be used to track the progress of the prefetch.  When the
     * iterator exhausts all of the iterable elements, the blob is guaranteed to have
     * been entirely copied to a local cache.
     * <p>
     * {@link io.v.v23.context.CancelableVContext#cancel Canceling} the provided context will
     * stop the prefetch and terminate the iterator early.
     * <p>
     * This method doesn't block.
     *
     * @param ctx         vanadium context
     * @param priority    prefetch priority
     * @return            a stream used for tracking the progress of the prefetch
     * @throws VException if the blob couldn't be prefetched
     */
    VIterable<BlobFetchStatus> prefetch(VContext ctx, long priority) throws VException;

    /**
     * Deletes the blob's local cached copy.
     * <p>
     * NOT YET IMPLEMENTED.
     *
     * @param ctx         vanadium context
     * @throws VException if the blob couldn't be deleted
     */
    void delete(VContext ctx) throws VException;

    /**
     * Pins the blob to a local cache so that it is not evicted.
     * <p>
     * NOT YET IMPLEMENTED.
     *
     * @param ctx         vanadium context
     * @throws VException if the blob couldn't be pinned
     */
    void pin(VContext ctx) throws VException;

    /**
     * Unpins the blob from the local cache so that it can be evicted if needed.
     * <p>
     * NOT YET IMPLEMENTED.
     *
     * @param ctx         vanadium context
     * @throws VException if the blob couldn't be un-pinned
     */
    void unpin(VContext ctx) throws VException;

    /**
     * Sets the eviction rank for the blob in the local cache.  Lower-ranked blobs are more eagerly
     * evicted.
     * <p>
     * NOT YET IMPLEMENTED.
     *
     * @param ctx         vanadium context
     * @param rank        eviction rank
     * @throws VException if the blob's local cache rank couldn't be set
     */
    void keep(VContext ctx, long rank) throws VException;
}