Coder Legion - Recent posts tagged spring

The Heart of B3: Building the Matching Engine with RabbitMQ, Redis and Spring Boot

Sun, 10 May 2026 21:29:07 +0000

Hello everyone!

Continuing the My Broker B3 series, we've reached one of the most anticipated components of the ecosystem: the B3 Matching Engine API.

In the previous post, we built b3-market-sync-api which synchronizes real prices from brapi.dev and stores them in Redis. Now it's time to use that data — this is the service that simulates the stock exchange itself, deciding whether a buy or sell order will be executed or rejected based on the prices we just put in cache.

️ What is the Matching Engine?

In the real world, when you place a buy order through your broker, it gets sent to B3, which checks whether there's a counterpart willing to trade at that price. This process is called matching.

In our simulator, the b3-matching-engine-api reproduces this logic in a simplified way:

Intake: Receives the order from the broker via RabbitMQ (queue mq-broker-to-b3)
Price: Fetches the current asset price from Redis (market:price:{TICKER}) — data injected by the Market Sync we built previously
Decision: Applies the matching rule
Persistence: Records the result in PostgreSQL
Notification: Returns the result to the broker via RabbitMQ (queue mq-b3-to-broker)

[Broker] ──RabbitMQ──▶ [mq-broker-to-b3] ──▶ [Matching Engine]
                                                      │
                                             Redis: market:price:{TICKER}
                                             (fed by Market Sync ⬆️)
                                                      │
                                         ┌────────────┴────────────┐
                                      FILLED                   REJECTED
                                         │                         │
                                   PostgreSQL                 PostgreSQL
                                         │                         │
                               [mq-b3-to-broker] ◀────────────────┘
                                         │
                                      [Broker]

MVP Focus

Before diving into the code, same disclaimer as previous posts: we're building the foundation. The goal is to have an end-to-end flow working with enough robustness to validate the POC.

In this phase, I prioritized:

End-to-end flow working correctly
Proper failure handling (no orders silently disappearing)
Dead Letter Queue for messages that fail during processing
REST API for querying execution history
Swagger documentation

️ Tech Stack

Technology	Usage
Java 21 + Spring Boot 3.5	Service core
Spring RabbitMQ	Order intake and result notification
Spring Data Redis	Real-time price lookup
Spring Data JPA + PostgreSQL	Execution persistence
Flyway	Database schema versioning
SpringDoc OpenAPI	Swagger UI documentation

️ Implementation Pillars

1. RabbitMQ Configuration

A critical lesson learned here: never rely on queues already existing in the broker. If the application starts before RabbitMQ has the queues created, the consumer fails on startup.

The solution is to declare all infrastructure beans directly in Spring — it ensures queues, exchanges and bindings exist before any message is processed:

@Bean
public DirectExchange exchange() {
    return new DirectExchange(exchangeName);
}

@Bean
public Queue queueIn() {
    return QueueBuilder.durable(queueIn)
            .withArgument("x-dead-letter-exchange", dlxName)
            .withArgument("x-dead-letter-routing-key", dlqName)
            .build();
}

@Bean
public Binding bindingQueueIn(Queue queueIn, DirectExchange exchange) {
    return BindingBuilder.bind(queueIn).to(exchange).with(routingKey);
}

Note the withArgument calls — they configure the Dead Letter Queue directly in the main queue declaration. Any message that fails processing is automatically redirected.

2. The Matching Logic

The heart of the service. The rule is straightforward:

BUY: If the price the user accepts to pay >= market price → FILLED
SELL: If the price the user wants to receive <= market price → FILLED
Otherwise → REJECTED

private static boolean isCanExecute(OrderEventDTO order, BigDecimal marketPrice) {
    if (SideStatus.BUY.name().equalsIgnoreCase(order.getSide())) {
        return order.getPrice().compareTo(marketPrice) >= 0;
    } else if (SideStatus.SELL.name().equalsIgnoreCase(order.getSide())) {
        return order.getPrice().compareTo(marketPrice) <= 0;
    }
    return false;
}

3. Failure Handling — No Silent Order Loss

A silent bug I identified: when the ticker wasn't in Redis, the method simply returned without doing anything. The broker would wait for a response that never came.

The fix was simple but critical — any failure must notify the broker:

if (marketDataOpt.isEmpty()) {
    log.warn("Price for ticker {} not found in Redis. Rejecting order {}",
             order.getTicker(), order.getOrderId());
    OrderResponseEvent response = new OrderResponseEvent(
        order.getOrderId(), ExecutionStatus.REJECTED.name(), BigDecimal.ZERO);
    orderProducer.sendToBroker(response);
    return;
}

