Strategy for Spring Boot 4.x support: Jackson 3.x migration (lessons from PR #912 dry-run)

# Spring Boot 4. x Support Strategy: Jackson 3. x Migration

## Context
Stove currently supports Spring Boot 2.x and 3.x in parallel. Spring Boot 4. x requires Jackson 3.x, which introduces breaking changes that need careful consideration for our multi-version support strategy. 

**Dry-run Reference:** PR [#912](https://github.com/Trendyol/stove/pull/912) serves as a practical dry-run where dependency bumps to Spring Boot 4.x and Jackson 3. x were applied, revealing concrete breaking changes and migration requirements.

## Ecosystem Dependency Audit & Migration Checklist

**This section covering ktor-jackson serialization, Elasticsearch Jackson integration, and all major references to Jackson across Stove modules that must be addressed for the Spring Boot 4.x/Jackson 3. x migration.**

### Ktor-Jackson Serialization
- **Current dependency:** `ktor-serialization-jackson` uses Jackson 2.x (see `gradle/libs.versions.toml` line 104)
- **Issue:** Ktor's official Jackson serialization is not yet compatible with Jackson 3.x (`tools.jackson`). This affects all Stove Ktor-based modules and recipes.
- **Actions:**
  - Track Ktor upstream for Jackson 3.x support ([Ktor issue tracker](https://youtrack.jetbrains.com/issues/KTOR))
  - Consider migration alternatives (e.g., kotlinx.serialization) for Stove Ktor modules if no Jackson 3.x support is released in time for Spring Boot 4.x upgrade.

### Elasticsearch JacksonJsonpMapper
- **Current Integration:** `lib/stove-testing-e2e-elasticsearch` uses `JacksonJsonpMapper` with Jackson 2.x for JSON serialization. 
- **Affected code:**
  - ElasticsearchSystemOptions uses `JacksonJsonpMapper(StoveSerde.jackson.default)`
  - Documentation and migration guides recommend using a custom Jackson `ObjectMapper`
- **Actions:**
  - Verify that `co.elastic.clients:elasticsearch-java` supports Jackson 3.x in the latest release ([Elastic Java client changelog](https://github.com/elastic/elasticsearch-java/releases))
  - Update all `JacksonJsonpMapper` usages to `tools.jackson` when supported
  - Test custom JSON mapper migration with Jackson 3.x

### Other Major Jackson Dependencies & Impacted Modules
- **Core Stove Serialization:**
  - Centralized configuration for all integrations (`lib/stove-testing-e2e/serialization/jackson.kt`). Must migrate to new package, builder usage, and remove deprecated features per Jackson 3. x guide.
- **MongoDB Integration:**
  - Custom Jackson ObjectId serializers/deserializers.  Requires migration and validation for annotation compatibility.
  - Check for impact in all recipes using MongoDB and Jackson serialization.
- **Couchbase Ser/de**
  - ClusterSerialization depends on Jackson 2
- **Spring Boot & Example Recipes:**
  - All modules using custom `JacksonConfiguration` or Spring Boot Jackson autoconfiguration beans (`spring-boot-couchbase-recipe`, `spring-standalone-example`, `micronaut-example`) must upgrade imports & refactor per Jackson 3.x. 

### Migration Checklist Addendum

#### Ktor Jackson Serialization Migration
- [ ] Track upstream Ktor support for Jackson 3.x (critical path for Ktor-based modules)
- [ ] Explore migration to kotlinx.serialization for Ktor if blocked
- [ ] Document migration options in test and recipe modules

#### Elasticsearch Client Jackson Migration
- [ ] Verify Elastic Java client support for Jackson 3.x
- [ ] Update all `JacksonJsonpMapper` usages and custom JSON mappers
- [ ] E2E/regression test Elasticsearch integration after Jackson 3.x upgrade

#### MongoDB and Custom SerDe Migration
- [ ] Migrate custom serializers/deserializers and annotation usages
- [ ] Validate with all supported MongoDB configurations

#### Audit All Downstream Recipes/Examples
- [ ] Identify remaining references to `com.fasterxml.jackson` in all Ktor, Spring, and Micronaut modules
- [ ] Add migration tasks for recipe modules: code, tests, and documentation

### Blockers
- **Ktor-Jackson:** Lack of Jackson 3. x support halts migration for Ktor modules—requires tracking or alternative serialization.
- **Elasticsearch:** Official client must support Jackson 3.x—verify and coordinate upgrade plans.

### Next Steps
- Continue migration impact analysis beyond the first 10 file result limit (see [GitHub code search: `com. fasterxml.jackson`](https://github.com/Trendyol/stove/search?q=com.fasterxml. jackson)).
- Where dependencies are not yet compatible, document blockers and alternatives in Stove migration docs. 


## Migration Guides
- Jackson 2.x → 3.x migration guide: [@FasterXML/jackson/files/jackson3/MIGRATING_TO_JACKSON_3.md](https://github.com/FasterXML/jackson/blob/master/jackson3/MIGRATING_TO_JACKSON_3.md)
- Spring Boot 4. 0 migration guide: [Spring Boot 4. 0 Migration Guide](https://github.com/spring-projects/spring-boot/wiki/Spring-Boot-4.0-Migration-Guide)

## Key Breaking Changes Identified in PR #912

The dry-run in [PR #912](https://github. com/Trendyol/stove/pull/912) revealed the following compilation and runtime issues:

### 1. **Jackson Package Migration** (`com.fasterxml.jackson` → `tools.jackson`)
**Affected files:**
- `recipes/java-recipes/spring-boot-couchbase-recipe/src/main/java/com/trendyol/stove/examples/java/spring/infra/boilerplate/serialization/JacksonConfiguration.java`
- Multiple configuration classes using `ObjectMapper`

**Errors encountered:**
```
error: package com.fasterxml.jackson.databind does not exist
import com.fasterxml.jackson. databind.ObjectMapper;
                                   ^
error: package com. fasterxml.jackson.databind.json does not exist
import com.fasterxml.jackson. databind. json.JsonMapper;
                                        ^
```

**Required changes:**
- Update all imports from `com.fasterxml.jackson.*` to `tools. jackson.*`
- Exception: `com.fasterxml.jackson.annotation` remains unchanged
- Update Maven/Gradle groupIds accordingly

### 2. **Spring Boot Autoconfigure Changes**
**Error encountered:**
```
error: package org.springframework. boot.autoconfigure. jackson does not exist
import org.springframework.boot.autoconfigure. jackson. Jackson2ObjectMapperBuilderCustomizer;
```

**Affected components:**
- `JacksonConfiguration` beans
- Custom Jackson configuration classes

### 3. **Immutable ObjectMapper/JsonFactory**
Jackson 3.x makes `ObjectMapper` and `JsonFactory` fully immutable, requiring builder pattern usage. 

**Migration required:**
```java
// Old (Jackson 2.x)
ObjectMapper mapper = new ObjectMapper();
mapper.configure(DeserializationFeature. FAIL_ON_UNKNOWN_PROPERTIES, false);

// New (Jackson 3. x)
JsonMapper mapper = JsonMapper.builder()
    . disable(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES)
    .build();
```

### 4. **Affected Modules in PR #912**
- `java-recipes/spring-boot-couchbase-recipe` (JacksonConfiguration, CategoryHttpApiConfiguration, KafkaBeanConfiguration, CouchbaseBeanConfiguration)
- Other recipe modules with Spring Boot integration

## Strategic Considerations

### Option 1: Separate Module/Artifact Strategy
- Create separate artifacts for Spring Boot 2.x/3.x (Jackson 2.x) and Spring Boot 4.x (Jackson 3.x)
- **Pros**: Clean separation, no compatibility issues
- **Cons**: Increased maintenance burden, code duplication
- **Aligned with**: Current pattern in `gradle/libs.versions.toml` (`spring-boot` vs `spring-boot-three`)

### Option 2: Conditional Dependency Strategy
- Use Gradle version catalogs to manage different Jackson versions
- Extend existing pattern to `spring-boot-four-*` dependencies
- **Pros**: Maintains single codebase
- **Cons**: Complex dependency management, potential runtime issues

### Option 3: Phased Migration with Version Bump
- Drop Spring Boot 2. x support, migrate to Jackson 3.x
- Support only Spring Boot 3.x (with Jackson 2.x) → Spring Boot 4.x (Jackson 3.x)
- **Pros**: Cleaner migration path, reduced complexity
- **Cons**: Breaking change for Spring Boot 2.x users

### Option 4: Dedicated Testing/Integration Module ⭐ **RECOMMENDED**
- Introduce a new module: **`stove-spring-4x-testing-e2e`**
- This module would:
  - Serve as an isolated sandbox for E2E and integration tests with Spring Boot 4.x + Jackson 3.x
  - Allow iteration and validation of migration approaches without disrupting existing modules
  - Provide concrete examples and recipes for users migrating to Spring Boot 4.x
  - Enable CI/CD validation of Spring Boot 4.x compatibility
  - Catch migration, dependency, and behavioral issues early
- **Pros**: Non-intrusive, reduces risk to core library, provides clear migration reference, enables parallel development
- **Cons**: Additional module to maintain
- **Alignment**: Follows existing pattern of separate recipe modules and version-specific testing

## Key Migration Tasks

### 1. Impact Analysis
- [ ] Audit current Jackson usage across all Stove modules (reference PR #912 findings)
- [ ] Identify which modules are Spring Boot version-dependent
- [ ] Analyze dependency tree for Jackson version conflicts
- [ ] Review current `spring-boot` vs `spring-boot-three` separation in `gradle/libs.versions.toml`

### 2. Module Structure & Dependency Management
- [ ] **Create `stove-spring-4x-testing-e2e` module**
  - Set up module structure following existing patterns
  - Configure with Spring Boot 4.x and Jackson 3.x dependencies
  - Add comprehensive E2E test coverage
  - Include migration examples and recipes
- [ ] Design version catalog structure for Jackson 2.x and 3.x coexistence
- [ ] Update `gradle/libs.versions.toml` with Jackson 3.x dependencies (new groupId: `tools.jackson`)
- [ ] Add Spring Boot 4.x dependencies following existing pattern (`spring-boot-four-*`)
- [ ] Ensure proper isolation between Spring Boot 2.x/3.x and 4.x modules

### 3. Code Migration (Jackson 3.x Breaking Changes)
Based on PR #912 findings and Jackson migration guide:

- [ ] **Update Java package imports**
  - Replace `com. fasterxml.jackson.*` → `tools.jackson.*` (except annotations)
  - Update `ObjectMapper`, `JsonMapper`, `DeserializationFeature`, etc.
- [ ] **Refactor for immutable `ObjectMapper`/`JsonFactory`**
  - Convert direct configuration to builder pattern
  - Update all `JacksonConfiguration` classes
- [ ] **Update Spring Boot autoconfigure usage**
  - Migrate `Jackson2ObjectMapperBuilderCustomizer` usage
  - Review Spring Boot 4.x autoconfiguration changes
- [ ] **Update to format-aligned mappers** (`JsonMapper`, `YAMLMapper`, etc.)
- [ ] **Update exception handling** (unchecked exceptions in Jackson 3.x)
- [ ] **Remove Java 8 module dependencies** (now built-in to jackson-databind)
- [ ] **Update streaming API features**
  - `JsonParser. Feature` → `StreamReadFeature`/`JsonReadFeature`
  - `JsonGenerator.Feature` → `StreamWriteFeature`/`JsonWriteFeature`
- [ ] **Address renamed classes/methods/fields** per JSTEP-6

### 4. Testing Strategy
- [ ] Implement comprehensive test suite in `stove-spring-4x-testing-e2e` module
- [ ] Test Jackson serialization/deserialization across all supported integrations
- [ ] Validate behavior changes from new Jackson 3.x defaults:
  - `FAIL_ON_TRAILING_TOKENS` (now enabled)
  - `FAIL_ON_UNKNOWN_PROPERTIES` (now disabled)
  - Date/time handling changes
  - Enum handling changes
- [ ] Performance testing for buffer recycling settings
- [ ] Run full test suite against PR #912 branch to identify remaining issues
- [ ] Create compatibility matrix tests for Spring Boot 2.x/3.x/4.x

### 5. Documentation
- [ ] Document multi-version support strategy decision
- [ ] Update user documentation with Spring Boot 4.x compatibility notes
- [ ] Provide migration guide for users upgrading to Spring Boot 4.x-compatible version
- [ ] Document breaking changes in Stove API (reference PR #912 changes)
- [ ] Create troubleshooting guide based on PR #912 lessons learned
- [ ] Add README for `stove-spring-4x-testing-e2e` module with migration examples

### 6. Release Planning
- [ ] Decide on versioning strategy (major/minor bump)
- [ ] Plan deprecation timeline for older Spring Boot versions (if applicable)
- [ ] Communicate changes to users/maintainers
- [ ] Consider using PR #912 and `stove-spring-4x-testing-e2e` as foundation for production migration

## Decision Required
**Which strategy should we adopt for Spring Boot 4.x support? ** 

Based on the analysis, **Option 4 (Dedicated Testing Module)** is recommended as it:
- Minimizes risk to existing functionality
- Provides a clear migration path and reference implementation
- Enables parallel development and validation
- Aligns with existing Stove architecture patterns

## References

### PR #912 Dry-Run
- [PR #912: fix(deps): update spring to v4 (major)](https://github.com/Trendyol/stove/pull/912)
- Commits by @osoykan demonstrating Jackson 3.x migration changes
- Build logs showing compilation errors and required fixes

### Migration Resources
- [Jackson 3 Migration Guide Official](https://github.com/FasterXML/jackson/blob/master/jackson3/MIGRATING_TO_JACKSON_3.md)
- [Spring Boot 4.0 migration guide](https://github.com/spring-projects/spring-boot/wiki/Spring-Boot-4.0-Migration-Guide)
- [Spring Boot 4.x Jackson 3 support blog](https://spring.io/blog/2025/10/07/introducing-jackson-3-support-in-spring)
- [JSTEPs (Jackson Strategic Enhancement Proposals)](https://github.com/FasterXML/jackson-future-ideas/wiki)
- [OpenRewrite upgrade recipe](https://docs.openrewrite.org/recipes/java/jackson/upgradejackson_2_3)
- [Current dependency structure](https://github.com/Trendyol/stove/blob/0fec847edaac0b52355c42c5dd64a6fa49a4ff09/gradle/libs.versions.toml)

Strategy for Spring Boot 4.x support: Jackson 3.x migration (lessons from PR #912 dry-run) #931

Description

Spring Boot 4. x Support Strategy: Jackson 3. x Migration

Context

Ecosystem Dependency Audit & Migration Checklist

Ktor-Jackson Serialization

Elasticsearch JacksonJsonpMapper

Other Major Jackson Dependencies & Impacted Modules

Migration Checklist Addendum

Ktor Jackson Serialization Migration

Elasticsearch Client Jackson Migration

MongoDB and Custom SerDe Migration

Audit All Downstream Recipes/Examples

Blockers

Next Steps

Migration Guides

Key Breaking Changes Identified in PR #912

1. Jackson Package Migration (com.fasterxml.jackson → tools.jackson)

2. Spring Boot Autoconfigure Changes

3. Immutable ObjectMapper/JsonFactory

4. Affected Modules in PR #912

Strategic Considerations

Option 1: Separate Module/Artifact Strategy

Option 2: Conditional Dependency Strategy

Option 3: Phased Migration with Version Bump

Option 4: Dedicated Testing/Integration Module ⭐ RECOMMENDED

Key Migration Tasks

1. Impact Analysis

2. Module Structure & Dependency Management

3. Code Migration (Jackson 3.x Breaking Changes)

4. Testing Strategy

5. Documentation

6. Release Planning

Decision Required

References

PR #912 Dry-Run

Migration Resources

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

1. Jackson Package Migration (`com.fasterxml.jackson` → `tools.jackson`)