Welcome to the first in a multi-part series of blog posts about creating
Eclipse Vert.x applications with
Infinispan. The purpose of this first tutorial is to showcase how to create a REST API.
All the code of this tutorial is available in this GitHub repository. The backend is a Java project using Maven, so all the needed dependencies can be found in the pom.xml.
What is Vert.x ?
Vert.x is a tool-kit for building reactive applications on the JVM. It’s an event driven and non blocking tool-kit. It is based on the
Reactor Pattern, like Node.js, but unlike Node it can easily use all the cores of your machine so you can create highly concurrent and performant applications. Code examples can be found
in this repository.
REST API
Let’s start creating a simple endpoint that will display a welcome message on
'/'.
In Vert.x this is done by creating a
Verticle. A verticle is a unit of deployment and processes incoming events over an event-loop.
Event-loops are used in asynchronous programming models. I won't spend more time here explaining these concepts as this is very well done in this
Devoxx Vert.x talk or in the documentation available
here.
We need to override the
start method, create a
'router' so
'/' requests can be handled, and finally create a http server.
The most important thing to remember about vert.x, is that
we can NEVER EVER call blocking code (we will see how to deal with blocking API's just after). If we do so, we will
block the event loop and we won't be able to serve incoming requests properly.
Run the
main method, go to your browser to
http://localhost:8081/ and we see the welcome message !
Connecting with Infinispan
Now we are going to create a
REST API that uses Infinispan. The purpose here is to post and get names by id.
We are going to use the default cache in Infinispan for this example, and we will connect to it remotely. To do that, we are going to use the
Infinispan hotrod protocol, which is the recommended way to do it (but we could use
REST or
Memcached protocol too)
Start Infinispan locally
The first thing we are going to do is to run an Infinispan Server locally. We download the Infinispan Server from
here, unzip the downloaded file and run
./bin/standalone.sh.
If you are using Docker on Linux, you can use the Infinispan Docker Image Available easily. If you are using Docker for Mac, at the time of this writing there is an issue with internal IP addresses and they can't be called externally. Different workarounds exist to solve the problem, but the easiest thing for this example is simply downloading and running the standalone server locally. We will see how to use the docker image in Openshift just after.
The hotrod server is listening in
localhost:11222.
Connect the client to the server
The code we need to connect with Infinispan from our java application is the following :
This code
is blocking. As I said before,
we can't block the event loop and this will happen if we directly call these API's from a verticle. The code must be called using
vertx.executeBlocking method, and passing a Handler. The code in the handler will be executed from a worker thread pool and will pass the result back asynchronously.
Instead of overriding the
start method, we are going to override
start(Future<Void> startFuture). This way, we are going to be able to handle errors.
To stop the client, the API supplies a non blocking method that can be called when the verticle is stopped, so we are safe on that.
We are going to create an abstract
CacheAccessVerticle where we will initialise the manager and get default cache. When everything is correct and the defautCache variable is initialised, we will log a message and execute the
initSuccess abstract method.
REST API to create names
We are going to add 3 new endpoints.
- GET /api displays the API name
- POST /api/cutenames creates a new name
- GET /api/cutenames/id displays a name by id
CuteNamesRestAPI verticle can now extend this class and override the
initSuccess method instead of the
start method.
POST
Our goal is to use a curl to create a name like this :
curl -X POST \
-H "Content-Type: application/json" \
-d '{"name":"Oihana"}'
"http://localhost:8081/api/cutenames"
For those that are not familiar with basques names, Oihana means 'rainforest' and is a super cute name. Those who know me will confirm that I'm absolutely not biased making this statement.
To read the body content, we need to
add a body handler to the route, otherwise the body won't be parsed. This is done by calling
router.route().handler(BodyHandler.create()).
The handler that will handle the post method in '
/api/cutenames' is a
RoutingContext handler. We want to create a new name in the default cache. For that, we will call
putAsync method from the
defaultCache.
The server responds 201 when the name is correctly created, and 400 when the request is not correct.
GET by id
To create a get endpoint by id, we need to declare a route that will take a parameter
:id. In the route handler, we are going to call
getAsync method.
If we run the main, we can POST and GET names using curl !
curl -X POST -H "Content-Type: application/json" \
-d '{"id":"42", "name":"Oihana"}' \
"http://localhost:8081/api/cutenames"
Cute name added
curl -X GET -H "Content-Type: application/json" \
"http://localhost:8081/api/cutenames/42"
{"name":"Oihana"}
Wrap up
We have learned how to create a REST API with Vert.x, powered by Infinispan. The repository has some unit tests using the
web client. Feedback is more than welcome to improve the code and the provided examples. I hope you enjoyed this tutorial ! On the next tutorial you will learn how to create a
PUSH API.