This is exactly why we built b3-market-sync-api first. If Redis doesn't have the price, the order is immediately rejected — correct and predictable behavior.

4. Transactional Guarantee

Another critical point: persisting to PostgreSQL and publishing to RabbitMQ are two distinct operations. If the database saves but the publish fails, the execution is recorded but the broker is never notified — silent inconsistency.

The solution was adding @Transactional to the method that orchestrates both operations:

@Transactional
private void saveAndNotify(OrderEventDTO order, BigDecimal price, ExecutionStatus status) {
    // 1. Persists in PostgreSQL
    OrderExecution execution = OrderExecution.builder()
            .orderId(order.getOrderId())
            .ticker(order.getTicker())
            .side(SideStatus.valueOf(order.getSide()))
            .quantity(order.getQuantity())
            .executedPrice(price)
            .status(status)
            .build();
    repository.save(execution);

    // 2. Notifies the Broker
    OrderResponseEvent response = new OrderResponseEvent(
        order.getOrderId(), status.name(), price);
    orderProducer.sendToBroker(response);
}

5. Dead Letter Queue

For messages that fail in the consumer (unexpected processing error), we configured a full DLQ setup:

@Bean
public DirectExchange deadLetterExchange() {
    return new DirectExchange(dlxName);
}

@Bean
public Queue deadLetterQueue() {
    return QueueBuilder.durable(dlqName).build();
}

@Bean
public Binding bindingDlq(Queue deadLetterQueue, DirectExchange deadLetterExchange) {
    return BindingBuilder.bind(deadLetterQueue)
            .to(deadLetterExchange)
            .with(dlqName);
}

In the consumer, we rethrow the exception so RabbitMQ knows the message failed and routes it to the DLQ:

@RabbitListener(queues = "${app.rabbitmq.queue-in}")
public void receiveOrder(OrderEventDTO event) {
    log.info("New order received: ID {} | Ticker {} | Side {}",
            event.getOrderId(), event.getTicker(), event.getSide());
    try {
        matchingService.process(event);
    } catch (Exception e) {
        log.error("Failed to process order {}: {}", event.getOrderId(), e.getMessage(), e);
        throw e; // RabbitMQ routes to DLQ
    }
}

6. REST API + Swagger

Since the service exposes query endpoints, I configured Swagger UI from the start:

@Bean
public OpenAPI customOpenAPI() {
    return new OpenAPI()
            .info(new Info()
                    .title("B3 Matching Engine API")
                    .version("1.0.0")
                    .description("Simulates the B3 stock exchange matching engine..."));
}

Available endpoints:

Method	Endpoint	Description
GET	`/api/v1/executions`	List all executions
GET	`/api/v1/executions/order/{orderId}`	Find by order ID
GET	`/api/v1/executions/ticker/{ticker}`	Find by ticker
GET	`/api/v1/executions/status/{status}`	Find by status

✅ Validating the Execution

With the application running locally, all components started correctly:

✅ Flyway applied the order_executions table migration
✅ Hibernate validated the schema
✅ RabbitMQ connected with queues and DLQ declared
✅ Tomcat running on port 8091
✅ Swagger UI accessible at http://localhost:8091/swagger-ui.html

What's Next?

With b3-market-sync-api feeding Redis and b3-matching-engine-api ready to process orders, the entire B3 side is operational.

The next step is building the broker-order-api — the orchestrator on the broker side that will manage the complete order lifecycle:

Receive the buy/sell intent from the user
Validate the ticker via REST against broker-asset-api
Save the order as PENDING
Publish the event to Kafka
Send the order to the Matching Engine via RabbitMQ
Consume the feedback and update the final status

Once that service is ready, we'll have the first complete end-to-end flow running in the ecosystem.

Got any questions about the matching logic or RabbitMQ DLQ configuration? Drop them in the comments!

About the Series

⬅️ Previous Post: Syncing the Real Market: Consuming Brapi and Feeding Redis with Spring Boot

Series Index: Series Roadmap

Links:

Syncing the Real Market: Consuming Brapi and Feeding Redis with Spring Boot

Sun, 10 May 2026 11:03:34 +0000

Hello everyone!

Continuing the My Broker B3 series, today we'll talk about an essential component on the B3 side of our simulator: the B3 Market Sync API.

Before building the engine that decides whether an order gets executed or rejected, we need to ensure it has access to real market prices. That's exactly what b3-market-sync-api does: fetches real asset prices from brapi.dev and stores them in Redis, ready for real-time consumption.

