| // 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(); |
| } |