com.mulesoft.connectivity.rest.commons.api.operation

Class BaseRestOperation

java.lang.Object

com.mulesoft.connectivity.rest.commons.api.operation.BaseRestOperation

public abstract class BaseRestOperation
extends Object

Constructor Summary

Constructors

Constructor and Description
BaseRestOperation()

Method Summary

Modifier and Type	Method and Description
protected <E extends Enum<E>> org.mule.runtime.extension.api.exception.ModuleException	createModuleException(org.mule.runtime.http.api.domain.message.response.HttpResponse httpResponse, org.mule.runtime.extension.api.error.ErrorTypeDefinition<E> errorTypeDefinition) Utility method that provides a hook for customizing the ModuleException to be thrown when an HttpResponse is marked as failure based on httpResponseToErrorTypeDefinition().
protected org.mule.runtime.api.metadata.MediaType	getDefaultResponseMediaType() This method specifies the MediaType that should be assumed the response to have in case the remote service doesn't specify a Content-Type header.
protected org.mule.runtime.api.el.ExpressionLanguage	getExpressionLanguage()
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) Given the default response media type obtained by resolveDefaultResponseMediaType(RestConfiguration) and the HttpResponse it will get the MediaType from the HttpHeaders.Names.CONTENT_TYPE or use the defaultResponseMediaType provided as parameter (which should be obtained from resolveDefaultResponseMediaType(RestConfiguration).
protected Function<org.mule.runtime.http.api.domain.message.response.HttpResponse,Optional<org.mule.runtime.extension.api.error.ErrorTypeDefinition<? extends Enum<?>>>>	httpResponseToErrorTypeDefinition() Template method that allows usage of custom ErrorTypeDefinition's for cause where SaaS is not Restful complaint or signal success error responses are returned.
protected <P,A,T> Function<Throwable,T>	notifyCompletionCallbackError(org.mule.runtime.extension.api.runtime.process.CompletionCallback<P,A> completionCallback) Utility method that provides a Function responsible for handling Throwables and notify the CompletionCallback on non-blocking operations only.
protected org.mule.runtime.api.metadata.MediaType	resolveDefaultResponseMediaType(RestConfiguration config) Resolves the default MediaType to be used when processing the response.
protected Function<org.mule.runtime.http.api.domain.message.response.HttpResponse,org.mule.runtime.http.api.domain.message.response.HttpResponse>	throwModuleExceptionIfErrorResponse() Utility method that provides a Function responsible for checking the HttpResponse and based on httpResponseToErrorTypeDefinition() the error type definition function defines if the response should be treated as error or not.
protected Function<Throwable,org.mule.runtime.extension.api.exception.ModuleException>	toConnectivityErrorFunction() Template method that allows usage of custom ErrorTypeDefinition's for general errors like TimeoutException or a generic error such as RestError.CONNECTIVITY.

Methods inherited from class java.lang.Object

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

Constructor Detail

BaseRestOperation

public BaseRestOperation()

Method Detail

getExpressionLanguage

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

throwModuleExceptionIfErrorResponse

protected final Function<org.mule.runtime.http.api.domain.message.response.HttpResponse,org.mule.runtime.http.api.domain.message.response.HttpResponse> throwModuleExceptionIfErrorResponse()

Utility method that provides a Function responsible for checking the HttpResponse and based on httpResponseToErrorTypeDefinition() the error type definition function defines if the response should be treated as error or not.
Be aware that operations that make usage of this logic to throw errors should be annotated with Mule's SDK: @Throws(RestfullErrorTypeProvider.class) if the httpResponseToErrorTypeDefinition() has not been overridden to change the org.mule.sdk.api.annotation.error.ErrorTypeProvider.
Example of usage in case of blocking operations:

 HttpResponse httpResponse = connection.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 operations:

  connection.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 ->...)
 

Returns:

a Function to be applied after obtaining the CompletableFuture from the RestConnection 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.

httpResponseToErrorTypeDefinition

protected Function<org.mule.runtime.http.api.domain.message.response.HttpResponse,Optional<org.mule.runtime.extension.api.error.ErrorTypeDefinition<? extends Enum<?>>>> httpResponseToErrorTypeDefinition()

Template method that allows usage of custom ErrorTypeDefinition's for cause where SaaS is not Restful complaint or signal success error responses are returned. By overriding this method in a base abstract class in all the operations it will allow 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() 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 before calling throwModuleExceptionIfErrorResponse() with one that loads in memory the response with an org.mule.runtime.http.api.domain.entity.ByteArrayHttpEntity so it could be consumed more than once.

Returns:

a Function>> to check if the response corresponds to an error.

createModuleException

