Skip to content

Migration Guide

Jump to bottom
Rain Ramm edited this page Mar 18, 2026 · 1 revision

Spring Core Library v5.0.0 — Release Notes & Migration Guide

Overview

Version 5.0.0 is a major release that upgrades the library to Spring Boot 4.0.0, Spring Framework 7.0.0, and Jackson 3.0.x. This release contains multiple breaking changes and requires careful migration of consuming applications.

Dependency Upgrades

Dependency v4.x v5.0.0
Spring Boot 3.5.0 4.0.0
Spring Framework 6.2.7 7.0.0
Jackson (primary) 2.21.x (com.fasterxml.jackson) 3.0.2 (tools.jackson)
Jackson (Retrofit compat) — 2.20.1 (com.fasterxml.jackson)
Tomcat 10.1.x 11.0.12
OkHttp 4.12.0 5.3.2
Testcontainers 1.x 2.0.3
Gradle Wrapper 8.14.1 9.2.1
SonarQube plugin 6.2.0 7.2.2

Breaking Changes

1. Jackson 3 Migration (package rename)

Spring Boot 4 uses Jackson 3, which moved from the com.fasterxml.jackson package to tools.jackson.

Impact: Any code that directly references Jackson types from the library (e.g., custom exception handlers extending ControllerAdvisor, audit mappers) must update imports.

// Before (v4.x)
import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.DeserializationFeature;

// After (v5.0.0)
import tools.jackson.databind.ObjectMapper;
import tools.jackson.databind.DeserializationFeature;

Note: The library maintains a dual Jackson setup — Jackson 3 for Spring Boot 4 and Jackson 2 for Retrofit (which does not yet support Jackson 3). If your application uses Retrofit through this library, the Jackson 2 ObjectMapper is automatically configured alongside the Jackson 3 JsonMapper.

Important: Spring Boot 4 no longer manages Jackson 2 on the compile classpath. If your application needs Jackson 2's JavaTimeModule (e.g., for a custom Jackson 2 ObjectMapper bean), you must add jackson-datatype-jsr310 explicitly:

implementation 'com.fasterxml.jackson.datatype:jackson-datatype-jsr310'

2. InvalidFormatValidationException Now Extends RuntimeException

Previously extended Jackson's InvalidFormatException (a checked exception). Now extends RuntimeException and wraps the original exception.

// Before (v4.x)
catch (InvalidFormatValidationException e) {
    // was a checked exception (InvalidFormatException → JsonProcessingException → IOException)
}

// After (v5.0.0)
catch (InvalidFormatValidationException e) {
    // now a RuntimeException — no longer needs to be declared in throws clauses
    e.getCause(); // returns the original InvalidFormatException
}

3. MDCTaskDecorator Removed

The deprecated class ee.bitweb.core.trace.thread.MDCTaskDecorator (deprecated since 3.3.0) has been removed.

Migration: Replace with the appropriate concrete implementation:

// Before (v4.x)
new MDCTaskDecorator(resolver);

// After (v5.0.0) — choose one:
new BasicMDCTaskDecorator(resolver);
new SecurityAwareMDCTaskDecorator(resolver);

4. TrimmedStringDeserializer API Changed

The static method addToObjectMapper(ObjectMapper) has been removed. Replaced by createModule() which returns a SimpleModule.

// Before (v4.x)
TrimmedStringDeserializer.addToObjectMapper(objectMapper);

// After (v5.0.0) — for Jackson 3:
jsonMapperBuilder.addModule(TrimmedStringDeserializer.createModule());

// After (v5.0.0) — for Jackson 2 (Retrofit):
Jackson2TrimmedStringDeserializer.addToObjectMapper(objectMapper);
// or
objectMapper.registerModule(Jackson2TrimmedStringDeserializer.createModule());

5. Deprecated persistenceException Log Level Property Removed