️ What is the Market Sync?

This microservice has a single, well-defined responsibility: to be the market data producer of the ecosystem. It operates completely asynchronously and independently — no other service needs to call it directly.

The flow is simple and elegant:

[brapi.dev] ◀── Feign Client ── [MarketSyncScheduler]
                                         │
                              market:price:{TICKER}
                                         │
                                      [Redis]
                                         │
                              [B3 Matching Engine] (next post)

MVP Focus

The goal here is clear: have real prices available in Redis with low latency. The Matching Engine we'll build in the next post won't query a database or make HTTP calls to get prices — it goes straight to Redis. This ensures the matching decision happens in microseconds.

In this phase, I prioritized:

Scheduled sync with market hours guard
Redis cache with TTL to prevent stale data
External API rate limit protection
Critical bug fixes found during code review
REST API for querying cached prices
Swagger documentation

️ Tech Stack

Technology	Usage
Java 21 + Spring Boot 3.5.11	Service core
Spring Cloud OpenFeign	Declarative HTTP client for brapi.dev
Spring Data Redis	High-performance cache
Spring Scheduling	Periodic synchronization
Jackson JSR310	Java 8 Date/Time serialization support
SpringDoc OpenAPI	Swagger UI documentation

️ Implementation Pillars

1. Feign Client — Consuming Brapi

Spring Cloud OpenFeign lets you declare an HTTP client as a simple interface, with no boilerplate code:

@FeignClient(name = "brapiClient", url = "${app.brapi.url}")
public interface BrapiClient {

    @GetMapping("/quote/{ticker}")
    BrapiResponseDTO getQuote(
        @PathVariable String ticker,
        @RequestParam String token
    );
}

The URL and token are injected via application.yaml, keeping the code clean and environment-configurable.

2. Scheduler with Market Hours Guard

The heart of the service is a scheduled job that fires every 30 minutes. But before any API call, it checks whether the market is open:

@Scheduled(fixedRateString = "${app.sync.interval:1800000}")
public void sync() {
    if (!isMarketOpen()) {
        log.info("Sync aborted: market is closed (outside trading hours or weekend).");
        return;
    }
    // ... fetch and store prices
}

private boolean isMarketOpen() {
    ZonedDateTime now = ZonedDateTime.now(ZoneId.of("America/Sao_Paulo"));
    DayOfWeek day = now.getDayOfWeek();
    int hour = now.getHour();

    if (day == DayOfWeek.SATURDAY || day == DayOfWeek.SUNDAY) {
        return false;
    }

    // B3 trading hours: 10:00 to 18:00 (Sao Paulo time)
    return hour >= 10 && hour < 18;
}

Important detail: we use ZonedDateTime with America/Sao_Paulo explicitly. Inside a Docker container, the JVM may default to UTC — which would make the market hours guard behave incorrectly. We also pass -Duser.timezone=America/Sao_Paulo in the Dockerfile ENTRYPOINT to ensure the JVM honors the correct timezone:

ENTRYPOINT ["java", "-Duser.timezone=America/Sao_Paulo", "-jar", "app.jar"]

3. Redis Cache with Correct TTL

The MarketDataService stores each quote in Redis with a standardized key and 5-minute TTL:

private static final Duration CACHE_TTL = Duration.ofMinutes(5);

public void saveToCache(BrapiResultDTO quote) {
    String key = CACHE_KEY_PREFIX + quote.getTicker();
    // TTL of 5 minutes — if sync stops, stale prices expire quickly
    // preventing the Matching Engine from using outdated data
    redisTemplate.opsForValue().set(key, quote, CACHE_TTL);
    log.info("Ticker {} updated in cache: R$ {}", quote.getTicker(), quote.getRegularMarketPrice());
}

The TTL is fundamental: if the service goes down, prices expire in 5 minutes. The Matching Engine then fails to find the price in Redis and rejects orders — correct and predictable behavior, much better than using hours-old prices.

4. Epoch Timestamp Deserialization

A subtle bug I found: brapi.dev returns the regularMarketTime field as a Unix epoch (integer), but Jackson was trying to deserialize it as LocalDateTime (ISO string). This causes silent deserialization failure.

The solution was a custom deserializer:

public class EpochToLocalDateTimeDeserializer extends StdDeserializer<LocalDateTime> {

    private static final ZoneId SAO_PAULO = ZoneId.of("America/Sao_Paulo");

