Asynchronously Calling RESTful Web Service Endpoints

MicroProfile Fault Tolerance provides the @Asynchronous annotation, which allows RESTful web service endpoints to be invoked asynchronously. This allows the client to continue processing and not block when invoking a service that may take a long time. This is especially useful when the client has to call multiple services that may each take a while to return; by invoking them asynchronously, these services can execute in parallel, reducing the time the client would have to wait to get the results.

The @Asynchronous annotation can be applied to methods in request scoped CDI beans; the method must return an implementation of either Future or CompletionStage interfaces. A return type of CompletionStage is preferred as in this case any other fault tolerance annotations applied to the method will still be applied if the invoked method throws an exception; this is not the case with methods returning Future.

Recall that we can turn any RESTful web service into a CDI bean simply by applying one of the scope annotations, such as @RequestScoped.

As we can see in the example, all we have to do is annotate any methods to be invoked asynchronously with @Asynchronous and make sure the method returns either a Future or a CompletionStage; when a client invokes our asynchronous methods, control goes back immediately to the client; the client won’t block waiting for a result.

One of the invoked methods takes approximately five seconds to return a value; the other one takes approximately seven seconds. Had we called this method synchronously, the client would have had to wait approximately 12 seconds to obtain both results; since we are calling them asynchronously (they run in parallel), the client only has to block for approximately seven seconds to obtain both results.

Limit Concurrent Execution to Avoid Overloading the System

MicroProfile Fault Tolerance provides the @Bulkhead annotation, named after the Bulkhead design pattern, since it allows us to implement this pattern with minimal effort. @Bulkhead can be used to specify the maximum number of concurrent instances for a RESTful web service endpoint.

There are two ways to use the @Bulkhead annotation: the semaphore style and the thread pool style.

Stop Invoking Repeatedly Failing Endpoints

The @CircuitBreaker annotation allows us to stop invoking endpoints that fail past a threshold; by default, if at least 50% of the last 20 invocations to an endpoint fail, then invocations to that method will stop; instead, the MicroProfile runtime will throw a CircuitBreakerOpenException. We can specify the number of invocations used and the ratio of failed requests via the requestVolumeThreshold and failureRatio attributes of @CircutiBreaker, respectively

After a specified delay (defaulting to 500 milliseconds), the circuit is half opened, meaning that number of requests (default of one request) from are allowed to pass through and invoke the operation; if these requests are successful, the circuit is automatically closed, allowing further requests to access the endpoint; if at least one of these requests fails, the circuit is reopened, preventing any further calls to the endpoint. We can specify the delay to use before half-opening the circuit via the delay attribute of @CircuitBreaker and the unit of time for the delay via its delayUnit attribute; the default unit of time is milliseconds.

For illustration purposes, in our example, we are deliberately throwing an exception when we receive a value of false as a query parameter. In our endpoint, we are using the last three invocations to our endpoint to calculate the threshold, as specified by the requestVolumeThreshold attribute to @CircuitBreaker. We specify the ratio of failed calls as .66 via the failureRatio attribute; in this case, since our request volume threshold is 3 and the failure ratio is .66, the circuit will open after two out of three consecutive calls fail.

In our example, we are specifying a delay of one second before we half-open the circuit; the number of seconds is specified in the delay attribute of @CircuitBreaker and the unit of time in the corresponding delayUnit attribute.

Recall that in our service, we are deliberately throwing an exception when it receives a value of false for its success path parameter; as such, the first invocation to the service succeeds, and the next two fail; since we met the threshold of failed requests, the circuit opens.

The next invocation to the service failed, even though we are passing a value of true; the reason it fails is because the circuit breaker is now open. After the specified delay of one second, the circuit breaker is half open; therefore, calls are allowed to reach the endpoint; the last call from our client succeeds. Since we specified a success threshold of 2 via the successThreshold attribute of @CircuitBreaker, at this point, the circuit breaker remains in half-open state; if the next request succeeds, the circuit is then closed; if it fails, it will be opened.

