lib/src/main/java/io/v/v23/syncbase/DatabaseCore.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;

import com.google.common.util.concurrent.ListenableFuture;
import io.v.v23.InputChannel;
import io.v.v23.context.VContext;
import io.v.v23.services.syncbase.Id;
import io.v.v23.services.watch.ResumeMarker;
import io.v.v23.vdl.VdlAny;

import javax.annotation.CheckReturnValue;
import java.lang.reflect.Type;
import java.util.List;

/**
 * Base interface for {@link Database} and {@link BatchDatabase}, allowing clients to pass the
 * handle to helper methods that are batch-agnostic.
 */
public interface DatabaseCore {
    /**
     * Returns the id of the database.
     */
    Id id();

    /**
     * Returns the full (i.e., object) name of the database.
     */
    String fullName();

    /**
     * Returns the collection with the given user blessing and name.
     * <p>
     * This is a non-blocking method.
     *
     * @param collectionId Id of the collection.
     * @return The handle {@link Collection} to the collection
     */
    Collection getCollection(Id collectionId);

    /**
     * Returns the collection with the given relative name.
     * The user blessing is derived from the context.
     * <p>
     * This is a non-blocking method.
     *
     * @param context Vanadium context
     * @param name    Name of the collection
     * @return The handle {@link Collection} to the collection
     */
    Collection getCollection(VContext context, String name);

    /**
     * Returns a new {@link ListenableFuture} whose result is a list of all collection ids that the
     * caller is allowed to see. The list is sorted by blessing, then by name.
     * <p>
     * The returned future is guaranteed to be executed on an {@link java.util.concurrent.Executor}
     * specified in {@code context} (see {@link io.v.v23.V#withExecutor}).
     * <p>
     * The returned future will fail with {@link java.util.concurrent.CancellationException} if
     * {@code context} gets canceled.
     *
     * @param context Vanadium context
     * @return a list of all collection ids
     */
    @CheckReturnValue
    ListenableFuture<List<Id>> listCollections(VContext context);

    /**
     * Executes a SyncQL query, returning a {@link QueryResults} object that allows the caller to
     * iterate over arrays of values for each row that matches the query.
     * <p>
     * It is legal to perform writes concurrently with {@link #exec exec()}. The returned stream reads
     * from a consistent snapshot taken at the time of the method and will not reflect subsequent
     * writes to keys not yet reached by the stream.
     * <p>
     * The returned future is guaranteed to be executed on an {@link java.util.concurrent.Executor}
     * specified in {@code context} (see {@link io.v.v23.V#withExecutor}).
     * <p>
     * The returned future will fail with {@link java.util.concurrent.CancellationException} if
     * {@code context} gets canceled.
     *
     * @param context Vanadium context
     * @param query   a SyncQL query
     * @return a {@link ListenableFuture} whose result is a {@link QueryResults} object
     * that allows the caller to iterate over arrays of values for each row that
     * matches the query
     */
    @CheckReturnValue
    ListenableFuture<QueryResults> exec(VContext context, String query);

    /**
     * Executes a SyncQL parameterized query. Same as {@link #exec(VContext, String)}, with the
     * query supporting positional parameters. {@code paramValues} and {@code paramTypes} must each
     * have one element corresponding to each '?' placeholder in the query.
     *
     * @param context     Vanadium context
     * @param query       a SyncQL query
     * @param paramValues SyncQL query parameters, one per '?' placeholder in the query
     * @param paramTypes  SyncQL query parameter types, one per parameter in paramValues
     * @return a {@link ListenableFuture} whose result is a {@link QueryResults}
     * object that allows the caller to iterate over arrays of values for each
     * row that matches the query
     */
    @CheckReturnValue
    ListenableFuture<QueryResults> exec(VContext context, String query,
                                        List<Object> paramValues, List<Type> paramTypes);

    /**
     * Returns a new {@link ListenableFuture} whose result is the {@link ResumeMarker} that points
     * to the current state of the database.
     * <p>
     * The returned future is guaranteed to be executed on an {@link java.util.concurrent.Executor}
     * specified in {@code context} (see {@link io.v.v23.V#withExecutor}).
     * <p>
     * The returned future will fail with {@link java.util.concurrent.CancellationException} if
     * {@code context} gets canceled.
     */
    @CheckReturnValue
    ListenableFuture<ResumeMarker> getResumeMarker(VContext context);

    /**
     * An interface for iterating through rows resulting from a
     * {@link DatabaseCore#exec DatabaseCore.exec()}.
     */
    interface QueryResults extends InputChannel<List<VdlAny>> {
        /**
         * Returns an array of column names that matched the query.  The size of the {@link VdlAny}
         * list returned in every {@link #recv} iteration will match the size of this list.
         */
        List<String> columnNames();
    }
}