    @Override
    public LocalDateTime deserialize(JsonParser parser, DeserializationContext context)
            throws IOException {
        long epoch = parser.getLongValue();
        return LocalDateTime.ofInstant(Instant.ofEpochSecond(epoch), SAO_PAULO);
    }
}

And annotating it on the DTO:

@JsonDeserialize(using = EpochToLocalDateTimeDeserializer.class)
private LocalDateTime regularMarketTime;

5. Rate Limit Protection

Since we use the brapi.dev free plan, we added a delay between calls to avoid throttling:

for (String ticker : brapiProperties.getTickers()) {
    try {
        BrapiResponseDTO response = brapiClient.getQuote(ticker.trim(), brapiProperties.getToken());
        if (nonNull(response.getResults()) && !response.getResults().isEmpty()) {
            marketDataService.saveToCache(response.getResults().getFirst());
        }
        // Small delay between calls to avoid hitting rate limit on free plan
        Thread.sleep(200);
    } catch (Exception e) {
        log.error("Failed to sync ticker {}: {}", ticker, e.getMessage());
    }
}

The per-ticker try/catch is essential — if one asset fails, the loop continues for the rest.

6. REST API + Swagger

Although the Matching Engine consumes prices directly from Redis, we added REST endpoints to make debugging and observability easier:

Method	Endpoint	Description
GET	`/api/v1/quotes`	List prices for all configured tickers
GET	`/api/v1/quotes/{ticker}`	Get price for a specific ticker

Documented via Swagger UI at http://localhost:8096/swagger-ui.html.

Security — Token Out of Code

A critical issue I fixed: the brapi.dev token was hardcoded as a default value in application.yaml:

# ❌ Before — token exposed in public repository
token: ${BRAPI_TOKEN:mFk9YRLijAtxsP5y1XxxxX}

# ✅ After — no fallback, variable is required
token: ${BRAPI_TOKEN}

Never expose credentials as default values in public repositories. The application now fails on startup if the variable is not provided — correct behavior.

✅ Validating the Execution

With the application running locally:

✅ Tomcat started on port 8096
✅ Application initialized in under 3 seconds
✅ Scheduler fired and logged: Sync aborted: market is closed (outside trading hours or weekend)
✅ Swagger UI accessible at http://localhost:8096/swagger-ui.html

What's Next?

With b3-market-sync-api up and feeding Redis with real prices, we have the foundation the next service needs to work. In the next post we'll build the B3 Matching Engine — the engine that will consume these prices and decide whether the broker's orders are executed or rejected.

Got any questions about the Redis integration or the market hours guard? Drop them in the comments!

About the Series

⬅️ Previous Post: From Stream to Database: Processing Market Data with Spring Boot, Redis and Flyway

➡️ Next Post: The Heart of B3: Building the Matching Engine with RabbitMQ and Redis (coming soon)

Series Index: Series Roadmap

Links:

Improving Maven's dependency:analyze... or not

Mon, 10 Mar 2025 15:55:22 +0000

Recently, my good friend Richard Fichtner advised using the mvn dependency:analyze command to get rid of declared but unused dependencies:

There is another use case for mvn dependency:analyze It can show you the dependencies you use in your code but have not declared in your pom.xml. This works because you have a transitive dependency on your classpath. Either don't use the dependency or declare it.

[image or embed]
— Richard Fichtner ????☕ (
@richard.fichtner.dev
)
December 10, 2024 at 2:00 PM

While it was a great idea years ago, it's dangerous advice today. In this post, I'd like to explain what the plugin does and why you shouldn't use it but in the most straightforward projects.

The `mvn dependency:analyze` command

Maven uses a plugin architecture; in the above command, the plugin is maven-dependency-plugin. A plugin hosts several related goals. Here, it's analyze.

>Analyzes the dependencies of this project and determines which are: used and declared; used and undeclared; unused and declared. This goal is intended to be used standalone, thus it always executes the test-compile phase - use the dependency:analyze-only goal instead when participating in the build lifecycle.
>By default, maven-dependency-analyzer is used to perform the analysis, with limitations due to the fact that it works at bytecode level, but any analyzer can be plugged in through analyzer parameter.
>-- dependency:analyze

maven-dependency-analyzer is a shared Maven component. Its description is quite descriptive:

>Analyzes the dependencies of a project for undeclared or unused artifacts.
>Warning: Because analysis is done on the bytecode rather than the source, some cases are not detected including constants, annotations with source-only retention, and links in Javadoc. This can lead to incorrect results when these are the only uses of a dependency.
>The main component is ProjectDependencyAnalyzer, which uses ClassAnalyzer and DependencyAnalyzer.
>-- maven-dependency-analyzer