Providing an Alternative Solution When Execution Fails

To specify a fallback method, we simply indicate the method name as a String as the value of the fallbackMethod attribute of @Fallback; the fallback method must have the same return type and parameters as the potentially failing endpoint; notice in our example, both the method implementing the endpoint and the fallback method return a String and take a single boolean as a parameter; in general, the return value and the parameter types of the endpoint and corresponding fallback method must match.

Using a fallback method is great if we wish to implement alternate functionality if our endpoint ends; however, what if instead we would like to get some diagnostic information about the failing endpoint? In that case, we can indicate a fallback handler class via the value attribute of @Fallback. A fallback handler must be a class implementing the FallbackHandler interface; this interface has a single abstract method called handle() ; this method accepts an instance of ExecutionContext as a parameter; we can use this parameter to obtain information about the failing method.

Our FallbackHandler implementation must be a CDI bean; the easiest way to turn it into one is to use one of the scope annotations; for FallbackHandler implementations, it is usually a good idea to use the @Dependent pseudoscope, which will cause the FallbackHandler implementation to use the same scope as the RESTful web service utilizing it.

The FallbackHandler interface has a generic type argument; its abstract handle() method returns the type we specify, which, in our example, is String; its handle() method is automatically invoked by the MicroProfile runtime; it passes an instance of a class implementing the ExecutionContext interface, which we can use to obtain information about the failed invocation. As shown in the example, we can invoke its getFailure() method to obtain the Throwable (typically an Exception) that was thrown from the endpoint.

Additionally, we can invoke ExecutionContext.getMethod() to obtain a reference to the method that failed; we can obtain the method name as a String by invoking its getName() method.

Finally, we can obtain the arguments that were passed to the failing endpoint by invoking the getParameters() method on ExecutionContext.

Our example sends this information to the Payara Micro log and returns a String to the client.

As seen in the example, all we have to do to defer to a FallbackHandler implementation in case of failure is to add the FallbackHandler class as the value of the @Fallback annotation.

Retrying Execution in Case of Failure

We use this bean in our endpoint to force a failure so that we can demonstrate the @Retry annotation in action.

Defining a Maximum Duration for Execution

MicroProfile Fault Tolerance provides a @Timeout annotation we can use to specify the maximum time to allow a RESTful web service endpoint to execute. If the method takes longer than the specified amount of time, a TimeoutException is thrown.

In our example, we are specifying that our RESTful web service endpoint should not take more than three seconds to execute, as can be seen in the example, how long to wait before a timeout is specified by combining the value and unit attributes of @Timeout, with the former containing a long value and the latter containing the unit of time. Default values for value and unit are 1000L and ChronoUnit.MILLIS (milliseconds), for a default timeout value of one second. In our example, we are simply suspending execution for the amount of seconds received as a query parameter; this way, we can force the endpoint to time out so that we can see it in action.

As we can see from the output of the curl command, we receive an HTTP error 500; the response body we receive is automatically generated by Payara Micro; by examining the output, we can see that a TimeoutException was thrown; this is the expected behavior since the endpoint took longer than the specified timeout of three seconds.

Summary

In this chapter, we covered Payara Micro’s support for the MicroProfile Fault Tolerance API.

We discussed how to make RESTful web services asynchronous so that clients don’t have to block waiting for them to return.

We also saw how we can limit the number of concurrent executions of a RESTful service endpoint, preventing a buggy or malicious client from overloading the system.

Additionally, we covered how to transparently stop invocations to an endpoint that keeps repeatedly failing.

Also, we saw how we can automatically invoke a fallback implementation when a RESTful web service fails.

Additionally, we saw how to automatically retry failed RESTful service endpoint invocations; lastly, we covered how to specify the maximum amount of time we allow an endpoint to execute before it times out.