Enhanced Mapping of Java Objects to Hashes

The Spring Data Redis (SDR) framework makes it easy to write Spring applications that use the Redis as a store for Java objects (POJOs) by eliminating the redundant tasks and boilerplate code required for interacting with the store through Spring’s excellent infrastructure support.

Redis OM Spring, builds on top of SDR to improve and optimize the interaction with Redis by leveraging Redis' rich module ecosystem. For Java objects mapped with SDR's @RedisHash annotation we enhance the object-mapping by:

• •Eliminating the need for client-side maintained secondary indices and instead using Redis' native Search and Query engine.
• •Implementing dynamic repository finders with fast and flexible querying
• •Using ULIDs instead of traditional UUIDs for performance, readability and interoperability

You will build an application that stores User POJOs (Plain Old Java Objects) as Redis Hashes.

• •About 15 minutes
• •A favorite text editor or IDE
• •JDK 11 or later
• •Gradle 4+ or Maven 3.2+
• •Docker / Docker Compose

We'll start by creating a base SpringBoot application using the Spring Initializr. You can use this pre-initialized project and click Generate to download a ZIP file. This project is configured to fit the examples in this tutorial.

To configure the project:

• •Navigate to https://start.spring.io. This service pulls in all the dependencies you need for an application and does most of the setup for you.
• •Choose either Gradle or Maven and the language you want to use. This guide assumes that you chose Java.
• •Click and select , and .
• •Click .
• •Download the resulting ZIP file (roms-hashes.zip), which is an archive of a web application that is configured with your choices.

The dependencies included are:

• •: Build web/RESTful applications using Spring MVC. It will allow us to expose our app as a web service.
• •: Java annotation library which helps to reduce boilerplate code.
• •: Provides fast application restarts, LiveReload, and configurations for enhanced development experience.

To use Redis OM Spring, open the pom.xml file and add the Redis OM Spring Maven dependency to the pom.xml file dependencies element:

If using gradle add the dependency as follows:

The generated application contains a single Java file, the @SpringBootApplication annotated main application. To enable Spring Data Redis repositories, we also need to annotate the main or the configuration class with @EnableRedisEnhancedRepositories as well as the @Configuration annotation.

Redis OM Spring relies on the power of Redis Stack. The docker compose YAML file below can get started quickly. You can place at the root folder of your project and name it docker-compose.yml:

To launch the docker compose application, on the command line (or via Docker Desktop), clone this repository and run (from the root folder):

Let's also launch an instance of the Redis CLI so that we can spy on what ROMS is doing. To do so we'll launch Redis in monitor mode:

We'll have a single class in our application, the User class. We'll use lombok to avoid having to create getters and setters. We'll use the lombok annotations @Data, @RequiredArgsConstructor and @AllArgsConstructor.

Finally, to mark the class as a JSON document, we use the @Document annotation.

We use Spring Data Redis @RedisHash annotation. The property named id is annotated with org.springframework.data.annotation.Id. Those two items are responsible for creating the actual key used to persist the Hash in Redis.

The User class has a firstName, middleName and lastName, as well as an email property.

Let's add a few User POJOs to Redis on application start-up by modify the RomsHashesApplication class to include the newly created UserRepository using the @Autowired annotation. Then we'll use a CommandLineRunner @Bean annotated method to create four User POJOs and save them to the database.

In the CommandLineRunner we take the following steps:

• •Use the repository deleteAll method to clear the database (be careful with this is production! 🙀)
• •Create four User instances; we'll use the four band members of Rage Against the Machine.
• •Use the repository saveAll method to save all User POJOs in bulk.

Since we are using Spring Boot DevTools, if you already had the application running, it should have restarted/reloaded. If not, use the mvn command to launch the application:

If every goes as expected, you should see the familiar Spring Boot banner fly by:

If you were watching the Redis CLI monitor you should have seen a barrage of output fly by. Let's break it down and inspect it using another Redis CLI so as to understand the inner workings of the system.

At the top you should have seen the FT.CREATE command which using the annotations in our POJO determined an index recipe. Since our POJO is annotated with @Document we get an index ON JSON against any keys starting with com.redis.om.documents.domain.Company: (which is the default key prefix for Spring Data Redis and also for ROMS):

ROMS uses the POJO fields annotated with @Indexed or @Searchable to build the index schema. In the case of the User POJO we have the fields firstName, middleName, lastName and email are all annotated as "indexable", meaning that we can do exact searches over these fields.

Spring Data Redis creates a SET to maintain primary keys for our entities, ROMS inherits this functionality from SDR. The DEL command following the index creation is triggered because of the call to userRepo.deleteAll(); in our data loading method. If we had any saved objects already we would also see calls to delete those individual instances.

For each of the User POJO we should see a sequence of REDIS commands like:

First SDR checks whether the object already exists in the Redis SET of primary keys using the SISMEMBER command. Then, a DEL is issued to remove the Hash, following by a HMSET to write the new or udpated Hash. Finally, the id property of the object is addded to the primary keys set using the SADD command.

Let's inspect the data using the Redis CLI. We'll start by listing the keys prefixed with com.redis.om.hashes.domain.User:

We have 5 matches, one for each of the User POJOs created plus the Redis SET for the primary keys. Let's inspect some of the values.

Let's check what type of data structure is stored in the com.redis.om.documents.domain.Company key:

Knowing that it is a Redis SET, let inspect it's contents using the SMEMBERS command:

The set contains all the Ids of our Users. Now, let's investigate the com.redis.om.documents.domain.Company:01FNRW9V98CYQMV2YAB7M4KFGQ key:

The Redis datatype stored is a hash (a Redis Hash). Let's check its contents using the HGETALL command:

ROMS most compelling feature is the ability to create repository implementations automatically, at runtime, from a repository interface.

Let's start with a simple method declaration in UserRepository that will find a unique instance of User given their lastname.

ROMS uses the method name, parameters and return type to determine the correct query to generate and how to package and return a result.

findOneByLastName return an Optional of User this tells ROMS to return a null payload if the entity is not found. The findOne part also reinforces that even if there are multiple results we are only interested in getting one. ROMS parses the method name to detemined the number of expected parameters, the ByLastName portion of the method tell us we expect 1 single parameter named lastName.

Let's create a REST controller to test the findOneByLastName method. Create the UserController under the package com.redis.om.hashes.controllers as shown:

In our controller, we include our UserRepository and create simple method to respond to a GET request at /api/users/name/{lastName} where {lastName} would be the string parameter we are passing as the lastName to find.

Let's test the endpoint using CURL and passing the exact company name Redis:

Let's format the resulting JSON:

Inspecting the Redis CLI MONITOR we should see the query issued:

Let say that we wanted to find Users by the combination of lastName and firstName, we could add a query declaration to the repository interface like:

In this case method findByFirstNameAndLastName is parsed and the And keyword is used to determine that the method is expecting 2 parameters; firstName and lastName.

To test it we could add the following to our controller:

Using CURL to test we

Formatting the resulting JSON we can see the record for Brad Wilk is returned as the only element of the JSON Array result:

Back on the Redis CLI monitor we can see the query generated by our repository method:

Redis OM Spring, extends Spring Data Redis with search capabilities that rival the flexibility of JPA queries by using Redis' native Search and Query engine.