The warning clearly shows that it works at the bytecode level. In particular, it explicitly mentions that it doesn't consider source-level annotations.

Spring Boot starters

I described how to design your own Spring Boot starter a long time ago, and it didn't change a lot since then. If you're new to Spring Boot starters, here's a summary.

SpringBoot relies on AutoConfiguration classes. AutoConfiguration classes are regular configuration classes, i.e., they contribute to the application classes. You can set specific activation criteria, such as the presence of a Spring property, but these are not specific to auto-configuration.

Here's a very simplified flow:

The JAR that automatically comes with Spring Boot is org.springframework.boot:spring-boot-autoconfigure. You can check the content of its META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports:

...
org.springframework.boot.autoconfigure.web.client.RestClientAutoConfiguration
org.springframework.boot.autoconfigure.web.client.RestTemplateAutoConfiguration
org.springframework.boot.autoconfigure.web.embedded.EmbeddedWebServerFactoryCustomizerAutoConfiguration
org.springframework.boot.autoconfigure.web.reactive.HttpHandlerAutoConfiguration
org.springframework.boot.autoconfigure.web.reactive.ReactiveMultipartAutoConfiguration
org.springframework.boot.autoconfigure.web.reactive.ReactiveWebServerFactoryAutoConfiguration
org.springframework.boot.autoconfigure.web.reactive.WebFluxAutoConfiguration
org.springframework.boot.autoconfigure.web.reactive.WebSessionIdResolverAutoConfiguration
org.springframework.boot.autoconfigure.web.reactive.error.ErrorWebFluxAutoConfiguration
org.springframework.boot.autoconfigure.web.reactive.function.client.ClientHttpConnectorAutoConfiguration
org.springframework.boot.autoconfigure.web.reactive.function.client.WebClientAutoConfiguration
org.springframework.boot.autoconfigure.web.servlet.DispatcherServletAutoConfiguration
org.springframework.boot.autoconfigure.web.servlet.ServletWebServerFactoryAutoConfiguration
org.springframework.boot.autoconfigure.web.servlet.error.ErrorMvcAutoConfiguration
org.springframework.boot.autoconfigure.web.servlet.HttpEncodingAutoConfiguration
org.springframework.boot.autoconfigure.web.servlet.MultipartAutoConfiguration
org.springframework.boot.autoconfigure.web.servlet.WebMvcAutoConfiguration
org.springframework.boot.autoconfigure.websocket.reactive.WebSocketReactiveAutoConfiguration
org.springframework.boot.autoconfigure.websocket.servlet.WebSocketServletAutoConfiguration
org.springframework.boot.autoconfigure.websocket.servlet.WebSocketMessagingAutoConfiguration
org.springframework.boot.autoconfigure.webservices.WebServicesAutoConfiguration
org.springframework.boot.autoconfigure.webservices.client.WebServiceTemplateAutoConfiguration

As an example, here's the RestClientAutoConfiguration:

@AutoConfiguration(after = { HttpClientAutoConfiguration.class, HttpMessageConvertersAutoConfiguration.class }) //1
@ConditionalOnClass(RestTemplate.class)                //2
@Conditional(NotReactiveWebApplicationCondition.class) //3
public class RestTemplateAutoConfiguration {

    // Class body
}

Set the order of auto-configuration classes
Activate if the RestTemplate class is on the classpath
Activate if we aren't in a reactive web app context

Note that the class loader loads the RestTemplateAutoConfiguration class just fine, regardless of whether the RestTemplate class is on the classpath or not! Spring leverages this mechanism to its fullest, as seen above. In effect, the resolution of classes configured in annotations is deferred until they are explicitly accessed.

Bringing the `maven-dependency-analyzer` into the modern age

Committers designed the analyzer in 2007: here's how it looked like then. Spring Boot started later, in 2010. For this reason, the analyzer didn't take deferred class loading in annotations. Note that this is still not the case; the project doesn't get a lot of love.

When using the plugin on a Spring Boot project, you'll get a lot of false positives. I tried it with a simple Spring Boot project, using WebFlux and R2DBC on PostgreSQL.

Here's a slight excerpt of the output when I run mvn analyze:dependencies:

[WARNING] Unused declared dependencies found:
[WARNING]   org.springframework.boot:spring-boot-starter-data-r2dbc:jar:3.4.0:compile
[WARNING]   org.testcontainers:postgresql:jar:1.20.4:test
[WARNING]   org.testcontainers:r2dbc:jar:1.20.4:test

