Broadleaf Microservices
  • v1.0.0-latest-prod

Upgrade to 3.0.0

July 27, 2026

Security

Important

July 27, 2026

This release natively integrates security improvements previously addressed via a standalone hotpatch module. Clients upgrading to version 3.0.0 can safely remove the standalone hotpatch module from their project configuration since these concerns are now supported directly in the framework.

For detailed information regarding this security item, please refer to the Broadleaf Security Advisory. You will need your login credentials originally provided for accessing the Broadleaf nexus.

Requirements

  • Java 17 is required since 2.0.0-GA.

General Upgrade Lifecycle

  • Check out your project(s) for upgrade preparation from your source control.

  • Run the OpenRewrite plugin with Broadleaf’s 3.0.0 upgrade recipe on the project(s) source.

  • Review the changes the plugin makes and attempt compilation.

  • Address any compilation failures.

  • Review your project(s) for possible out-of-scope changes not handled by the automation. See the official Spring upgrade guides mentioned in the sections below.

  • Run your automated test suite and QA test your upgrade.

Migration

Broadleaf 3.0.0 OpenRewrite Recipes

Broadleaf Commerce 3.0.0 includes a suite of automated OpenRewrite Recipes to handle the heavy lifting of the Spring Boot 4.1, Spring Security 7.0, and Hibernate 7 upgrades. The aggregate upgrade script includes a subset of relevant OpenRewrite recipes for the Spring Boot 4 upgrade, as well as custom recipes to update an existing Initializr project to Broadleaf 3.0.

These custom recipes include automation for:

  • Request Matchers Migration: Renames and restructures all AntPathRequestMatcher instantiations, static factory helpers (.antMatcher), and method references (::antMatcher or ::new) to use Broadleaf’s secure smartPathPattern(…​) utility.

  • Spring Security DSL Refactoring: Renames legacy MatcherUtil.mvcMatcher calls to MatcherUtil.mvcRequestMatcher for Spring Security 7 compatibility.

  • Automatic Bean Registration: Automatically registers any custom MetadataMessagesBasename classes as Spring @Component beans (only if they are not already manually registered as @Beans in configuration classes).

  • Hibernate 7 Annotation Changes: Migrates legacy @Where(clause = "…​") entity annotations to the modern @SQLRestriction("…​") format.

  • Apache SolrJ 10 Renaming: Automatically renames Jetty HTTP/2 Solr client classes (e.g. Http2SolrClient to HttpJettySolrClient) and injects the solr-solrj-jetty dependency only where required.

  • Defensive SendGrid Package Updates: Safely renames old com.sendgrid.* package paths to com.sendgrid.helpers.mail.objects.*, executing only if the newer SendGrid library is active on your module’s classpath.

  • Cart Payment Activity Renaming: Performs a highly-scoped rename of validatePaymentsForSubscription(…​) to validatePaymentsForFutureSubscriptionBillingCycles(…​) strictly on classes that extend CartPaymentMethodValidationActivity.

The full list of recipes can be found in the composite upgrade recipe, com.broadleafcommerce.Upgrade_3_0_0.

Configuration

To configure these recipes, you’ll need to add the rewrite-maven-plugin configuration to your project’s root pom.xml and register the Broadleaf Upgrade 3.0.0 recipe.

    <plugin>
      <groupId>org.openrewrite.maven</groupId>
      <artifactId>rewrite-maven-plugin</artifactId>
      <version>6.45.0</version>
      <configuration>
        <activeRecipes>
          <recipe>com.broadleafcommerce.Upgrade_3_0_0</recipe>
        </activeRecipes>
      </configuration>
      <dependencies>
        <dependency>
          <groupId>com.broadleafcommerce.microservices</groupId>
          <artifactId>broadleaf-rewrite</artifactId>
          <version>1.0.0-GA</version>
        </dependency>
      </dependencies>
    </plugin>

Also, add a new repositories element & pluginRepositories element, if one does not already exist, in the same pom.

    <repository>
      <id>codegenome</id>
      <url>https://artifacts.codegenomeproject.org/maven</url>
    </repository>
    <pluginRepository>
      <id>codegenome</id>
      <url>https://artifacts.codegenomeproject.org/maven</url>
    </pluginRepository>

To view the OpenRewrite recipes available, you can run mvn rewrite:discover.