protected <E extends Enum<E>> org.mule.runtime.extension.api.exception.ModuleException createModuleException(org.mule.runtime.http.api.domain.message.response.HttpResponse httpResponse,
                                                                                                             org.mule.runtime.extension.api.error.ErrorTypeDefinition<E> errorTypeDefinition)

Utility method that provides a hook for customizing the ModuleException to be thrown when an HttpResponse is marked as failure based on httpResponseToErrorTypeDefinition().
Default implementation will generate an error.description based on statusCode " " reasonPhrase.

Type Parameters:

E - ErrorType generic.

Parameters:

httpResponse - the response HttpResponse from the server.

errorTypeDefinition - ErrorTypeDefinition associated to this failure response.

Returns:

a ModuleException with the description and the ErrorTypeDefinition associated.

notifyCompletionCallbackError

protected final <P,A,T> Function<Throwable,T> notifyCompletionCallbackError(org.mule.runtime.extension.api.runtime.process.CompletionCallback<P,A> completionCallback)

Utility method that provides a Function responsible for handling Throwables and notify the CompletionCallback on non-blocking operations only. It will unwrap a CompletionException to get the cause and convert to ModuleException with its corresponding ErrorTypeDefinition. If the exception is already a ModuleException it will be propagated as it may have been thrown by throwModuleExceptionIfErrorResponse().
Example of usage in a non-blocking operation:

 connection.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 -> completionCallback.success(Result.builder()
         .output(IOUtils.toString(httpResponse.getEntity().getContent()))
         .attributes(httpResponse.getStatusCode())
         .attributesMediaType(APPLICATION_JAVA)
         .build()))
     // Converts to a ModuleException with the default generic ErrorType: CONNECTIVITY or TIMEOUT from RestfullError
     // and notifies the completionCallback with the error.
     .exceptionally(notifyCompletionCallbackError(completionCallback));
 

Type Parameters:

P - type for output.

A - type for output attributes.

Parameters:

completionCallback - the CompletionCallback to be notified about the error.

Returns:

a Function to be provided as CompletableFuture.exceptionally(Function) to handle any Throwable that happens during the execution of the completable future. Its responsible for notifying the CompletionCallback and translated to ModuleException the exception with its corresponding ErrorTypeDefinition.

toConnectivityErrorFunction

protected Function<Throwable,org.mule.runtime.extension.api.exception.ModuleException> toConnectivityErrorFunction()

Template method that allows usage of custom ErrorTypeDefinition's for general errors like TimeoutException or a generic error such as RestError.CONNECTIVITY. The implementation should consider that a ModuleException may be passed to this function in which case it should be propagated as it is. By overriding this method in a base abstract class in all the operations it will allow customizing these ErrorTypeDefinition's. If these generic errors are modified the operation should be consistent about the ErrorTypeProvider and most likely httpResponseToErrorTypeDefinition() would need to be overridden too.

Returns:

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

getDefaultResponseMediaType

protected org.mule.runtime.api.metadata.MediaType getDefaultResponseMediaType()

This method specifies the MediaType that should be assumed the response to have in case the remote service doesn't specify a Content-Type header.
By default, this method returns MediaType.APPLICATION_JSON since it's the most common response type. However, this method should be overwritten if a different type of media type is to be expected, or if you know that a certain encoding will be enforced.

Returns:

the MediaType to assign the response in case the server doesn't specify one in its response

resolveDefaultResponseMediaType

protected final org.mule.runtime.api.metadata.MediaType resolveDefaultResponseMediaType(RestConfiguration config)

Resolves the default MediaType to be used when processing the response.

Parameters:

config - RestConfiguration to get the defaultCharset from Mule Runtime.

Returns:

the MediaType.

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)

Given the default response media type obtained by resolveDefaultResponseMediaType(RestConfiguration) and the HttpResponse it will get the MediaType from the HttpHeaders.Names.CONTENT_TYPE or use the defaultResponseMediaType provided as parameter (which should be obtained from resolveDefaultResponseMediaType(RestConfiguration).

 connection.sendAsync(HttpRequest.builder()
     .uri(connection.getBaseUri() + "/accounts/" + accountId)
     .build())
     .thenApply(throwModuleExceptionIfErrorResponse())
     .thenAccept(httpResponse -> completionCallback.success(Result.builder()
         .output(httpResponse.getEntity().getContent())
         .mediaType(getMediaType(httpResponse, resolveDefaultResponseMediaType(configuration)))
         .build()))
     .exceptionally(notifyCompletionCallbackError(completionCallback));
 

Parameters:

response - the HttpResponse

defaultResponseMediaType - to be used if header is missed.

Returns:

MediaType to be set to the org.mule.runtime.extension.api.runtime.operation.Result.Builder#mediaType(MediaType).