com.mulesoft.connectivity.rest.commons.api.connection

Class BaseRestConnection<E extends org.mule.runtime.extension.api.exception.ModuleException,T extends org.mule.runtime.extension.api.error.ErrorTypeDefinition<? extends Enum<?>>>

java.lang.Object

com.mulesoft.connectivity.rest.commons.api.connection.BaseRestConnection<E,T>

Type Parameters:

T - defines the ErrorType enumeration.

All Implemented Interfaces:

RestConnection

Direct Known Subclasses:

DefaultRestConnection

public abstract class BaseRestConnection<E extends org.mule.runtime.extension.api.exception.ModuleException,T extends org.mule.runtime.extension.api.error.ErrorTypeDefinition<? extends Enum<?>>>
extends Object
implements RestConnection

Base class for implementing RestConnection which provides an implementation based on HttpClient and supports for error handling which allow to be customized by sub classing with template methods.

Constructor Summary

Constructors

Constructor and Description
BaseRestConnection(org.mule.runtime.http.api.client.HttpClient httpClient, org.mule.runtime.http.api.client.HttpRequestOptions httpRequestOptions, String baseUri, org.mule.runtime.api.el.ExpressionLanguage expressionLanguage)

Method Summary

Modifier and Type	Method and Description
protected void	authenticate(org.mule.runtime.http.api.domain.message.request.HttpRequestBuilder httpRequestBuilder) Allows to different type of connections to intercept the request before sending the HTTP call.
protected org.mule.runtime.http.api.domain.message.request.HttpRequest	beforeRequest(org.mule.runtime.http.api.domain.message.request.HttpRequest request)
protected abstract E	createModuleException(org.mule.runtime.http.api.domain.message.response.HttpResponse httpResponse, T errorTypeDefinition, org.mule.runtime.api.metadata.MediaType mediaType) Utility method that provides a hook for customizing the E to be thrown when an HttpResponse is marked as failure based on httpResponseToErrorTypeDefinition(HttpResponse, MediaType).
String	getBaseUri()
protected CommonsExpressionLanguage	getCommonsExpressionLanguage()
protected org.mule.runtime.api.el.ExpressionLanguage	getExpressionLanguage()
protected org.mule.runtime.http.api.client.HttpClient	getHttpClient()
protected org.mule.runtime.http.api.client.HttpRequestOptions	getHttpRequestOptions()
protected org.mule.runtime.api.metadata.MediaType	getMediaType(org.mule.runtime.http.api.domain.message.response.HttpResponse response, org.mule.runtime.api.metadata.MediaType defaultResponseMediaType)
protected abstract Optional<T>	httpResponseToErrorTypeDefinition(org.mule.runtime.http.api.domain.message.response.HttpResponse httpResponse, org.mule.runtime.api.metadata.MediaType mediaType) Template method that allows usage of custom ErrorTypeDefinition's for those scenarios where SaaS is not Restful complaint or signal success error responses are returned with 20x responses.
protected abstract org.mule.runtime.http.api.domain.entity.HttpEntity	materializeHttpResponseEntity(org.mule.runtime.http.api.domain.entity.HttpEntity httpEntity) Whenever the connection implementation needs to handle signal error responses which are 200 response status code the method httpResponseToErrorTypeDefinition(HttpResponse, MediaType) would be implemented in order to read the entity content response to check for the signal error flag.
HttpResponseResult	send(org.mule.runtime.http.api.domain.message.request.HttpRequest request, org.mule.runtime.api.metadata.MediaType defaultResponseMediaType) Synchronous invocation of the HttpRequest against the connection.
CompletableFuture<HttpResponseResult>	sendAsync(org.mule.runtime.http.api.domain.message.request.HttpRequest request, org.mule.runtime.api.metadata.MediaType defaultResponseMediaType) Asynchronous invocation of the HttpRequest against this connection.
protected org.mule.runtime.http.api.domain.message.response.HttpResponse	throwModuleExceptionIfErrorResponse(org.mule.runtime.http.api.domain.message.response.HttpResponse httpResponse, org.mule.runtime.api.metadata.MediaType mediaType) Utility method that provides a Function responsible for checking if the HttpResponse should be treated as error, based on httpResponseToErrorTypeDefinition(HttpResponse, MediaType) error type definition function.
protected abstract E	toConnectivityErrorFunction(Throwable throwable) Template method that allows usage of custom ErrorTypeDefinition's for general errors like TimeoutException or IOException which are thrown by the HttpClient API.
protected HttpResponseResult	toResult(org.mule.runtime.http.api.domain.message.response.HttpResponse httpResponse, org.mule.runtime.api.metadata.MediaType mediaType)
org.mule.runtime.api.connection.ConnectionValidationResult	validate(org.mule.runtime.http.api.domain.message.request.HttpRequest request, Function<org.mule.runtime.http.api.domain.message.response.HttpResponse,org.mule.runtime.api.connection.ConnectionValidationResult> whenComplete, Function<Exception,org.mule.runtime.api.connection.ConnectionValidationResult> onError) Executes the HttpRequest and validates the response to generate the corresponding ConnectionValidationResult.