Before modifying any files, you can execute a dry run with mvn rewrite:dryRun. OpenRewrite will scan your project and generate a detailed report showing exactly what changes will be made, along with patch diff files under target/rewrite/.

Once you have reviewed the dry-run diffs and confirmed the planned refactorings are correct, run the active recipe train to modify your source files in-place. To execute the recipes listed in the activeRecipes section of the rewrite plugin, run mvn rewrite:run.

More information on running the Broadleaf external module for Open Rewrite can be found in their documentation.

Spring Boot 4

Background

For Broadleaf’s 3.0.0 release, which upgrades the platform from Spring Boot 3.5.15 to Spring Boot 4.1.0 (along with Spring Security 7 and Hibernate 7), clients should be aware of several important architectural, dependency, and configuration changes.

Migration

Broadleaf provides an automated upgrade script (com.broadleafcommerce.Upgrade_3_0_0) via the rewrite-maven-plugin to automate the heavy lifting. See the migration notes above on setting up the rewrite plugin.

  • Updates for Spring dependencies, such as OAuth2 & Web Starters

    • Spring libraries such as spring-boot-starter-oauth2-client and spring-boot-starter-web have been renamed.

    • Broadleaf’s automated OpenRewrite recipe for 3.0.0 performs this refactoring globally.

  • Migrates spring-boot-starter-aop to spring-boot-starter-aspectj

    • Broadleaf’s automated OpenRewrite recipe for 3.0.0 performs this refactoring globally.

  • Updates legacy Mock annotations to the new standard replacements

    • i.e. updates annotations, such as @MockBean → @MockitoBean

    • Broadleaf’s automated OpenRewrite recipe for 3.0.0 performs this refactoring globally.

  • Automatically re-routes relocated core Spring Boot classes to their modern classpath locations. See the below table for a sample list of relocated classes used in the Broadleaf framework.

    • Broadleaf’s automated OpenRewrite recipe for 3.0.0 performs this refactoring globally.

Class Original Package New Package

JpaProperties

org.springframework.boot.autoconfigure.orm.jpa

org.springframework.boot.jpa.autoconfigure

HibernateProperties

org.springframework.boot.autoconfigure.orm.jpa

org.springframework.boot.hibernate.autoconfigure

HibernatePropertiesCustomizer

org.springframework.boot.autoconfigure.orm.jpa

org.springframework.boot.hibernate.autoconfigure

HibernateSettings

org.springframework.boot.autoconfigure.orm.jpa

org.springframework.boot.hibernate.autoconfigure

DataSourceAutoConfiguration

org.springframework.boot.autoconfigure.jdbc

org.springframework.boot.jdbc.autoconfigure

EntityManagerFactoryBuilder

org.springframework.boot.orm.jpa

org.springframework.boot.jpa

TransactionManagerCustomizers

org.springframework.boot.autoconfigure.transaction

org.springframework.boot.transaction.autoconfigure

JpaRepositoriesAutoConfiguration

org.springframework.boot.autoconfigure.data.jpa

org.springframework.boot.data.jpa.autoconfigure

SpringBeanContainer

org.springframework.orm.hibernate5

org.springframework.orm.jpa.hibernate

LiquibaseProperties

org.springframework.boot.autoconfigure.liquibase

org.springframework.boot.liquibase.autoconfigure

  • Resolves package-shifting issues for slice-based tests by safely injecting required slice configurations. See the below table for a list of test slices affected.

    • Broadleaf’s automated OpenRewrite recipe for 3.0.0 performs this refactoring globally.

Test Slice Original Package New Package

@AutoConfigureMockMvc

org.springframework.boot.test.autoconfigure.web.servlet.AutoConfigureMockMvc.imports

org.springframework.boot.webmvc.test.autoconfigure.AutoConfigureMockMvc.imports

@AutoConfigureWebMvc

org.springframework.boot.test.autoconfigure.web.servlet.AutoConfigureWebMvc.imports

org.springframework.boot.webmvc.test.autoconfigure.AutoConfigureWebMvc.imports

@AutoConfigureDataJpa

org.springframework.boot.test.autoconfigure.orm.jpa.AutoConfigureDataJpa.imports

org.springframework.boot.data.jpa.test.autoconfigure.AutoConfigureDataJpa.imports

