// 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.rpc;

import io.v.v23.Options;
import io.v.v23.verror.VException;
import io.v.v23.context.VContext;

import java.lang.reflect.Type;

/**
 * The interface for making RPC calls.  There may be multiple outstanding calls associated with a
 * single client, and a client may be used by multiple threads concurrently.
 */
public interface Client {
    /**
     * Starts an asynchronous call of the method on the server instance identified by name
     * with the given input args (of any arity).  The returned {@link ClientCall} object manages
     * streaming args and results and finishes the call.
     *
     * @param  context         client context
     * @param  name            name of the server
     * @param  method          name of the server's method to be invoked
     * @param  args            arguments to the server method
     * @param  argTypes        types of the provided arguments
     * @return                 call object that manages streaming args and results
     * @throws VException      if the call cannot be started
     */
    ClientCall startCall(VContext context, String name, String method, Object[] args, Type[] argTypes)
            throws VException;

    /**
     * Starts an asynchronous call of the method on the server instance identified by name with the
     * given input args (of any arity) and provided options.  The returned {@link ClientCall} object
     * manages streaming args and results and finishes the call.
     * <p>
     * A particular implementation of this interface chooses which options to support,
     * but at the minimum it must handle the following pre-defined options:
     * <ul>
     *     <li>{@link io.v.v23.OptionDefs#SKIP_SERVER_ENDPOINT_AUTHORIZATION}</li>
     * </ul>
     *
     * @param  context         client context
     * @param  name            name of the server
     * @param  method          name of the server's method to be invoked
     * @param  args            arguments to the server method.
     * @param  argTypes        types of the provided arguments
     * @param  opts            call options
     * @return                 call object that manages streaming args and results
     * @throws VException      if the call cannot be started
     */
    ClientCall startCall(VContext context, String name, String method, Object[] args, Type[] argTypes,
            Options opts) throws VException;

    /**
     * Starts an asynchronous call of the method on the server instance identified by name with the
     * given input args (of any arity). The callback's {@link Callback#onSuccess} method is called
     * when the asynchronous call has been started on the remote side, or its {@link
     * Callback#onFailure} method is called if the call could not be started.
     *
     * @param  context         client context
     * @param  name            name of the server
     * @param  method          name of the server's method to be invoked
     * @param  args            arguments to the server method.
     * @param  argTypes        types of the provided arguments
     * @param  callback        the non-{@code null} callback to call when the call has been started
     * @throws VException      if the call cannot be started
     */
    void startCall(VContext context, String name, String method, Object[] args, Type[] argTypes,
                   Callback<ClientCall> callback) throws VException;

    /**
     * Starts an asynchronous call of the method on the server instance identified by name with the
     * given input args (of any arity) and provided options. The callback's {@link
     * Callback#onSuccess} method is called when the asynchronous call has been started on the
     * remote side, or its {@link Callback#onFailure} method is called if the call could not be
     * started.
     * <p>
     * A particular implementation of this interface chooses which options to support,
     * but at the minimum it must handle the following pre-defined options:
     * <ul>
     *     <li>{@link io.v.v23.OptionDefs#SKIP_SERVER_ENDPOINT_AUTHORIZATION}</li>
     * </ul>
     *
     * @param  context         client context
     * @param  name            name of the server
     * @param  method          name of the server's method to be invoked
     * @param  args            arguments to the server method.
     * @param  argTypes        types of the provided arguments
     * @param  opts            call options
     * @param  callback        the non-{@code null} callback to call when the call has been started
     * @throws VException      if the call cannot be started
     */
    void startCall(VContext context, String name, String method, Object[] args, Type[] argTypes,
                         Options opts, Callback<ClientCall> callback) throws VException;

    /**
     * Discards the state associated with this client.  In-flight calls may be terminated with
     * an error.
     */
    void close();
}