// 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 com.google.common.util.concurrent.ListenableFuture;

import java.util.Map;

import javax.annotation.CheckReturnValue;

import io.v.v23.context.VContext;
import io.v.v23.services.syncbase.nosql.SyncgroupMemberInfo;
import io.v.v23.services.syncbase.nosql.SyncgroupSpec;

/**
 * A handle for a {@link Database} synchronization group.
 */
public interface Syncgroup {
    /**
     * Creates a new syncgroup with the given spec.  Requires:
     * <p>
     * <ul>
     *     <li> client must have at least {@code read} access on the database,</li>
     *     <li> prefix ACL must exist at each syncgroup prefix,</li>
     *     <li> client must have at least {@code read} access on each of these prefix ACLs.</li>
     * </ul>
     * <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  spec       syncgroup specification
     * @param  info       creator's membership information
     */
    @CheckReturnValue
    ListenableFuture<Void> create(VContext context, SyncgroupSpec spec, SyncgroupMemberInfo info);

    /**
     * Joins a syncgroup.  Requires:
     * <p>
     * <ul>
     *     <li> client must have at least {@code read} access on the database and on the syncgroup
     *          ACLs.</li>
     * </ul>
     * <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  info       joiner's membership information
     * @return            a new {@link ListenableFuture} whose result is the syncgroup specification
     */
    @CheckReturnValue
    ListenableFuture<SyncgroupSpec> join(VContext context, SyncgroupMemberInfo info);

    /**
     * Leaves the syncgroup.  Previously synced data will continue to be available.  Requires:
     * <p>
     * <ul>
     *     <li> client must have at least {@code read} access on the database.</li>
     * </ul>
     * <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
     */
    @CheckReturnValue
    ListenableFuture<Void> leave(VContext context);

    /**
     * Destroys the syncgroup.  Previously synced data will continue to be available to all
     * members.  Requires:
     * <p>
     * <ul>
     *     <li> client must have at least {@code read} access on the database and an {@code admin}
     *          access on the syncgroup ACLs.</li>
     * </ul>
     * <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
     */
    @CheckReturnValue
    ListenableFuture<Void> destroy(VContext context);

    /**
     * Ejects a member from the syncgroup.  The ejected member will not be able to sync further,
     * but will retain any data it has already synced.  Requires:
     * <p>
     * <ul>
     *     <li> client must have at least {@code read} access on the database and an {@code admin}
     *          access on the syncgroup ACLs.</li>
     * </ul>
     * <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  member     member to be ejected
     */
    @CheckReturnValue
    ListenableFuture<Void> eject(VContext context, String member);

    /**
     * Returns a new {@link ListenableFuture} whose result is the syncgroup specification, along
     * with its version string.  The version number allows for atomic read-modify-write of the
     * specification (see {@link #setSpec setSpec()}). Requires:
     * <p>
     * <ul>
     *     <li> client must have at least {@code read} access on the database and on the syncgroup
     *          ACLs.</li>
     * </ul>
     * <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 new {@link ListenableFuture} whose result is the syncgroup specification
     *                    along with its version number; the returned map is guaranteed to be
     *                    non-{@code null} and contain exactly one element
     */
    @CheckReturnValue
    ListenableFuture<Map<String, SyncgroupSpec>> getSpec(VContext context);

    /**
     * Sets the syncgroup specification.  The version string may be either empty or the value of
     * the previous {@link #getSpec getSpec()}, in which case {@link #setSpec setSpec()} will only
     * succeed iff the current version matches the specified one.
     * <p>
     * <ul>
     *     <li> client must have at least {@code read} access on the database and an {@code admin}
     *          access on the syncgroup ACLs.</li>
     * </ul>
     * <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  spec       the new syncgroup specification
     * @param  version    expected version string of the syncgroup;  if non-empty, this
     *                    method will only succeed if the current syncgroup's version matches
     *                    this value
     */
    @CheckReturnValue
    ListenableFuture<Void> setSpec(VContext context, SyncgroupSpec spec, String version);

    /**
     * Returns a new {@link ListenableFuture} whose result is the membership of the syncgroup.
     * Requires:
     * <p>
     * <ul>
     *     <li> client must have at least {@code read} access on the database and on the syncgroup
     *          ACLs.</li>
     * </ul>
     * <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
     */
    @CheckReturnValue
    ListenableFuture<Map<String, SyncgroupMemberInfo>> getMembers(VContext context);
}