Refer to the Spring Boot 4.0 and 4.1 release notes for the complete documentation. Since it was a major upgrade for Spring, the majority of the changes will be found in the 4.0 upgrade guide.

Spring Cloud

Background

Spring Cloud 5.0 (2025.1.2) is included as part of Spring Boot 4.1 dependencies.

Migration

  • The legacy spring-cloud-starter-parent Maven parent pom has been completely removed from the ecosystem. If this artifact was set as a parent, it must migrate to use the standard Spring Boot parent.

    • Broadleaf’s automated OpenRewrite recipe for 3.0.0 performs this refactoring globally.

Full release notes for Spring Cloud 2025.1.2 can be found in their Oakwood release blog as well as in their official release notes page.

Spring Security

Background

Spring Security 7.1 is included as part of Spring Boot 4.1 dependencies.

Migration

  • In Spring Security 7.0, the legacy configuration registration method .apply() has been completely removed in favor of the standardized, lambda-friendly .with() builder.

    • Migrate all DSL registrations to use http.with() paired with a customizer:

      • Before: http.apply(resourceSecurity());

      • After: http.with(resourceSecurity(), Customizer.withDefaults());

    • Broadleaf’s automated OpenRewrite recipe for 3.0.0 performs this refactoring globally.

  • The method signatures for AbstractHttpConfigurer initialization have been cleaned up and simplified in Spring Security 7.0.

    • The overridden init(HttpSecurity) and configure(HttpSecurity) methods on classes extending AbstractHttpConfigurer (such as ResourceSecurityDsl or other custom filters) no longer declare throws Exception in their base signatures.

    • Remove the throws Exception clause from your custom configurers to match the base signatures

    • Broadleaf’s automated OpenRewrite recipe for 3.0.0 performs this refactoring globally.

  • Spring Security 7.0 has completely removed MvcRequestMatcher and its dependency on HandlerMappingIntrospector to simplify and speed up servlet-path matching.

    • Broadleaf’s automated OpenRewrite recipe for 3.0.0 performs this refactoring globally.

Refer to the Spring Security 7.1 release notes for the complete documentation.

Hibernate

Background

Hibernate 7.4.1.Final is included as part of Spring Boot 4.1 dependencies.

Migration

  • Hibernate 7 enforces strict specification checks on Jakarta Persistence 3.2 cascade and flush cycles.

    • Attempting to persist or merge an entity tree where child collections contain references to unsaved (transient) objects is now strictly blocked and throws TransientObjectException.

    • Broadleaf introduced TransientReferenceResolvingInterceptor and its Customizer in CommonJpaAutoConfiguration to safely intercepts these cascades, resolve transient primary keys, and auto-persist them before Hibernate’s state validation block triggers.

  • Hibernate 7 has modernized its Service Provider Interface (SPI) for registering custom identifier generators.

    • Registering identifier generators (like Broadleaf’s default UlidIdentifierGenerator) via traditional hibernate property mappings is deprecated.

    • UlidIdentifierGenerator and UlidIntegrator are now registered natively using Hibernate 7’s StrategyRegistrationProvider and ServiceContributor SPI files.

  • In Hibernate 7, a number of annotations were removed or migrated. For example, the legacy @org.hibernate.annotations.Where annotation (which had been deprecated) has been completely removed from the library.

    • Any soft-delete or multi-tenant domain models relying on @Where to filter out records (e.g. @Where(clause = "ARCHIVED = 'N'")) will fail to compile. All usages should be replaced with the modern @SQLRestriction annotation. Note that the attribute name has changed from clause to value.

      • Before: @Where(clause = "ARCHIVED = 'N'")

      • After: @SQLRestriction("ARCHIVED = 'N'")

    • Broadleaf’s automated OpenRewrite recipe for 3.0.0 performs this refactoring for @org.hibernate.annotations.Where globally. The full list of affected annotations can be found in the Hibernate 7.0 migration guide.

Lombok

Background

When upgrading to Spring Boot 4.1, Lombok is upgraded to 1.18.46. This introduces a critical behavioral change that directly affects REST payload serialization/deserialization for custom domain objects, DTOs, and API projections.

