lib/src/main/java/io/v/v23/syncbase/nosql/Stream.java

// 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.verror.VException;

/**
 * An interface for iterating through a collection of elements.
 *
 * The {@link java.util.Iterator} returned by the {@link java.lang.Iterable#iterator iterator}:
 * <p><ul>
 *     <li>can be created <strong>only</strong> once,
 *     <li>does not support {@link java.util.Iterator#remove remove}</li>,
 *     <li>stops the iteration early and gracefully if the {@link #cancel} method is invoked,</li>
 *     <li>may throw {@link RuntimeException} if the underlying iteration step throws
 *         a {@link VException}.  The {@link RuntimeException#getCause cause} of the
 *         {@link RuntimeException} will be the said {@link VException}.</li>
 * </ul>
 */
public interface Stream<T> extends Iterable<T> {
    /**
     * Notifies the stream provider that it can stop producing elements.  The client must call
     * {@link #cancel} if it does not iterate through all the elements.
     * <p>
     * This method is idempotent and can be called concurrently with a thread that is iterating.
     * <p>
     * This method causes the iterator to (gracefully) terminate early.
     */
    void cancel() throws VException;
}