com.linkedin.restli.client.Client Maven / Gradle / Ivy

Go to download
/*
   Copyright (c) 2017 LinkedIn Corp.

   Licensed under the Apache License, Version 2.0 (the "License");
   you may not use this file except in compliance with the License.
   You may obtain a copy of the License at

       http://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.
*/

package com.linkedin.restli.client;

import com.linkedin.common.callback.Callback;
import com.linkedin.common.util.None;
import com.linkedin.r2.message.RequestContext;
import com.linkedin.restli.client.multiplexer.MultiplexedRequest;
import com.linkedin.restli.client.multiplexer.MultiplexedResponse;


/**
 * Rest.li client interface with overloading methods for sending Rest.li {@link Request}
 *
 * @author Sean Sheng
 */
public interface Client
{
  /**
   * Resource name of {@link MultiplexedRequest}
   */
  String MULTIPLEXER_RESOURCE = "mux";

  /**
   * Shuts down the underlying {@link com.linkedin.r2.transport.common.Client} which this RestClient wraps.
   * @param callback
   */
  void shutdown(Callback callback);

  /**
   * Sends a type-bound REST request, returning a future.
   *
   *
   * @param request to send
   * @param requestContext context for the request
   * @return response future
   */
   ResponseFuture sendRequest(Request request, RequestContext requestContext);

  /**
   * Sends a type-bound REST request, returning a future.
   *
   *
   * @param request to send
   * @param requestContext context for the request
   * @param errorHandlingBehavior error handling behavior
   * @return response future
   */
   ResponseFuture sendRequest(Request request, RequestContext requestContext,
      ErrorHandlingBehavior errorHandlingBehavior);

  /**
   * Sends a type-bound REST request, returning a future.
   *
   *
   * @param requestBuilder to invoke {@link RequestBuilder#build()} on to obtain the request
   *                       to send.
   * @param requestContext context for the request
   * @return response future
   */
   ResponseFuture sendRequest(RequestBuilder> requestBuilder, RequestContext requestContext);

  /**
   * Sends a type-bound REST request, returning a future.
   *
   *
   * @param requestBuilder to invoke {@link RequestBuilder#build()} on to obtain the request
   *                       to send.
   * @param requestContext context for the request
   * @param errorHandlingBehavior error handling behavior
   * @return response future
   */
   ResponseFuture sendRequest(RequestBuilder> requestBuilder, RequestContext requestContext,
      ErrorHandlingBehavior errorHandlingBehavior);

  /**
   * Sends a type-bound REST request using a callback.
   *
   * @param request to send
   * @param requestContext context for the request
   * @param callback to call on request completion. In the event of an error, the callback
   *                 will receive a {@link com.linkedin.r2.RemoteInvocationException}. If a valid
   *                 error response was received from the remote server, the callback will receive
   *                 a {@link RestLiResponseException} containing the error details.
   */
   void sendRequest(Request request, RequestContext requestContext, Callback> callback);

  /**
   * Sends a type-bound REST request using a callback.
   *
   * @param requestBuilder to invoke {@link RequestBuilder#build()} on to obtain the request
   *                       to send.
   * @param requestContext context for the request
   * @param callback to call on request completion. In the event of an error, the callback
   *                 will receive a {@link com.linkedin.r2.RemoteInvocationException}. If a valid
   *                 error response was received from the remote server, the callback will receive
   *                 a {@link RestLiResponseException} containing the error details.
   */
   void sendRequest(RequestBuilder> requestBuilder, RequestContext requestContext,
      Callback> callback);

  /**
   * Sends a type-bound REST request, returning a future
   * @param request to send
   * @return response future
   */
   ResponseFuture sendRequest(Request request);

  /**
   * Sends a type-bound REST request, returning a future
   * @param request to send
   * @param errorHandlingBehavior error handling behavior
   * @return response future
   */
   ResponseFuture sendRequest(Request request, ErrorHandlingBehavior errorHandlingBehavior);

  /**
   * Sends a type-bound REST request, returning a future
   *
   * @param requestBuilder to invoke {@link RequestBuilder#build()} on to obtain the request
   *                       to send.
   * @return response future
   */
   ResponseFuture sendRequest(RequestBuilder> requestBuilder);

  /**
   * Sends a type-bound REST request, returning a future
   *
   * @param requestBuilder to invoke {@link RequestBuilder#build()} on to obtain the request
   *                       to send.
   * @param errorHandlingBehavior error handling behavior
   * @return response future
   */
   ResponseFuture sendRequest(RequestBuilder> requestBuilder,
      ErrorHandlingBehavior errorHandlingBehavior);

  /**
   * Sends a type-bound REST request using a callback.
   *
   * @param request to send
   * @param callback to call on request completion. In the event of an error, the callback
   *                 will receive a {@link com.linkedin.r2.RemoteInvocationException}. If a valid
   *                 error response was received from the remote server, the callback will receive
   *                 a {@link RestLiResponseException} containing the error details.
   */
   void sendRequest(Request request, Callback> callback);

  /**
   * Sends a type-bound REST request using a callback.
   *
   * @param requestBuilder to invoke {@link RequestBuilder#build()} on to obtain the request
   *                       to send.
   * @param callback to call on request completion. In the event of an error, the callback
   *                 will receive a {@link com.linkedin.r2.RemoteInvocationException}. If a valid
   *                 error response was received from the remote server, the callback will receive
   *                 a {@link RestLiResponseException} containing the error details.
   */
   void sendRequest(RequestBuilder> requestBuilder, Callback> callback);

  /**
   * Sends a multiplexed request. Responses are provided to individual requests' callbacks.
   *
   * The request is sent using the protocol version 2.0.
   *
   * @param multiplexedRequest the request to send.
   */
  void sendRequest(MultiplexedRequest multiplexedRequest);

  /**
   * Sends a multiplexed request. Responses are provided to individual requests' callbacks. After all responses are
   * received the given aggregated callback is invoked.
   *
   * The request is sent using the protocol version 2.0.
   *
   * @param multiplexedRequest  the multiplexed request to send.
   * @param callback the aggregated response callback.
   */
  void sendRequest(MultiplexedRequest multiplexedRequest, Callback callback);

  /**
   * Sends a multiplexed request. Responses are provided to individual requests' callbacks. After all responses are
   * received the given aggregated callback is invoked.
   *
   * The request is sent using the protocol version 2.0.
   *
   * @param multiplexedRequest  the multiplexed request to send.
   * @param requestContext context for the request
   * @param callback the aggregated response callback.
   */
  void sendRequest(MultiplexedRequest multiplexedRequest, RequestContext requestContext,
      Callback callback);
}