Migration

  • Starting in version 1.18.40, Lombok reversed its default behavior and no longer automatically copies Jackson annotations (such as @JsonProperty, @JsonIgnore, @JsonInclude, or custom Jackson validators) from private fields to their generated getter and setter methods. Fields annotated with @JsonIgnore might start appearing in your JSON responses because Jackson reads the unannotated, generated getter method instead of the private field. Custom JSON field mappings (e.g., @JsonProperty("customer_id") on a field customerId) will fail to map during deserialization, resulting in null values because the generated setter lacks the annotation.

    • The previous behavior should be explicitly restored by updating the project’s root configuration to include the following property: lombok.copyJacksonAnnotationsToAccessors = true. If you do not have a lombok.config file in your project root, one should be created and with this line to ensure global compatibility across all your custom modules.

    • Broadleaf’s automated OpenRewrite recipe for 3.0.0 adds this annotation property to the lombok.config file in your project root (and creates a new lombok.config in your project root if one does not already exist).

  • Lombok has tightened its handling of @Builder and default field values.

    • If you use @Builder on a class with initialized field variables (e.g., private String status = "ACTIVE";), the builder pattern will bypass this default initialization unless explicitly instructed.

    • If your DTOs or domain models rely on default assignments while using @Builder, ensure you annotate those specific fields with @Builder.Default

For more details, see the Lombok changelog.

Jackson2

Background

Migrating from Jackson 2 to Jackson 3 introduces major breaking changes in package names, annotations, and API signatures. Broadleaf’s decision to remain on Jackson 2 instead of migrating to Jackson 3 during the 3.0.0 (Spring Boot 4.1) upgrade is driven by highly strategic engineering, risk-mitigation, and backward-compatibility factors. When the Broadleaf framework migrates to Jackson 3, all custom client projects, extension modules, SDKs, and third-party integrations will have to migrate to Jackson 3 annotations (com.fasterxml.jackson3 namespaces) simultaneously. To reduce the risk for clients adopting the Broadleaf 3.0.0 release, we’ve chosen to remain on Jackson 2 since it is still the industry standard.

Migration

  • Since Spring Jackson properties have changed property pathing, we’ve added an EnvironmentPostProcessor which will bridges standard Spring Boot Jackson properties, JacksonCompatibilityEnvironmentPostProcessor.

    • Dynamically bridges standard Spring Boot {@code spring.jackson.*} properties to {@code spring.jackson2.*} counterparts when Jackson 2 is the preferred JSON mapper.

    • For project hygiene, you can update your spring.jackson.* properties to correct to the new pathing spring.jackson2.*.

Solr

Background

As part of the upgrade to Spring Boot 4.1, Solr (and its core SolrJ dependency) has been upgraded to SolrJ 10. Full migration notes can be found on the Solr Upgrade Guide.

Migration

  • In SolrJ 10, the core solr-solrj dependency has been stripped of its transitive third-party dependencies (like ZooKeeper, Jetty HTTP, and Streaming Expressions) to make the library leaner.

    • Broadleaf’s automated OpenRewrite recipe for 3.0.0 adds the solr-solrj-jetty dependency only where required.

  • To avoid generic/vague names (like Http2), SolrJ 10 has renamed all client implementations that are backed by the Jetty HTTP Client and moved them to a dedicated .jetty subpackage. As part of this the historical HttpSolrClient based on Apache HttpClient 4.x has been completely removed in SolrJ 10.

    • Broadleaf’s automated OpenRewrite recipe for 3.0.0 replaces the org.apache.solr.client.solrj.impl.Http2SolrClient with org.apache.solr.client.solrj.jetty.HttpJettySolrClient.

  • Several core SolrJ classes have been relocated to better align with functional package scoping. The central query builder, org.apache.solr.client.solrj.SolrQuery, has moved packages to org.apache.solr.client.solrj.request.SolrQuery.

    • Broadleaf’s automated OpenRewrite recipe for 3.0.0 performs this refactoring globally.

  • The handling of client endpoint URLs has become strictly enforced to prevent routing issues.

  • The extension mechanism for customizing the underlying HTTP client sockets has been reorganized.

Refer to the Solr 10 upgrade notes for the complete documentation.

Apache Camel

Background

As part of the upgrade to Spring Boot 4.1, Apache Camel has been upgraded from 4.14.4 to 4.20.