If I remove any of these dependencies, tests don't run.

What would be necessary to make the analyzer work with Spring Boot projects?
Let's analyze the analyzer.

The plugin allows configuring another analyzer:

>
>Specify the project dependency analyzer to use (plexus component role-hint). By default, maven-dependency-analyzer is used. To use this, you must declare a dependency for this plugin that contains the code for the analyzer. The analyzer must have a declared Plexus role name, and you specify the role name here.
> Type: java.lang.String
> Since: 2.2
> Required: No
> User Property: analyzer
>* Default: default
>-- dependency:analyze

We can create an overall analyzer that reuses the above but adds one specific to Spring Boot.

Conclusion

The current state of the Maven analyzer doesn't offer any benefit to modern Spring Boot projects. The existing code is open to configuration and even extension. However, we would need to embed a lot of Spring Boot logic. For Quarkus and Micronaut projects, we would require dedicated code as well.

I don't know if it's worth the time and effort. If you think it is, I hope this blog post can serve as an early-stage analysis.

To go further:

Originally published at A Java Geek on March 9^th, 2025

Spring Data Neo4j: How to update an entity

Thu, 27 Feb 2025 20:28:06 +0000

After working on a new online Spring Data Neo4j course, I learned a couple more things about updating an entity. The course required a different set of scenarios than outlined in my previous SDN update blog post, so I wanted to cover those scenarios, as well.

Spring save() method

First up is the out-of-the-box save() method that is provided by Spring as a default. This method takes an input of the entity object you want to save to the database.

Here is an example of what this looks like with a popular movie data set as the model.

Movie domain class:

@Node
public class Movie {
     @Id
     private String movieId;
    
     private String title;
     private String plot;
     private String poster;
     private String url;
     private String released;
     private Long imdbVotes;
    
     @Relationship(value = "ACTED_IN", direction = Relationship.Direction.INCOMING)
     private List<Role> actors;
}

Movie controller class:

@RestController
@RequestMapping("/movies")
public class MovieController {
    //inject repository + constructor

    @PostMapping("/save")
    Movie save(@RequestBody Movie movie) {
        return movieRepo.save(movie);
    }
}

This works well to save a new movie, as you can provide a subset of properties or all properties, as long as the id is present, and anything you don't provide will be set to null. However, the issue arises when you need to update an existing entity because it means any attributes you do not provide will be overwritten to null.

To better understand how this works, let's see it in action by saving a movie, and then trying to update it.

Movie request object:

{
  "movieId": "9876",
  "title": "MyMovie"
}

Save Movie object:

% http ":8080/movies/save" @src/main/resources/movie.json
{
    "actors": null,
    "imdbId": null,
    "imdbVotes": null,
    "movieId": "9876",
    "plot": null,
    "poster": null,
    "title": "MyMovie",
    "url": null,
    "year": null
}

Now let's use the same method to try to update the movie with a year property.

MovieUpdated object:

{
  "movieId": "9876",
  "year": 2018
}

Save updated Movie object:

% http ":8080/movies/save" @src/main/resources/movieUpdated.json
{
    "actors": null,
    "imdbId": null,
    "imdbVotes": null,
    "movieId": "9876",
    "plot": null,
    "poster": null,
    "title": null,
    "url": null,
    "year": 2018
}

In the output above, you can see that the title property is null, and the year property is populated. This is because the title is not specified in the updated JSON object, so it is overwritten to null.

This may not be too big of an effort if you have only a few attributes in your domain class, although I would still find it frustrating to include all properties for only updating one or two properties. In that case, I would need to resort to the POJO method outlined in my previous SDN update blog post where you pull the database entity, set each property, and then save the entity. The added business logic seems like an unnecessary maintenance headache.

What if you wanted to preserve what was already there without providing all the properties defined in the domain class to the request? In these scenarios, there are a couple of other options at your disposal, though neither allow dynamic updates to random properties per request.

Patch Year

The first option is that you don't have to set all properties if you use a PATCH method and only set the values you want to update. Here is an example.

Movie controller class:

@RestController
@RequestMapping("/movies")
public class MovieController {
    //inject repository + constructor

    @PatchMapping("/patchYear")
    Movie patchYear(@RequestBody Movie moviePatch) {
        Movie existingMovie = movieRepository.findById(moviePatch.getMovieId()).get();
        existingMovie.setYear(moviePatch.getYear());

        return movieRepository.save(existingMovie);
    }
}

PatchYear object:

{
  "movieId": "9876",
  "year": 2024
}

Patch movie year:

% http PATCH ":8080/movies/patchYear" @src/main/resources/moviePatch.json

{
    "budget": null,
    "countries": null,
    "imdbId": null,
    "imdbRating": null,
    "imdbVotes": null,
    "languages": null,
    "movieId": "9876",
    "plot": null,
    "poster": null,
    "released": null,
    "revenue": null,
    "runtime": null,
    "title": "MyMovie",
    "tmdbId": null,
    "url": null,
    "year": 2024
}

This allows you to set specific values without overwriting other property values to null. You also don't need to set all the values in the movie object programmatically. If you modified the initial save() method to just include the setYear() line, it would still overwrite other values. This approach prevents that, although you still have to call setProperty() for each field you want to update.

Note: For this approach to work, your domain entity must be a class (not a record) because records are immutable, which means you cannot change (or set/update) fields on the entity instance. For immutable objects, you have to create a new instance of the object and copy property values to the new object before saving.

You can avoid setting each property on an object and retain existing values with a couple of options covered next.

Custom Cypher

One of the more flexible options is to use custom Cypher. For this, you would write a Cypher statement that sets the new values to the properties you want to update. You can even add/set properties that do not exist on the application's domain class. The negative is that you would need to make changes to the application (Cypher statement) if you wanted to update different properties, so it is not fully dynamic.

The example below uses the same movie domain but adds a Cypher statement and method to the repository interface to update the year property without overwriting the title.

Repository interface:

interface MovieRepository extends Neo4jRepository<Movie, String> {
    @Query("MATCH (m:Movie {movieId: $movieId}) " +
            "SET m.year = toInteger($year) " +
            "RETURN m;")
    Movie updateYear(String movieId, Long year);
}

Movie controller class:

@RestController
@RequestMapping("/movies")
public class MovieController {
    //inject repository + constructor

    @PatchMapping("/updateYear")
    Movie patchYear(@RequestParam String movieId, @RequestParam Long year) {
        return movieRepository.updateYear(movieId, year);
    }
}

Then, the following request calls the method and updates the movie's year property.

Update movie year:

% http PATCH ":8080/movies/updateYear?movieId=9876&year=2018"

{
    "actors": [],
    "imdbId": null,
    "imdbVotes": null,
    "movieId": "9876",
    "plot": null,
    "poster": null,
    "title": "MyMovie",
    "url": null,
    "year": 2018
}

It worked! The movie's title remained the same (not overwritten to null), and a value was saved for the year property.

This ad hoc Cypher approach could work well when values or property updates occur somewhat frequently, as updating the Cypher statement makes updates flexible. You could also make the incoming property generic (value) and pass in any value (or multiple values) and set whichever properties you'd like by changing the Cypher. While still not completely dynamic, this option is probably the most flexible and dynamic of the list.

A custom Cypher approach might work well when you need to update certain properties, but if you have a subset of properties that operate together, another option is to create a projection of the domain class.

Projections

To provide a consistent set of values for update and leave other properties as-is, projections are probably the nicest option I've found so far. This approach still requires setting consistent properties (like with custom Cypher), but avoids overwriting consistent values by creating a "view" of the larger entity, only working with those values and leaving other field values alone.

Note: There are two types of projections - interface and DTO. Interface projections are immutable, which means you cannot update values, but have to create a new object and copy existing values over. DTO objects, then, are more straightforward when dealing with update operations. For this reason, the examples use DTO-based projections.

There are two different ways to save a projection - 1. send the projection (subset of properties) and save into the full domain entity, 2. send a full domain object but only save the projection fields. Really, the difference is the incoming request object, whether you have a smaller set or larger set and only want to save those values.

Let's see how this operates.

Projection as Movie

