Jakarta NoSQL in action: JNopo game

Before you start, this game uses the Maven Wrapper plugin, which means, you just need to have the JDK 21 or later installed in your machine to build and/or run the application.

Yeah! It’s time have fun playing JNopo!

Clone the Git repository:

Navigate to the start directory. This directory contains the starting project that we’ll work through in this post.

This project is ready to run on Open Liberty. You just need to perform the following Maven Wrapper command:

This will install all required dependencies and start the default server.

Now, if everything works, you can play the game by accessing the following URL address:

To play the game locally you just need to open two browsers tabs/windows pointing to the same URL address.

Let’s add the dependencies to create the persistence layer. Our persistence layer will be implemented using Jakarta NoSQL and Jakarta Data. To implement these Jakarta EE specifications, we’ll use Eclipse JNoSQL.

Eclipse JNoSQL offers a database API collection that covers document, key-value, column and graph NoSQL databases. For now, Eclipse JNoSQL supports about 30 NoSQL databases.

For this challenge, let’s develop the persistence layer to integrate with document NoSQL databases type. Eclipse JNoSQL supports various document NoSQL databases. You can find a list of supported databases, along with their configurations and dependencies, on the GitHub repository.

Let’s use MongoDB as the default document database. Add the following Maven dependency into the pom.xml file of the project:

Once you add the appropriate dependency, you need to configure the credentials for your document database. These credentials typically include details such as the database name, host, port, and any required authentication credentials. To configure MongoDB, you can find the supported credentials properties at the Eclipse JNoSQL MongoDB Database API Configuration.

Installing and managing databases locally requires additional efforts that we will not cover it in this blog post. We chose to use Docker Compose as the tooling for managing containers locally. Take a look at the Docker Compose Overview to learn more about this tool.

Let’s create a docker-compose.yml file into the project root directory and add the following content:

For convenience, the previous example added a mongo-express service that allows us to navigate and manage MongoDB data through a friendly web interface.

Now, to start up the databases we just need to run the following command:

You should now be able to access the mongo-express UI at http://localhost:8081/ :

Now that we defined the MongoDB database instance, we can set up the Eclipse JNoSQL framework correctly.

Eclipse JNoSQL uses MicroProfile Config to get the required configurations to establish the connection to the databases. We can define these properties in the resources/META-INF/microprofile-config.properties file by using environment variables. For more information about MicroProfile Config, take a look at External configuration of microservices in the Open Liberty docs.

According to the docker-compose.yml file that we have created previously, we can define the following properties:

Once we add the Eclipse JNoSQL dependencies, the Jakarta NoSQL api comes together as a transient dependency to the project, allowing us to create the NoSQL entities we want.

Let’s model the GameMatch entity, which represents each game match result.

As we said before, Eclipse JNoSQL allows us to use Java Records as entities, so, let’s use this feature:

To represent each player name and movement, let’s model such data as a PlayerInfo record class:

Now, we’ll create a component to store and retrieve such entities from the MongoDB database. It’s common to see developers using patterns like data access object (DAO) to implement these components. That’s not a problem at all, but we use to see them making the components closer to a specific vendor database semantics, raising a vendor lock-in situation.

Nowadays, in the cloud era where we pay as we go, switching between NoSQL solutions can save resources and costs. But vendor lock-in would probably compromise this strategy. Also, other considerations come to the table when there’s a need to switch databases, such as time spent on the change, the learning curve of a new API, the code that will be lost, the persistence layer that needs to be replaced, etc. This is where the flexibility of Jakarta NoSQL shines.

Another interesting point is that DAO components tend to be closer to the database semantics than the business domain model language, requiring a high cognitive load for developers to connect the dots and fill the gaps between the technical codes and business necessities, once the code is not expressive enough, and doesn’t fit with the ubiquitous language of the business. At this point, Jakarta Data comes into play!

Coming back to our challenge, let’s create a repository component that will represents the play-offs:

With the entity and repository already created, we need to capture and persist the results of each game match. The next obvious question is: how could we capture the required game events?

It’s a really good question! The answer is: the Events API provided by the Jakarta Context and Dependency Injection (CDI) specification!

JNopo game uses CDI Events to promote extension points, based on event publishing, to be used as needed. With that, we can implement an @Observable methods on any CDI bean to handle event objects.

See the following GameState interface. Objects that implement this interface will act as event objects:

The GameState interface is a sealed interface that defines all the supported game states. According to the sealed implementation, the event that we’re interested is the GameOver state. Such class is a record class. But it’s not just a simple record class that acts like a data transfer object (DTO), it has useful methods that return important info like:

Now let`s create the GameMatchCapturer bean that captures the emitted GameOver state and stores the game match results in the database:

At this point, let’s instantiate a new GameMatch entity instance, populate it from GameOver data and then store it into the database by using the Playoffs component.

The required Playoff component, which is a repository implementation provided Eclipse JNoSQL, will be injected by CDI using the @Inject and @Database(DOCUMENT) annotations:

Now, let’s start the Open Liberty runtime to figure out if the game match results are being stored on the MongoDB.

After some game matches, we can confirm the persistence of the game matches into the database by looking at Mongo Express running on http://localhost:8081 :

Or, if you’re a command-line practitioner, you can check the data by using the mongosh cli:

Once connected, you can run mongo commands:

Great! JNopo is storing the game match results as expected! It’s time to create the winner ranking and then expose it though a restful endpoint: http://localhost:9080/jakarta-nosql-game/api/playoffs/ranking .

Collecting and storing the game matches enables us to implement the winner ranking feature.

Let’s implement the Ranking class to represent any ranking on the JNopo application.

The Ranking creation requires the data from the Playoffs component. In order to avoid to create a new layer to keep the logic of the ranking creation, I decided to use a simple approach: a simple static factory method on the Ranking class itself.

Firstly, Playoffs needs to provide a method to retrieve the non-tied game results:

Regarding the aggregation process that evolves the ranking logic creation, we used to see developers delegating this aggregation logic to the DBMS and, depending on the persistence mechanism, it should be the best approach. For now, the grouping projection functions like we have with Jakarta Persistence is not available on the Jakarta NoSQL. However, in the future, such capabilities might be available.

In order to keep our implementation free of vendor lock-in, I decided to implement the aggregation process by using the Stream API. I added comments on the code to help you to understand the implemented logic.

Now, let make this ranking be accessible to our model. As the ranking needs the data from the Playoffs component, why not to put the ranking creation on the Playoffs interface? That’s we’re going to do! It is possible since the Java 8:

It looks like we’re getting closer to our goal!

Following the challenge requirements, let’s create the resource component that will expose the winner ranking.

Firstly, let’s create the RestApplication class to define the URL dedicated to restful endpoints:

Now, any URL under /api will be handled by the Jakarta Restful Web Services implementation available in our runtime environment.

Next step: let’s implement the PlayoffsResource resource. This component will expose an HTTP GET endpoint for the /api/playoffs/ranking URL:

It’s time to test everything! Let’s restart the Open Liberty runtime:

Open Liberty provides amazing tooling to help during develop Jakarta EE / MicroProfile applications. When dev mode is running, we can use some HTTP addresses to test and explore the capabilities offered by this amazing Jakarta EE/MicroProfile runtime:

Let’s focus on two of these URLs:

If you’re a command-line practitioner, you can check the data by using the curl command:

Congratulations if you made it this far!

Now, JNopo is providing a winner ranking!

If you’re interested to take a look on the finished project code version developed during this challenge, clone this Git repository and then navigate to the winner-ranking-challenge directory.