Migration

  • To prepare for future parser strictness, Camel 4.20 has deprecated and removed several legacy binary operators containing spaces in their names.

  • The declarative handling of specific Data Types has been extracted into its own Enterprise Integration Pattern (EIP).

  • As part of alignment with modern Kubernetes and Service Mesh environments, the legacy camel-cloud module has been completely retired.

  • Camel’s telemetry and microservices tracing modules have been refactored to align with Spring Boot 4’s platform standards.

  • Upgrading Camel to 4.20 brings in the modern Apache Kafka Client 4.2.0 library.

  • The Camel engine has tightened its resource parsing guidelines during application startup.

  • To prevent remote code execution (RCE) vulnerabilities and protect runtime state, the execution component has been secured.

Other

  • You should consider adding the following Kafka logging property to prevent being spammed with benign WARN logs.

    • Set org.apache.kafka.clients.consumer.internals.OffsetFetcherUtils to ERROR.

    • See KAFKA-20449 for the details on why this is benign and suppression is expected.

  • GatewayServerPropertyRelocationApplicationContextInitializer converts a number of properties to their compatible format in the latest gateway version, and are emitted in the gateway logs when this occurs.

    • As part of project hygiene, these properties should be found via the logs & updated in the project. Properties to look for include:

      • spring.cloud.gateway.* configuration namespace has been remapped to spring.cloud.gateway.server.webflux.*, except for properties under spring.cloud.gateway.server.* which are not remapped.

Troubleshooting Guide

If you find that custom Metadata i18n labels are not being loaded, verify that the custom MetadataMessagesBasename classes are either annotated with @Component and scanned, or that they are registered as Spring Beans. The classes should be annotated with @Component by AddSpringComponentToMetadataMessages recipe if you’ve run the Broadleaf 3.0.0 OpenRewrite scripts.

If you notice a number of WARN logs from Kafka with Not updating high watermark for partition {} as it is no longer assigned, make sure to set the logging level of OffsetFetcherUtils to ERROR as noted in the "Other" migration section.

New and Notable Changes

Improved Support for $0 Checkouts and $0 Authorizations

  • Checkout Payment Expectations API: Broadleaf now provides a consolidated expectations endpoint (GET /checkout/{cartId}/payment-expectations) returning both immediate and future checkout payment expectations (paymentRequired and savedPaymentMethodRequired) alongside available payment method options. This guides the frontend on exactly what payment interactions are required to complete checkout, unifying presentations for standard and subscription carts.

  • Support for $0 Checkouts: Broadleaf now better supports zero-dollar checkout scenarios (e.g., promotional carts, free gifts, subscription trials, or postpaid subscriptions) with clear property-driven controls. By default, a $0 cart does not require a payment, unless the broadleaf.cartoperation.service.checkout.payment-required-for-zero-cart-total property is explicitly enabled.

  • $0 Authorizations for Saved Payment Method Registration: When checking out with zero-dollar cart totals (such as free trials) and saving a card for future use, Broadleaf can safely coordinate a $0.00 Authorize (account verification) transaction with the payment gateway to validate the card before tokenization and preservation. On success, the token is stored in the BLC_SAVED_PAYMENT_METHOD wallet table.

Added Support for Adyen Web v6

Added support for the Adyen Web v6 with supporting changes in broadleaf-adyen 2.0.0, broadleaf-payment-transaction-services 3.0.0 and broadleaf-cart-operation-services 3.0.0 services. The React library SDK, @broadleaf/adyen-payment-services-react 1.5.1, contains additional changes to support Adyen Web v6 as well.

Stripe Version Updates

The Stripe Java SDK in broadleaf-stripe 3.0.0 was updated from 29.1.0 to 32.1.0. This requires the Stripe API version 2026-04-22.dahlia

Notable Bug Fixes

Webclient Access Token Resolution for Background and Async Calls
Fixed Spurious Lock-Failure Events from a TOCTOU Race in the ZooKeeper Lock Monitor