The first example sends a projection object (subset of the full domain object's properties) and saves the trimmed object as the full movie entity. We have defined a projection that only includes the movieId and plot properties of a movie.

MovieDTOProjection class:

public class MovieDTOProjection {
    private String movieId;
    private String plot;

    public String getMovieId() { return movieId; }

    public String getPlot() {
        return plot;
    }

    public void setPlot(String plot) {
        this.plot = plot;
    }
}

MovieController class method:

@RestController
@RequestMapping("/movies")
public class MovieController {
    //inject repository + constructor

    //Only updates properties in projection
    @PatchMapping("/projectionAsMovie")
    MovieDTOProjection saveProjectionAsMovie(@RequestBody MovieDTOProjection movieDTO) {
        return neo4jTemplate.save(Movie.class).one(movieDTO);
    }
}

ProjectionAsMovie object (request object):

{
  "movieId": "9876",
  "plot": "Here is the plot."
}

Update Movie with a projection object:

% http PATCH ":8080/movies/projectionAsMovie" @src/main/resources/projectionAsMovie.json

{
    "movieId": "9876",
    "plot": "Here is the plot."
}

Full database entity:

{
    "plot": "Here is the plot.",
    "year": 2024,
    "movieId": "9876",
    "title": "MyMovie"
}

The request successfully updated the entity with the new plot value ("Here is the plot.") without overwriting the title or year properties on the existing entity! The method in the controller class takes the projection object input and saves it as a Movie class entity.

This approach is helpful when you only want to send certain properties over the wire and not the full object. You can set any fields you wish to update in the projection and only send those values in the request.

Movie entity as projection

This type of projection only saves a defined subset of properties out of a potentially larger or variable object. The save will only update the fields included in the projection and ignore anything else that might be in the request object.

The example below uses the same MovieDTOProjection class as the above example. Then, we only need a new method in the controller to save the projection.

MovieController class method:

@RestController
@RequestMapping("/movies")
public class MovieController {
    //inject repository + constructor

    //Only updates properties in projection (ignores other values)
    @PatchMapping("/movieAsProjection")
    MovieDTOProjection saveMovieAsProjection(@RequestBody Movie movie) {
        return neo4jTemplate.saveAs(movie, MovieDTOProjection.class);
    }
}

MovieAsProjection object:

{
  "movieId": "9876",
  "title": "TestTitle",
  "plot": "Some plot cliche here.",
  "year": 2025
}

Send Movie object (only save projection values):

% http PATCH ":8080/movies/movieAsProjection" @src/main/resources/movieAsProjection.json

{
    "movieId": "9876",
    "plot": "Some plot cliche here."
}

Full database entity:

{
    "plot": "Some plot cliche here.",
    "year": 2024,
    "movieId": "9876",
    "title": "MyMovie"
}

This also worked! The controller method accepts a Movie request object as input and saves it as the projection entity, which only retains the subset of values defined in the projection and ignores the rest.

This approach would be helpful if you have request objects with varying fields of a Movie entity, but only want to update a certain subset each time. In terms of the incoming request object, this option seems to be the most flexible in allowing you to provide all kinds of fields as input, and it will only save the relevant ones defined in the projection.

Wrapping Up!

In this post, we delved a bit deeper into updating entities using Spring Data and Neo4j. A previous blog post on the topic outlined some examples for that use case at the time (microservices), but I learned about a few more options after working on the GraphAcademy Spring Data Neo4j course. These options included custom Cypher statements and projections.

There are still other pieces of the puzzle to explore and integrate, such as optimistic locking (with the @Version field) and custom repository implementations for extending repositories (e.g. to combine Neo4jRepository<>, Neo4jTemplate, and/or Neo4jClient levels of abstraction), but we will save those for a future blog post. Happy coding!

Resources

Code: sdn-update-entity-round2
Blog post: previous SDN update article
Graphacademy course (free, online, self-paced): Spring Data Neo4j
Documentation: SDN projection persistence
Documentation: SDN custom repository implementations

Coder Legion - Recent posts tagged spring

The Heart of B3: Building the Matching Engine with RabbitMQ, Redis and Spring Boot

️ What is the Matching Engine?

MVP Focus

️ Tech Stack

️ Implementation Pillars

1. RabbitMQ Configuration

2. The Matching Logic

3. Failure Handling — No Silent Order Loss

4. Transactional Guarantee

5. Dead Letter Queue

6. REST API + Swagger

✅ Validating the Execution

What's Next?

About the Series

Syncing the Real Market: Consuming Brapi and Feeding Redis with Spring Boot

️ What is the Market Sync?

MVP Focus

️ Tech Stack

️ Implementation Pillars

1. Feign Client — Consuming Brapi

2. Scheduler with Market Hours Guard

3. Redis Cache with Correct TTL

4. Epoch Timestamp Deserialization

5. Rate Limit Protection

6. REST API + Swagger

Security — Token Out of Code

✅ Validating the Execution

What's Next?

About the Series

Improving Maven's dependency:analyze... or not

The mvn dependency:analyze command

Spring Boot starters

Bringing the maven-dependency-analyzer into the modern age

Conclusion

Spring Data Neo4j: How to update an entity

Spring save() method

Patch Year

Custom Cypher

Projections

Projection as Movie

Movie entity as projection

Wrapping Up!

Resources

The `mvn dependency:analyze` command

Bringing the `maven-dependency-analyzer` into the modern age