com.linkedin.restli.client

Class RestClient

java.lang.Object

com.linkedin.restli.client.RestClient

All Implemented Interfaces:

Client

public class RestClient
extends java.lang.Object
implements Client

Subset of Jersey's REST client, omitting things we probably won't use for internal API calls + enforcing the use of Model (stenciled) response entities. We feature:

• Generic client interface (domain-specific hooks are via URIBuilders and Models)
• All request/response entities _must_ be 'Representation', which encapsultes a DataTemplate and hyperlinks
• Batch mode for all REST operations. This is inherently unRESTful, as you are supposed to operate on a single, named resource, NOT an arbitrary, ad-hoc collection of resources. For example, this probably breaks cacheability in proxies, as clients can specify an arbitrary set of IDs in the URI, in any order. Caching that specific batched response is pretty much useless, as no other client will probably look up those same IDs. Same for invalidating resources on POST/PUT. If we can add batch-aware proxies, this may work. In any case, we need batching to reduce latency, chattiness and framing overhead for calls made within and across our datacenters. Semantics of batch operations (atomic/non-atomic, etc) are specified by the server.
• Async invocation
• Client can choose to deal with the 'Response' (including status, headers) or just get the response entity (Model) directly (assuming response was status 200)
• TODO Exceptions at this layer? We clearly can't declare checked exceptions on THIS interface

Features NOT ported from Jersey client

• No support for String URIs
• Clients may define accept MIME types, the expected response entity type, and their preference order. By default clients will send no accept headers and receive responses in and expect the server to send responses in application/json format when there is no accept header.
• TODO Do we need to support Accept-Language header for i18n profile use case?
• No cookies
• No (convenient) synchronous invocation mode (can just call Future.get())

Features in Jersey we should consider

• Standard a way to fetch 'links' from response entities. This would at least open the door for HATEOAS-style REST if we choose to use it in certain places (e.g. collection navigation, secondary actions (like, comment), etc)

Field Summary

Fields inherited from interface com.linkedin.restli.client.Client

MULTIPLEXER_RESOURCE

Constructor Summary

Constructors

Constructor and Description
RestClient(com.linkedin.r2.transport.common.Client client, java.lang.String uriPrefix)
RestClient(com.linkedin.r2.transport.common.Client client, java.lang.String uriPrefix, com.linkedin.restli.common.ContentType contentType, java.util.List<com.linkedin.restli.common.ContentType> acceptTypes) Deprecated. please use RestliRequestOptions to configure content type and accept types.
RestClient(com.linkedin.r2.transport.common.Client client, java.lang.String uriPrefix, java.util.List<com.linkedin.restli.common.ContentType> acceptTypes) Deprecated. please use RestliRequestOptions to configure accept types.

Method Summary

Modifier and Type	Method and Description
java.lang.String	getURIPrefix() Deprecated. Use PrefixAwareRestClient#getPrefix instead.
void	sendRequest(MultiplexedRequest multiplexedRequest) Sends a multiplexed request.
void	sendRequest(MultiplexedRequest multiplexedRequest, com.linkedin.common.callback.Callback<MultiplexedResponse> callback) Sends a multiplexed request.
void	sendRequest(MultiplexedRequest multiplexedRequest, com.linkedin.r2.message.RequestContext requestContext, com.linkedin.common.callback.Callback<MultiplexedResponse> callback) Sends a multiplexed request.
<T> ResponseFuture<T>	sendRequest(Request<T> request) Sends a type-bound REST request, returning a future
<T> void	sendRequest(Request<T> request, com.linkedin.common.callback.Callback<Response<T>> callback) Sends a type-bound REST request using a callback.
<T> ResponseFuture<T>	sendRequest(Request<T> request, ErrorHandlingBehavior errorHandlingBehavior) Sends a type-bound REST request, returning a future
<T> ResponseFuture<T>	sendRequest(Request<T> request, com.linkedin.r2.message.RequestContext requestContext) Sends a type-bound REST request, returning a future.
<T> void	sendRequest(Request<T> request, com.linkedin.r2.message.RequestContext requestContext, com.linkedin.common.callback.Callback<Response<T>> callback) Sends a type-bound REST request using a callback.
<T> ResponseFuture<T>	sendRequest(Request<T> request, com.linkedin.r2.message.RequestContext requestContext, ErrorHandlingBehavior errorHandlingBehavior) Sends a type-bound REST request, returning a future.
<T> ResponseFuture<T>	sendRequest(RequestBuilder<? extends Request<T>> requestBuilder) Sends a type-bound REST request, returning a future
<T> void	sendRequest(RequestBuilder<? extends Request<T>> requestBuilder, com.linkedin.common.callback.Callback<Response<T>> callback) Sends a type-bound REST request using a callback.
<T> ResponseFuture<T>	sendRequest(RequestBuilder<? extends Request<T>> requestBuilder, ErrorHandlingBehavior errorHandlingBehavior) Sends a type-bound REST request, returning a future
<T> ResponseFuture<T>	sendRequest(RequestBuilder<? extends Request<T>> requestBuilder, com.linkedin.r2.message.RequestContext requestContext) Sends a type-bound REST request, returning a future.
<T> void	sendRequest(RequestBuilder<? extends Request<T>> requestBuilder, com.linkedin.r2.message.RequestContext requestContext, com.linkedin.common.callback.Callback<Response<T>> callback) Sends a type-bound REST request using a callback.
<T> ResponseFuture<T>	sendRequest(RequestBuilder<? extends Request<T>> requestBuilder, com.linkedin.r2.message.RequestContext requestContext, ErrorHandlingBehavior errorHandlingBehavior) Sends a type-bound REST request, returning a future.
<T> void	sendRestRequest(Request<T> request, com.linkedin.r2.message.RequestContext requestContext, com.linkedin.common.callback.Callback<com.linkedin.r2.message.rest.RestResponse> callback) Deprecated. as this API will change to private in a future release. Please use other APIs in this class, such as sendRequest(Request,RequestContext, Callback) to send type-bound REST requests. Sends a type-bound REST request and answers on the provided callback.
void	shutdown(com.linkedin.common.callback.Callback<com.linkedin.common.util.None> callback) Shuts down the underlying Client which this RestClient wraps.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