Methods inherited from class java.lang.Object

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

Constructor Detail

BaseRestConnection

public BaseRestConnection(org.mule.runtime.http.api.client.HttpClient httpClient,
                          org.mule.runtime.http.api.client.HttpRequestOptions httpRequestOptions,
                          String baseUri,
                          org.mule.runtime.api.el.ExpressionLanguage expressionLanguage)

Method Detail

getHttpClient

protected org.mule.runtime.http.api.client.HttpClient getHttpClient()

getHttpRequestOptions

protected org.mule.runtime.http.api.client.HttpRequestOptions getHttpRequestOptions()

getBaseUri

public String getBaseUri()

Specified by:

getBaseUri in interface RestConnection

Returns:

the base uri of the REST API being consumed. Could be null.

getExpressionLanguage

protected org.mule.runtime.api.el.ExpressionLanguage getExpressionLanguage()

getCommonsExpressionLanguage

protected CommonsExpressionLanguage getCommonsExpressionLanguage()

sendAsync

public CompletableFuture<HttpResponseResult> sendAsync(org.mule.runtime.http.api.domain.message.request.HttpRequest request,
                                                       org.mule.runtime.api.metadata.MediaType defaultResponseMediaType)

Description copied from interface: RestConnection

Asynchronous invocation of the HttpRequest against this connection. Allows non-blocking operations to fulfil the SDK contract for non-blocking support in connectors.

Specified by:

sendAsync in interface RestConnection

Parameters:

request - to be executed.

defaultResponseMediaType - to be used if the server doesn't specify one with the HttpHeaders.Names.CONTENT_TYPE header.

Returns:

HttpResponseResult > to handle the async response. CompletableFuture will success if the response from the server is success, case of a failure a ModuleException would be passed to the completeExceptionally. The HttpResponseResult provides the MediaType for the output InputStream.

getMediaType

protected final org.mule.runtime.api.metadata.MediaType getMediaType(org.mule.runtime.http.api.domain.message.response.HttpResponse response,
                                                                     org.mule.runtime.api.metadata.MediaType defaultResponseMediaType)

toResult

protected HttpResponseResult toResult(org.mule.runtime.http.api.domain.message.response.HttpResponse httpResponse,
                                      org.mule.runtime.api.metadata.MediaType mediaType)

send

public HttpResponseResult send(org.mule.runtime.http.api.domain.message.request.HttpRequest request,
                               org.mule.runtime.api.metadata.MediaType defaultResponseMediaType)
                        throws E extends org.mule.runtime.extension.api.exception.ModuleException

Description copied from interface: RestConnection

Synchronous invocation of the HttpRequest against the connection. Used for design operations like value providers or even for paging operations where non-blocking is not supported by SDK.

Specified by:

send in interface RestConnection

Parameters:

request - to be executed.

defaultResponseMediaType - to be used if the server doesn't specify one with the HttpHeaders.Names.CONTENT_TYPE header.

Returns:

with the response body and HTTP protocol attributes from the server. The HttpResponseResult provides the MediaType for the output InputStream.

Throws:

E extends org.mule.runtime.extension.api.exception.ModuleException

validate

public org.mule.runtime.api.connection.ConnectionValidationResult validate(org.mule.runtime.http.api.domain.message.request.HttpRequest request,
                                                                           Function<org.mule.runtime.http.api.domain.message.response.HttpResponse,org.mule.runtime.api.connection.ConnectionValidationResult> whenComplete,
                                                                           Function<Exception,org.mule.runtime.api.connection.ConnectionValidationResult> onError)

Description copied from interface: RestConnection

Executes the HttpRequest and validates the response to generate the corresponding ConnectionValidationResult.

Specified by:

validate in interface RestConnection

Parameters:

request - to be executed.

whenComplete - to process an HttpResponse and return a ConnectionValidationResult.

onError - to process an Exception, that happened from client side before calling the server, and return a ConnectionValidationResult.

Returns:

a ConnectionValidationResult.

beforeRequest

protected org.mule.runtime.http.api.domain.message.request.HttpRequest beforeRequest(org.mule.runtime.http.api.domain.message.request.HttpRequest request)

authenticate

protected void authenticate(org.mule.runtime.http.api.domain.message.request.HttpRequestBuilder httpRequestBuilder)

Allows to different type of connections to intercept the request before sending the HTTP call. This would be useful for Bearer, API Key or OAuth connections which need to include headers for authentication.

Parameters:

httpRequestBuilder - HttpRequestBuilder populated with the values from the original HttpRequest.

throwModuleExceptionIfErrorResponse