Frontend Compatibility and Release Notes

  • AdminWeb 2.1.0

    • Recommended

    • Drops Node <22 support

    • Artifacts

      • @broadleaf/admin-components

      • @broadleaf/admin-stripe-components

      • @broadleaf/admin-tailwindcss

      • @broadleaf/admin-style

  • AdminWeb 2.0.2

    • Optional

    • Artifacts

      • @broadleaf/admin-components: 2.0.2

      • @broadleaf/admin-stripe-components: 2.0.2

      • @broadleaf/admin-tailwindcss: 2.0.0

      • @broadleaf/admin-style: 2.0.0

  • Auth JS SDK 1.6.8

    • Recommended

    • Artifacts

      • @broadleaf/auth-react

      • @broadleaf/auth-web

  • Commerce JS SDK 1.7.5

    • Recommended

    • Artifacts

      • @broadleaf/commerce-browse

      • @broadleaf/commerce-cart

      • @broadleaf/commerce-content

      • @broadleaf/commerce-core

      • @broadleaf/commerce-customer

      • @broadleaf/commerce-menu

      • @broadleaf/commerce-sandbox

      • @broadleaf/commerce-tenant

  • Commerce Quote UI 1.1.5

    • Recommended

  • Commerce Shared React 1.0.5

    • Recommended

  • Commerce Subscription React 1.0.5

    • Recommended

  • Payment JS SDK 1.5.0

    • Recommended

      • Includes third-party payment library upgrades and used by NextJS Starter 2.1.0

    • Artifacts

      • @broadleaf/adyen-payment-services-api

      • @broadleaf/adyen-payment-services-react

      • @broadleaf/amazon-payment-services-api

      • @broadleaf/amazon-payment-services-react

      • @broadleaf/braintree-payment-services-api

      • @broadleaf/braintree-payment-services-react

      • @broadleaf/checkout-com-payment-services-api

      • @broadleaf/checkout-com-payment-services-react

      • @broadleaf/myfatoorah-payment-services-api

      • @broadleaf/myfatoorah-payment-services-react

      • @broadleaf/stripe-payment-services-api

      • @broadleaf/stripe-payment-services-react

      • @broadleaf/tabby-payment-services-api

      • @broadleaf/tabby-payment-services-react

      • @broadleaf/payment-js

      • @broadleaf/payment-react

      • @broadleaf/paypal-checkout-js

      • @broadleaf/paypal-checkout-react

  • Payment JS SDK 1.4.3

    • Optional

    • Artifacts

      • @broadleaf/adyen-payment-services-api

      • @broadleaf/adyen-payment-services-react

      • @broadleaf/amazon-payment-services-api

      • @broadleaf/amazon-payment-services-react

      • @broadleaf/braintree-payment-services-api

      • @broadleaf/braintree-payment-services-react

      • @broadleaf/checkout-com-payment-services-api

      • @broadleaf/checkout-com-payment-services-react

      • @broadleaf/myfatoorah-payment-services-api

      • @broadleaf/myfatoorah-payment-services-react

      • @broadleaf/stripe-payment-services-api

      • @broadleaf/stripe-payment-services-react

      • @broadleaf/tabby-payment-services-api

      • @broadleaf/tabby-payment-services-react

      • @broadleaf/payment-js

      • @broadleaf/payment-react

      • @broadleaf/paypal-checkout-js

      • @broadleaf/paypal-checkout-react

  • Admin Starter 2.1.1

    • Important: Users are expected to build their own Admin Starter image. This is present for reference only.

    • Recommended

    • URL: repository.broadleafcommerce.com:5001/broadleaf/adminstarter:2.1.1

    • Drops Node <22 support

    • Uses Admin Web 2.1.0 libraries

  • Admin Starter 2.0.5

    • Important: Users are expected to build their own Admin Starter image. This is present for reference only.

    • Optional

    • URL: repository.broadleafcommerce.com:5001/broadleaf/adminstarter:2.0.5

    • Uses Admin Web 2.0.2 libraries

  • NextJS Starter 2.1.0

    • Recommended

      • Includes third-party payment library upgrades and Payment JS SDK 1.5.0

    • URL: repository.broadleafcommerce.com:5001/broadleaf/commerce-nextjs-starter:2.1.0

  • NextJS Starter 2.0.4

    • Maintenance-Only

    • URL: repository.broadleafcommerce.com:5001/broadleaf/commerce-nextjs-starter:2.0.4

  • Telco Starter 1.1.4

    • Recommended

    • URL: repository.broadleafcommerce.com:5001/broadleaf/telco-nextjs-starter:1.1.4

  • Open Api 3.0.0

    • Important: Users are expected to build their own Open API image. This is present for reference only.

Service-level Release Notes

Tax Provider Libraries

Utility Services