// 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.syncbase.v23.services.syncbase.nosql;

import io.v.v23.verror.VException;

/**
 * An interface for iterating through a collection of elements.
 */
public interface Stream {
    /**
     * Stages an element so that the client can retrieve it.
     * <p>
     * Returns {@code true} iff there is an element to retrieve.
     * <p>
     * The client must call {@link #advance} before retrieving the element.
     * <p>
     * The client must call {@link #cancel} if it does not iterate through all elements
     * (i.e. until {@link #advance} returns {@code false}).
     * <p>
     * This method may block if an element is not immediately available.
     *
     * @return             {@code true} iff there is an element to retrieve
     * @throws VException  if there was an error advancing the stream
     */
    boolean advance() throws VException;

    /**
     * Notifies the stream provider that it can stop producing elements.  The client must call
     * {@link #cancel} if it does not iterate through all elements (i.e. until {@link #advance})
     * returns {@code false}).
     * <p>
     * This method is idempotent and can be called concurrently with a thread that is
     * iterating via {@link #advance}.
     * <p>
     * This method causes {@link #advance} to subsequently return {@code false}.
     * <p>
     * This method does not block.
     */
    void cancel();
}