protected final org.mule.runtime.http.api.domain.message.response.HttpResponse throwModuleExceptionIfErrorResponse(org.mule.runtime.http.api.domain.message.response.HttpResponse httpResponse,
                                                                                                                   org.mule.runtime.api.metadata.MediaType mediaType)

Utility method that provides a Function responsible for checking if the HttpResponse should be treated as error, based on httpResponseToErrorTypeDefinition(HttpResponse, MediaType) error type definition function.
Be aware that operations that make usage of this connection which throws errors should be annotated with Mule's SDK: @Throws(RestfullErrorTypeProvider.class), if the httpResponseToErrorTypeDefinition(HttpResponse, MediaType) has not been overridden to change the ErrorTypeProvider.
Example of usage in case of blocking requests:

 HttpResponse httpResponse = httpClient.send(HttpRequest.builder()
                          .uri(connection.getBaseUri() + "/accounts/" + accountId)
                          .build());
 // Check if the HTTP response is not success based on RestfullError and throws a ModuleException
 httpResponse = throwModuleExceptionIfErrorResponse().apply(httpResponse);
 ...
 

Example of usage in case of non-blocking requests:

  httpClient.sendAsync(HttpRequest.builder()
                          .uri(connection.getBaseUri() + "/accounts/" + accountId)
                          .build())
  // Check if the HTTP response is not success based on RestfullError and throws a ModuleException.
 .thenApply(throwModuleExceptionIfErrorResponse())
 .thenAccept(httpResponse ->...)
 

Parameters:

mediaType - to read the entity content from server.

Returns:

a Function to be applied after obtaining the CompletableFuture from the HttpClient invocation as it applies the decision logic to define if the HttpResponse is a failure or success response. If it is defined as an error a ModuleException is thrown with its associated ErrorTypeDefinition.

materializeHttpResponseEntity

protected abstract org.mule.runtime.http.api.domain.entity.HttpEntity materializeHttpResponseEntity(org.mule.runtime.http.api.domain.entity.HttpEntity httpEntity)

Whenever the connection implementation needs to handle signal error responses which are 200 response status code the method httpResponseToErrorTypeDefinition(HttpResponse, MediaType) would be implemented in order to read the entity content response to check for the signal error flag. If this is done without materializing the HttpEntity it won't later allow the client which made the request to be executed by the connection to consume the response. Therefore, this method allows to materialize the entity so it would allow to be read more than once.

Parameters:

httpEntity - the server's response.

Returns:

an HttpEntity that allows to be read more than once.

httpResponseToErrorTypeDefinition

protected abstract Optional<T> httpResponseToErrorTypeDefinition(org.mule.runtime.http.api.domain.message.response.HttpResponse httpResponse,
                                                                 org.mule.runtime.api.metadata.MediaType mediaType)

Template method that allows usage of custom ErrorTypeDefinition's for those scenarios where SaaS is not Restful complaint or signal success error responses are returned with 20x responses. By overriding this method in a custom connection implementation allows customizing ErrorTypeDefinition's. If the function returns an Optional.empty() it means the HttpResponse is a success. If this method is overridden most like toConnectivityErrorFunction(Throwable) would need to be too as it uses RestError for generic errors.
For scenarios like signal error responses with success status code responses it is recommended to materialize the HttpResponse entity content with an in memory implementation such is ByteArrayHttpEntity by overwritten materializeHttpResponseEntity(HttpEntity) so it could be consumed more than once, to check the body content for signal error and if it not an error by the client when processing the response.

Parameters:

httpResponse - the response HttpResponse from the server.

mediaType - to read the entity content from server.

Returns:

a Optional to check if the response corresponds to an error.

createModuleException

protected abstract E createModuleException(org.mule.runtime.http.api.domain.message.response.HttpResponse httpResponse,
                                           T errorTypeDefinition,
                                           org.mule.runtime.api.metadata.MediaType mediaType)

Utility method that provides a hook for customizing the E to be thrown when an HttpResponse is marked as failure based on httpResponseToErrorTypeDefinition(HttpResponse, MediaType).
Default implementation will generate an error.description based on statusCode " " reasonPhrase.
It is recommended to write in the connector's base code a specific E that also implements ErrorMessageAwareException so it associates the HttpResponse body as payload and the attributes representation's for the response.

Parameters:

httpResponse - the response HttpResponse from the server.

errorTypeDefinition - ErrorTypeDefinition associated to this failure response.

mediaType - to read the entity content from server.

Returns:

a E with the description and the ErrorTypeDefinition associated.

toConnectivityErrorFunction

protected abstract E toConnectivityErrorFunction(Throwable throwable)

Template method that allows usage of custom ErrorTypeDefinition's for general errors like TimeoutException or IOException which are thrown by the HttpClient API. The implementation should consider that a E may be passed to this function in which case it should be propagated as it is. By overriding this method in a custom connection implementation it will allow customizing these ErrorTypeDefinition's.

Returns:

a Function to handle a Throwable and return a E with its corresponding ErrorTypeDefinition.