The deprecated property ee.bitweb.core.api.controller-advisor.log-level.persistence-exception has been removed. The entityNotFoundException and conflictException properties now default to ERROR independently.

# Before (v4.x)
ee.bitweb.core.api.controller-advisor.log-level:
  persistence-exception: WARN  # affected both entity-not-found and conflict

# After (v5.0.0) — configure each independently:
ee.bitweb.core.api.controller-advisor.log-level:
  entity-not-found-exception: WARN
  conflict-exception: WARN

6. AMQP Message Converter Changed

The AMQP auto-configuration now uses JacksonJsonMessageConverter (Jackson 3) instead of Jackson2JsonMessageConverter.

// Before (v4.x)
Jackson2JsonMessageConverter converter = new Jackson2JsonMessageConverter(objectMapper);

// After (v5.0.0)
JacksonJsonMessageConverter converter = new JacksonJsonMessageConverter(jsonMapper);

If you override the message converter bean, update to JacksonJsonMessageConverter and pass a JsonMapper instead of ObjectMapper.

7. Spring Security & Actuator Import Path Changes

Spring Boot 4 reorganized several actuator and security packages:

// Before (v4.x)
import org.springframework.boot.actuate.autoconfigure.health.HealthEndpointProperties;
import org.springframework.boot.actuate.autoconfigure.security.servlet.EndpointRequest;

// After (v5.0.0)
import org.springframework.boot.health.autoconfigure.actuate.endpoint.HealthEndpointProperties;
import org.springframework.boot.security.autoconfigure.actuate.web.servlet.EndpointRequest;

8. Spring Boot 4 Test Import Changes

MockMvc auto-configuration moved to a new package:

// Before (v4.x)
import org.springframework.boot.test.autoconfigure.web.servlet.AutoConfigureMockMvc;

// After (v5.0.0)
import org.springframework.boot.webmvc.test.autoconfigure.AutoConfigureMockMvc;

9. ObjectMapper Auto-Configuration Refactored

The ObjectMapperAutoConfiguration class was significantly refactored:

  • Jackson 3 (JsonMapper): Configured via a JsonMapperBuilderCustomizer bean (coreLibJsonMapperCustomizer).
  • Jackson 2 (ObjectMapper): Configured via a nested Jackson2ObjectMapperCustomizer inner class, only active when an ObjectMapper bean exists.

If your application had custom logic that depended on the old @PostConstruct init() method or the injection pattern, update accordingly.

10. RabbitAdmin getMessageCount() Return Type

Spring AMQP changed the return type from Integer to Long. This affects code that calls RabbitAdmin.getQueueProperties() for message count.

New Features

Dual Jackson Support

The library transparently configures both Jackson 2 (for Retrofit compatibility) and Jackson 3 (for Spring Boot 4). Both are configured identically with:

  • Trimmed string deserialization
  • ADJUST_DATES_TO_CONTEXT_TIME_ZONE disabled
  • ACCEPT_FLOAT_AS_INT disabled

Jackson2TrimmedStringDeserializer

New class for Jackson 2 compatibility. Provides the same string-trimming behavior as TrimmedStringDeserializer but for the com.fasterxml.jackson package.

StringUtil.trim()

New utility method ee.bitweb.core.util.StringUtil.trim(String) — safely trims strings, returning null for null input.

Java Module Name

The JAR manifest now includes Automatic-Module-Name: ee.bitweb.core for JPMS compatibility.

Removals

Removed Replacement
MDCTaskDecorator BasicMDCTaskDecorator or SecurityAwareMDCTaskDecorator
TrimmedStringDeserializer.addToObjectMapper() TrimmedStringDeserializer.createModule()
persistenceException log-level property entityNotFoundException + conflictException
OWASP dependency-check Gradle plugin (removed from build)
Spring version matrix CI workflow (removed — fixed to Spring Boot 4.0.0)
.github/spring-versions.json (removed)
.github/scripts/update-spring-versions.py (removed)

Clone this wiki locally