Exercise 1 - Develop reactive Endpoints
Last updated
Was this helpful?
Last updated
Was this helpful?
In this exercise you will learn how to develop reactive endpoints with standard Java functionality via and .
The service that will be created is an easier implementation of the 'Web-API' service as described earlier. In this exercise the service only returns some dummy data and doesn't invoke other services.
Let's start by creating a new Quarkus project with a synchronous REST endpoint. Invoke the following command the Cloud Shell.
To better understand which files have been created, run the same command locally and explore the generated code via the editor of your choice.
In order to test the synchronous endpoint which has been created with the command above, run these commands in one terminal in the Cloud Shell.
Open a second terminal in the Cloud Shell and invoke the following command.
You should see the following response.
Next let's create a reactive endpoint. We need a new class 'ArticleResource.java'
and a class 'Article.java'
.
Add the following code to 'Article.java'
.
Exit the Editor via 'Ctrl-X', 'y' and 'Enter'.
Exit the Editor via 'Ctrl-X', 'y' and 'Enter'.
In order to test the reactive endpoint, run these commands in one terminal in the Cloud Shell.
Open a second terminal in the Cloud Shell and invoke the following command.
You should see the following response.
Now the big question is: How does the reactive endpoint work??? Let's go through the code line by line.
Reactive endpoints use the same JAX-RS annotations '@Path'
, '@Get'
and '@Produces'
as synchronous endpoints.
The CompletionStage
is returned immediately, so that the thread is not blocked. Only when it's completed, a callback
is invoked which contains the actual response.
To demonstrate this behavior better, a [CompletableFuture](https://docs.oracle.com/javase/8/docs/api/java/util/concurrent/CompletableFuture.html)
instance is created and returned. CompletableFuture
is an implementation of the CompletionStage
instance. Once the asynchronous code has been completed, a method 'complete'
is invoked on the CompletableFuture
object.
The static method 'CompletableFuture.supplyAsync()'` returns a list of sample articles asynchronously for demo purposes. In this case only one sample article is returned.
The CompletionStage
interface has several methods. Most of them return CompletionStages again. This allows chaining method invocations as done in the sample code. As input parameters functions are passed in via [Java Lambda](https://www.oracle.com/webfolder/technetwork/tutorials/obe/java/Lambda-QuickStart/index.html)
.
The method 'whenComplete'
is triggered after the asynchronous methods have been completed.
Another method of CompletionStage is 'thenApply'
. This method is invoked after the previous asynchronous methods have been completed. The method can be used, for example, to convert data. In the sample code the list of articles is converted in two steps. First the list of article is converted into a JSON array and then the array is converted into a Response object.
The methods 'stream'
and 'map'
are only used for the conversion and not related to reactive programming.
In the same way exceptions and errors can occur for synchronous code, they can happen for asychronous code as well.
However the way to handle them is quite different. When invoking asynchronous methods exceptions cannot be handled via 'catch'
as usual. Instead the method 'exceptionally'
of the interface CompletionStage
is used.
If you want to try out 'exceptionally'
uncomment the line where the InvalidInputParameter exception is thrown.
See with Quarkus
The implementation of the synchronous endpoint is in the class . The annotations @Path, @Get and @Produces are used to define the endpoint via . To learn more about synchronous endpoints, check out the .
Modify the ArticleResource class via nano and add the following skeleton. The complete source is in the .
The key difference is the return type. Rather than returning a object, a with a Response object is returned.
The code below should give you an idea how to handle exceptions. To find out more, read the blog .