<plugin>
<artifactId>ms-upgrade-maven-plugin</artifactId>
<groupId>com.broadleafcommerce.microservices</groupId>
<version>2.0.0.3-GA</version>
</plugin>
- v1.0.0-latest-prod
The primary goal of this release is to upgrade the Broadleaf backend framework to Spring Boot 3, Spring Framework 6, and Spring Security 6. From the features and bug fixes perspective, this release is practically the same as the 1.8.6-GA Release.
To make this upgrade as easy as possible for clients, this release intentionally has a minimal number of Broadleaf-specific changes outside what is absolutely necessary to jump to the new Spring versions.
JDK 17. Spring Boot 3 (and as a result, Broadleaf 2.0.0) requires Java 17.
If you are currently using Java 11 for local dev or environments, you will need to upgrade your Java installation.
This includes any container images you have generated in the past for running your Broadleaf microservices. Refer to release_train_1_8_1_and_beyond_with_optional_java_17 for more information on using container images for running Broadleaf components under Java 17.
If you use IntelliJ run configurations to launch your Broadleaf Commerce flex packages, you will need to include additional VM options for those configurations to execute successfully under Java 17.
Not required if upgrading from a Broadleaf initializr project (should already be set for you)
Not required when launching flex packages via mvn spring-boot:run.
Check out your project(s) for upgrade preparation from your source control.
Run the maven upgrade plugin 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 Additional Notes for general information about the Spring Security and Spring Boot 3 upgrades from a Broadleaf perspective. Also, see the official Spring upgrade guides mentioned in the sections below.
Update your docker-compose.yml (for local dev) and Helm charts for deployments. See other for more information on container image changes.
Run your automated test suite and QA test your upgrade.
Broadleaf has introduced a new Maven plugin, com.broadleafcommerce.microservices:ms-upgrade-maven-plugin, to greatly reduce the burden of manually applying many of the required boilerplate changes.
When run, the plugin will automatically apply various changes to your source code that you can subsequently verify and commit.
Add the following maven coordinates to your project pom plugins section (the pom in the directory in which you’ll be running the plugin).
<plugin>
<artifactId>ms-upgrade-maven-plugin</artifactId>
<groupId>com.broadleafcommerce.microservices</groupId>
<version>2.0.0.3-GA</version>
</plugin>Also, add a new pluginRepositories element, if one does not already exist, in the same pom.
<pluginRepositories>
<pluginRepository>
<id>broadleaf-microservices</id>
<url>https://repository.broadleafcommerce.com/repository/microservices/</url>
</pluginRepository>
</pluginRepositories># Review help text for the plugin
mvn ms-upgrade:help -pl .
# Run the plugin against the Maven project in the current directory
mvn ms-upgrade:prepare|
Tip
|
Run this against each top-level Maven project in your codebase (it will recursively apply to child projects). For example, if you run a multi-module maven build where the entire project tree has a single, top-level pom.xml file, then you can cd to the root directory and run this plugin there. The plugin will prepare your entire project tree in this case. Caveat: if you have an aggregator pom whose subordinate pom files are parented elsewhere, then running the upgrade from the root will not work unless you add the plugin declaration to those subordinate pom files as well.
|
|
Tip
|
Review the output of the plugin help goal for available modules and options. By default, all upgrade modules are run. However, there are include and exclude options for the prepare goal that will allow you to execute a subset of the upgrade logic, if desired.
|
In most cases, the plugin will migrate your project code to Broadleaf 2.0.0, requiring little of you afterward to complete the upgrade. This includes the marked items mentioned in the sections below. It is likely your project will still require some minor updates to complete the upgrade. Here are a couple of common items we’ve encountered:
We’ve found that client installations may have import statements in Java classes that point to locations no longer present in upgraded third party libraries. This may require you to edit these imports to get your problem classes to compile.
Review your pom.xml files for explicit references to Broadleaf libraries and versions. You will need to update the version element for these to point to the 2.0.0-GA version.
The exception to this is Auth Services. While a customized Auth module does benefit from the upgrade tool for basic items, it is likely your customizations will require a more substantial code migration to work with Broadleaf Auth 2 (and the new Spring Authorization Server). See Auth 2 Release Notes for more details.
|
Tip
|
The Broadleaf microservices framework version 2.0.x is compatible with Broadleaf Auth Services version 1.x. Broadleaf Auth always runs in isolation, so it is possible for it to utilize a different version of Spring than the rest of the codebase. If convenient, you should be able to delay a more complicated Auth upgrade temporarily, while still upgrading the remainder of the framework. If you choose this option for your initial upgrade to 2.0.0, keep in mind that the 2.0.0-GA release train is essentially equivalent to the 1.8.6-GA release train + upgrading to Spring Boot 3. Therefore, when adopting the 2.0.0-GA release train, you should also update your Auth Services project to use the 1.8.6-GA release train which includes Auth Services 1.8.14-GA. This will ensure that Auth Services & the remainder of the framework are using compatible versions. |
The prior release of Broadleaf was on Spring Boot 2.7.14, which came with Spring Security 5.7.10. Spring later released Spring Security 5.8 as a 'transitional' release to allow migration to the new Spring Security 6.x patterns/APIs without actually upgrading to Spring Boot 3.0.
Broadleaf clients will go to Spring Boot 3 directly, skipping the Spring Security 5.8 intermediary step. This has the benefit of not requiring two separate migrations (5.7 → 5.8, then 5.8 → 6.0).
With that being said, Spring documents the bulk of the migration steps within the Spring Security 5.8 migration guide itself, so we will be referencing it here.
This section relates to a subset of Spring’s official Spring Security 6.0 migration guide. This represents the most common areas of client customization.
|
Important
|
It is important clients review their codebase for Spring Security utilization outside the scope of what is covered by the upgrade plugin. Additional Notes provides more context on the aspects covered in Spring’s migration guide. |
Use the new requestMatchers methods.
Handled by the upgrade plugin
See Additional Notes for more information.
Stop Using WebSecurityConfigurerAdapter
configure(HttpSecurity http) has been replaced with SecurityFilterChain beans, most notably in OAuth2ResourceWebSecurityConfiguration and AuthorizationServerWebSecurityConfiguration
The upgrade plugin will attempt to migrate simple cases of this for you
configure(WebSecurity web) has been replaced with WebSecurityCustomizer beans, most notably in ForwardedHeaderSecurityConfiguration (in sample configuration)
configure(AuthenticationManagerBuilder) has been replaced with a new global AuthenticationManager bean-based configuration (only relevant in AuthorizationServerWebSecurityConfiguration)
See Additional Notes for more information.
Use AuthorizationManager for Request Security
Handled by the upgrade plugin
This section is about changing http.authorizeRequests() to use the new http.authorizeHttpRequests() functionality that leverages AuthorizationFilter/AuthorizationManager rather than FilterSecurityInterceptor.
See Additional Notes for more information.
Spring Boot 3 includes a number of version upgrades to not only Spring Boot and Spring Framework components, but also Hibernate (and others). In addition, we also upgrade our Spring Cloud dependencies to be harmonized with Spring Boot 3.
This section relates to a subset of Spring’s official Spring Boot 3 migration guide. This represents the most common areas of client customization.
|
Important
|
It is important clients review their codebase for Spring utilization outside the scope of what is covered by the upgrade plugin. Additional Notes provides more context on the aspects covered in Spring’s migration guide. |
Some Spring framework properties have changed. Broadleaf has handled most/all interesting changes here internally and generally nothing will be required of you. However, Spring does provide a diagnostic library that will let you know if you have any properties declared that require migration.
It is generally a good idea to confirm this in your project. The instructions for using this library are here.
Jakarta EE libraries now replace much of the previously packaged javax code.
Handled by the upgrade plugin
Update Java file import statements to point to the jakarta package location, instead of javax.
Autoconfiguration and test slice declarations are no longer referenced from META-INF/spring.factories.
Handled by the upgrade plugin
These declarations must be externalized into separate files.
EnvironmentPostProcessors, and custom spring.factories utilization, remain in place. As a result, spring.factories files often remain, but with a reduced scope.
In integration tests, you cannot mix usage of the Spring Cloud Stream Test Binder and real middleware binders. If the test binder is detected on the classpath, it will take precedence and the middleware binder will be ignored. This may cause some confusion if you’re using a mix of tests, some using embedded Kafka, and some using the test binder in the same maven module. You should limit yourself to a single approach in your maven module.
In the latest Spring Cloud Stream, Spring has removed support for annotation based configuration. Broadleaf has introduced backward compatibility components to continue to support the legacy annotation-based approach. This requires the addition of several new Broadleaf dependencies to support the compatibility layer. Addition of the new compatibility dependencies is generally handled automatically by the upgrade plugin. Review Spring Cloud for more details.
Hibernate 6 is included as part of Spring Boot 3 dependencies. The most interesting change in Hibernate 6 is the optimization of Jpa Criteria conversion to SQL.
For @Id annotated entities using Ulid generation for the primary key, the Hibernate @Type annotation on the primary key field has changed to require a UserType reference.
Handled by the upgrade plugin.
The new UserType is com.broadleafcommerce.data.tracking.jpa.hibernate.UlidUserType
If your entity class uses a JPA converter to persist a Set collection as Json, you will need to use a Hibernate @Type instead of the JPA converter.
Handled by the upgrade plugin.
A type implementation to replace the converter should extend com.broadleafcommerce.common.jpa.usertype.AbstractSetType.
There are several other Broadleaf related migration concerns that are primarily handled by the upgrade plugin automation.
|
Important
|
Review any Helm charts you use for deployment to rectify container images and versions. This is not handled by the upgrade plugin. |
Non-Manifest Based Projects
Rename liquibase changelogs that have flexdemo in the filename. Change the portion of the name to component instead.
Handled by the upgrade plugin.
Also update any include references to these new file names in other changelogs.
This is required for supporting the liquibase emit phase in the maven build lifecycle.
Update docker-compose.yml with the latest versions of supporting services (non-manifest based projects).
Handled by the upgrade plugin.
This update only occurs when you are leveraging the out-of-the-box Broadleaf container images. If you have overridden images (e.g. extended MicroserviceGateways), you will need to upgrade your override project with the upgrade plugin and regenerate your image.
If you host your own images (not Broadleaf’s nexus), this upgrade step will not occur either.
If you are using Kafka for your message broker, and you are using the official confluent image, change to use the confluentinc/cp-kafka:7.3.3 version of the image.
If you are using the Broadleaf Solr image for search, change to use the repository.broadleafcommerce.com:5001/broadleaf/docker-solr:2.0.0-GA version of the image.
If you are using the official confluent image for Zookeeper, change to use the confluentinc/cp-zookeeper:7.3.3 version of the image.
If the upgrade plugin skips this step for any of these reasons, you will need to manually update the images in your docker-compose.yml file.
Refactor pom.xml project files to minimize contents and inherit functionality from Broadleaf starter parent pom.
Handled by the upgrade plugin.
This is a fairly detailed process and should be handled by using the upgrade plugin, rather than attempting manually.
This change facilitates Liquibase changelog construction and ModelMapper cache construction during the maven build lifecycle.
Integration tests that simulate startup of the module and use the liquibase changelogs to populate the backing TestContainers database should explicitly enable Liquibase.
Handled by the upgrade plugin.
Set the spring.liquibase.enabled=true test property in the startup integration test.
For service override maven modules (e.g. modules where you’ve created Broadleaf domain extensions, etc…), there should be a <broadleaf-service-key> maven property in the module pom file (in some cases, an additional <broadleaf-alt-service-key> maven property as well). This property identifies the service to the liquibase generation maven plugin that runs during standard maven builds. The insertion of the maven property is generally handled by the upgrade plugin automatically based on module filesystem directory name matching. However, you may find that one or more of your service override module pom files are missing this property if the name matching algorithm fails. In such a case, you can manually add the maven property based on this Reference Table.
Manifest-Based Projects
After running the upgrad plugin, compile your entire project (including manifest module) first.
At the command line in the manifest module, execute mvn docker-compose:generate. This will emit an updated docker-compose.yml file in your manifest module build directory for local dev use.
If you do not use the maven docker-compose plugin to manage your docker-compose.yml file
If the upgrade plugin is able to see your file (must be in a directory entitled docker directly inside one of your project directories), it will attempt to update the contents of the file. In such a case, you should review the contents of the file for correctness.
If the upgrade plugin is not able to see your file, you will need to manually update the images in your docker-compose.yml file.
Gateway Customizations
If you have customized the Broadleaf microservices gateway as an independent project in your codebase, you can use the upgrade plugin to migrate that project to 2.0 compatibility as well.
The upgrade plugin expects a particular structure matching the reference design for gateways. This includes a root pom, and two subordinate pom files - one for each of admin and commerce. If your gateway project structure diverges from this reference setup, the upgrade plugin may have diminished effectiveness.
Refer to gateway pom examples for an upgraded pom file reference.
Opentracing, Jaeger, and Libthrift are no longer used in 2.0 and should be removed from any project dependencies. This is generally handled automatically by the upgrade plugin.
If you find that you see errors during a build in the liquibase generation phase, it’s possible your module’s Spring application context is missing configuration or bean factories required to initialize Spring in isolation. This may require changes to make sure a modules application can start on its own. This is sometimes overlooked, but a successful Spring startup lifecycle is required for the liquibase step.