// Copyright 2016 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.discovery;

import com.google.common.util.concurrent.ListenableFuture;

import java.util.List;

import javax.annotation.CheckReturnValue;

import io.v.v23.InputChannel;
import io.v.v23.context.VContext;
import io.v.v23.security.BlessingPattern;
import io.v.v23.verror.VException;

/**
 * An interface for discovery operations; it is the client-side library for the discovery service.
 */
public interface Discovery {
    /**
     * Broadcasts the advertisement to be discovered by {@link #scan scan} operations.
     * <p>
     * Visibility is used to limit the principals that can see the advertisement. An
     * empty list means that there are no restrictions on visibility (i.e, equivalent
     * to {@link io.v.v23.security.Constants#ALL_PRINCIPALS}).
     * <p>
     * If {@link Advertisement#id} is not specified, a random unique a random unique
     * identifier will be assigned. Any change to service will not be applied after
     * advertising starts.
     * <p>
     * It is an error to have simultaneously active advertisements for two identical
     * instances (i.e., {@link Advertisement#id}s).
     * <p>
     * Advertising will continue until the context is canceled or exceeds its deadline
     * and the returned {@link ListenableFuture} will complete once it stops.
     * <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>
     *
     * @param context     a context that will be used to stop advertising
     * @param ad          an advertisement to advertises; this may be update with a random unique
     *                    identifier if ad.id is not specified.
     * @param visibility  a set of blessing patterns for whom this advertisement is meant; any entity
     *                    not matching a pattern here won't know what the advertisement is
     * @return            a new {@link ListenableFuture} that completes once advertising stops
     * @throws VException if advertising couldn't be started
     */
    @CheckReturnValue
    ListenableFuture<Void> advertise(
            VContext context, Advertisement ad, List<BlessingPattern> visibility) throws VException;

    /**
     * Scans advertisements that match the query and returns an {@link InputChannel} of updates.
     * <p>
     * Scan excludes the advertisements that are advertised from the same discovery instance.
     * <p>
     * The query is a {@code WHERE} expression of a {@code syncQL} query against advertisements,
     * where keys are {@link Advertisement#id}s and values are {@link Advertisement}s.
     * <p>
     * Examples:
     * <p><blockquote><pre>
     *     v.InterfaceName = "v.io/i"
     *     v.InterfaceName = "v.io/i" AND v.Attributes["a"] = "v"
     *     v.Attributes["a"] = "v1" OR v.Attributes["a"] = "v2"
     * </pre></blockquote><p>
     * You can find the {@code SyncQL} tutorial at:
     *     https://vanadium.github.io/tutorials/syncbase/syncql-tutorial.html
     * <p>
     * Scanning will continue until the context is canceled or exceeds its deadline. Note that
     * to avoid memory leaks, the caller should drain the channel after cancelling the context.
     *
     * @param context     a context that will be used to stop scanning
     * @param query       a WHERE expression of {@code syncQL query} against scanned advertisements
     * @return            a (potentially-infite) {@link InputChannel} of updates
     * @throws VException if scanning couldn't be started
     */
    @CheckReturnValue
    InputChannel<Update> scan(VContext context, String query) throws VException;
}