RestClient

public RestClient(com.linkedin.r2.transport.common.Client client,
                  java.lang.String uriPrefix)

RestClient

@Deprecated
public RestClient(com.linkedin.r2.transport.common.Client client,
                              java.lang.String uriPrefix,
                              java.util.List<com.linkedin.restli.common.ContentType> acceptTypes)

Deprecated. please use RestliRequestOptions to configure accept types.

RestClient

@Deprecated
public RestClient(com.linkedin.r2.transport.common.Client client,
                              java.lang.String uriPrefix,
                              com.linkedin.restli.common.ContentType contentType,
                              java.util.List<com.linkedin.restli.common.ContentType> acceptTypes)

Deprecated. please use RestliRequestOptions to configure content type and accept types.

Method Detail

shutdown

public void shutdown(com.linkedin.common.callback.Callback<com.linkedin.common.util.None> callback)

Description copied from interface: Client

Shuts down the underlying Client which this RestClient wraps.

Specified by:

shutdown in interface Client

getURIPrefix

@Deprecated
public java.lang.String getURIPrefix()

Deprecated. Use PrefixAwareRestClient#getPrefix instead.

Returns:

The URI Prefix that this RestClient is using.

sendRequest

public <T> ResponseFuture<T> sendRequest(Request<T> request,
                                         com.linkedin.r2.message.RequestContext requestContext)

Description copied from interface: Client

Sends a type-bound REST request, returning a future.

Specified by:

sendRequest in interface Client

Parameters:

request - to send

requestContext - context for the request

Returns:

response future

sendRequest

public <T> ResponseFuture<T> sendRequest(Request<T> request,
                                         com.linkedin.r2.message.RequestContext requestContext,
                                         ErrorHandlingBehavior errorHandlingBehavior)

Description copied from interface: Client

Sends a type-bound REST request, returning a future.

Specified by:

sendRequest in interface Client

Parameters:

request - to send

requestContext - context for the request

errorHandlingBehavior - error handling behavior

Returns:

response future

sendRequest

public <T> ResponseFuture<T> sendRequest(RequestBuilder<? extends Request<T>> requestBuilder,
                                         com.linkedin.r2.message.RequestContext requestContext)

Description copied from interface: Client

Sends a type-bound REST request, returning a future.

Specified by:

sendRequest in interface Client

Parameters:

requestBuilder - to invoke RequestBuilder.build() on to obtain the request to send.

requestContext - context for the request

Returns:

response future

sendRequest

public <T> ResponseFuture<T> sendRequest(RequestBuilder<? extends Request<T>> requestBuilder,
                                         com.linkedin.r2.message.RequestContext requestContext,
                                         ErrorHandlingBehavior errorHandlingBehavior)

Description copied from interface: Client

Sends a type-bound REST request, returning a future.

Specified by:

sendRequest in interface Client

Parameters:

requestBuilder - to invoke RequestBuilder.build() on to obtain the request to send.

requestContext - context for the request

errorHandlingBehavior - error handling behavior

Returns:

response future

sendRequest

public <T> void sendRequest(Request<T> request,
                            com.linkedin.r2.message.RequestContext requestContext,
                            com.linkedin.common.callback.Callback<Response<T>> callback)

Description copied from interface: Client

Sends a type-bound REST request using a callback.

Specified by:

sendRequest in interface Client

Parameters:

request - to send

requestContext - context for the request

