Migrating OrqueIO to Spring Boot 4: OrqueIO 2.x

Why Upgrade to OrqueIO 2.0.0?

Spring Boot 4 represents the most significant architectural change to the framework in years. The modularization effort makes the framework more maintainable, reduces startup time, and improves native compilation support with GraalVM.

For OrqueIO, staying current with Spring Boot ensures compatibility with the broader ecosystem and allows us to leverage these improvements directly. Users benefit from smaller deployment artifacts, better performance, and alignment with Jakarta EE 11.

There’s also a practical consideration: Spring Boot 3.x is entering maintenance mode. New features, optimizations, and community focus will center on the 4.x line. Organizations planning long-term projects should factor this into their technology decisions.

Core Requirements & Platform Updates

• Java Baseline: A minimum of Java 17 is required, with Java 21/25 recommended for optimal performance and access to the latest features like Virtual Threads.
• Spring Framework 7: Spring Boot 4 is built on top of Spring Framework 7, aligning the entire ecosystem with modern standards.
• Jakarta EE 11: The framework moves to a Jakarta EE 11 baseline, requiring a Servlet 6.1 compatible server and Jakarta Persistence API 3.2.0 baseline. Support for Undertow has been dropped as it is not yet compatible.

The big picture: what Changed in OrqueIO 2.0.0

org.springframework.boot.autoconfigure.* 
    → org.springframework.boot.<module>.autoconfigure.*
org.springframework.boot.actuate.health.* 
    → org.springframework.boot.health.contributor.*
org.springframework.boot.test.* 
    → org.springframework.boot.<module>.test.*

Upgrading OrqueIO from 1.x to 2.0.0

<dependency>
    <groupId>io.orqueio.bpm.springboot</groupId>
    <artifactId>orqueio-bpm-spring-boot-starter</artifactId>
    <version>2.0.0</version>
</dependency>

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-properties-migrator</artifactId>
    <scope>runtime</scope>
</dependency>

How We Upgraded OrqueIO to spring boot 4:

This section documents the internal changes we made to OrqueIO’s codebase. These modifications are already included in OrqueIO 2.0.0 .

Join The Writer's Circle event

For developers maintaining similar Spring Boot integrations or those curious about the technical details, here’s what we encountered.

package org.springframework.boot.actuate.health does not exist

// Before (Spring Boot 3.x)
import org.springframework.boot.actuate.health.AbstractHealthIndicator;
import org.springframework.boot.actuate.health.Health;
import org.springframework.boot.actuate.health.HealthIndicator;
import org.springframework.boot.actuate.health.Status;
// After (Spring Boot 4.x)
import org.springframework.boot.health.contributor.AbstractHealthIndicator;
import org.springframework.boot.health.contributor.Health;
import org.springframework.boot.health.contributor.HealthIndicator;
import org.springframework.boot.health.contributor.Status;

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-health</artifactId>
</dependency>

package org.springframework.boot.autoconfigure.security;

cannot find symbol: variable DEFAULT_FILTER_ORDER

// Spring Boot 3.x
filterRegistration.setOrder(SecurityProperties.DEFAULT_FILTER_ORDER + 1);

// Spring Boot 4.x
private static final int SECURITY_FILTER_ORDER = -100;
filterRegistration.setOrder(SECURITY_FILTER_ORDER + 1);

3. Test Infrastructure Changes

Spring Boot 4 relocates several test-related classes and changes some behaviors.

Import Changes:

TestRestTemplate Configuration:

TestRestTemplate is no longer auto-configured. Add the annotation explicitly:

java

@SpringBootTest
@AutoConfigureTestRestTemplate
public class MyIntegrationTest {
    
    @Autowired
    private TestRestTemplate restTemplate;
}

Required Dependencies:

xml

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-webmvc-test</artifactId>
    <scope>test</scope>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-resttestclient</artifactId>
    <scope>test</scope>
</dependency>

Conclusion

Spring Boot 4 represents a maturation of the framework. The modular architecture may require upfront migration effort, but it results in a cleaner dependency graph and better alignment with modern deployment practices.

For teams evaluating the upgrade, the key question isn’t whether to migrate, but when. Spring Boot 3.x will enter maintenance mode, and the ecosystem , libraries, tools, and community knowledge , will increasingly center on version 4.x.

OrqueIO 2.0.0 is available now for teams ready to adopt Spring Boot 4. For those who need more time, our 1.x line continues to receive updates. Either way, we hope this guide helps you plan your path forward.

Recommendations

• Read the migration guide first — The Spring Boot 4.0 Migration Guide covers most changes.
• Track package relocations — Maintain a reference document of old-to-new import mappings.
• Address test changes early — Test infrastructure has the most numerous changes.