callback - to call on request completion. In the event of an error, the callback will receive a RemoteInvocationException. If a valid error response was received from the remote server, the callback will receive a RestLiResponseException containing the error details.

sendRestRequest

@Deprecated
public <T> void sendRestRequest(Request<T> request,
                                            com.linkedin.r2.message.RequestContext requestContext,
                                            com.linkedin.common.callback.Callback<com.linkedin.r2.message.rest.RestResponse> callback)

Deprecated. as this API will change to private in a future release. Please use other APIs in this class, such as sendRequest(Request,RequestContext, Callback) to send type-bound REST requests. Sends a type-bound REST request and answers on the provided callback.

Parameters:

request - to send

requestContext - context for the request

callback - to call on request completion

sendRequest

public <T> void sendRequest(RequestBuilder<? extends Request<T>> requestBuilder,
                            com.linkedin.r2.message.RequestContext requestContext,
                            com.linkedin.common.callback.Callback<Response<T>> callback)

Description copied from interface: Client

Sends a type-bound REST request using a callback.

Specified by:

sendRequest in interface Client

Parameters:

requestBuilder - to invoke RequestBuilder.build() on to obtain the request to send.

requestContext - context for the request

callback - to call on request completion. In the event of an error, the callback will receive a RemoteInvocationException. If a valid error response was received from the remote server, the callback will receive a RestLiResponseException containing the error details.

sendRequest

public <T> ResponseFuture<T> sendRequest(Request<T> request)

Description copied from interface: Client

Sends a type-bound REST request, returning a future

Specified by:

sendRequest in interface Client

Parameters:

request - to send

Returns:

response future

sendRequest

public <T> ResponseFuture<T> sendRequest(Request<T> request,
                                         ErrorHandlingBehavior errorHandlingBehavior)

Description copied from interface: Client

Sends a type-bound REST request, returning a future

Specified by:

sendRequest in interface Client

Parameters:

request - to send

errorHandlingBehavior - error handling behavior

Returns:

response future

sendRequest

public <T> ResponseFuture<T> sendRequest(RequestBuilder<? extends Request<T>> requestBuilder)

Description copied from interface: Client

Sends a type-bound REST request, returning a future

Specified by:

sendRequest in interface Client

Parameters:

requestBuilder - to invoke RequestBuilder.build() on to obtain the request to send.

Returns:

response future

sendRequest

public <T> ResponseFuture<T> sendRequest(RequestBuilder<? extends Request<T>> requestBuilder,
                                         ErrorHandlingBehavior errorHandlingBehavior)

Description copied from interface: Client

Sends a type-bound REST request, returning a future

Specified by:

sendRequest in interface Client

Parameters:

requestBuilder - to invoke RequestBuilder.build() on to obtain the request to send.

errorHandlingBehavior - error handling behavior

Returns:

response future

sendRequest

public <T> void sendRequest(Request<T> request,
                            com.linkedin.common.callback.Callback<Response<T>> callback)

Description copied from interface: Client

Sends a type-bound REST request using a callback.

Specified by:

sendRequest in interface Client

Parameters:

request - to send

callback - to call on request completion. In the event of an error, the callback will receive a RemoteInvocationException. If a valid error response was received from the remote server, the callback will receive a RestLiResponseException containing the error details.

sendRequest

public <T> void sendRequest(RequestBuilder<? extends Request<T>> requestBuilder,
                            com.linkedin.common.callback.Callback<Response<T>> callback)

Description copied from interface: Client

Sends a type-bound REST request using a callback.

Specified by:

sendRequest in interface Client

Parameters:

requestBuilder - to invoke RequestBuilder.build() on to obtain the request to send.

callback - to call on request completion. In the event of an error, the callback will receive a RemoteInvocationException. If a valid error response was received from the remote server, the callback will receive a RestLiResponseException containing the error details.

sendRequest

public void sendRequest(MultiplexedRequest multiplexedRequest)

Description copied from interface: Client

Sends a multiplexed request. Responses are provided to individual requests' callbacks. The request is sent using the protocol version 2.0.

Specified by:

sendRequest in interface Client

Parameters:

multiplexedRequest - the request to send.

sendRequest

public void sendRequest(MultiplexedRequest multiplexedRequest,
                        com.linkedin.common.callback.Callback<MultiplexedResponse> callback)

Description copied from interface: Client

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.

Specified by:

sendRequest in interface Client

Parameters:

multiplexedRequest - the multiplexed request to send.

callback - the aggregated response callback.

sendRequest

public void sendRequest(MultiplexedRequest multiplexedRequest,
                        com.linkedin.r2.message.RequestContext requestContext,
                        com.linkedin.common.callback.Callback<MultiplexedResponse> callback)

Description copied from interface: Client

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.

Specified by:

sendRequest in interface Client

Parameters:

multiplexedRequest - the multiplexed request to send.

requestContext - context for the request

callback - the aggregated response callback.