7.0 to 7.1 Migration

These migration notes assume that you are upgrading from Broadleaf Framework 7.0 (e.g. 7.0.7-GA) to 7.1 (7.1.0-GA). There might be additional migration steps necessary for your particular implementation of Broadleaf. If so, please contact our support team at support@broadleafcommerce.com or reach out through Gitter.

An overview of new features, library upgrades, and resolved issues in the 7.1.0-GA release are detailed within the 7.1.0-GA Release Notes.

Module Compatibility with 7.1

The version for each Broadleaf module is managed through broadleaf-boot-starter-parent and broadleaf-bom. If your project defines explicit versions for individual modules, either remove the explicit version declarations (to inherit from the parent BOM) or update them. Here is the compatibility chart listing the modules and versions compatible with Broadleaf Framework 7.1:

Major Upgrades & Baseline Changes

Broadleaf 7.1 introduces modern framework baselines across all modules. Here are relevant resources to help with your implementations:

Spring Framework 7.x

• Spring Framework 7.0 Release Notes
• Spring Framework 6 to 7 Migration Guide

Spring Boot 4.x

• Spring Boot 4.1 Release Notes
• Spring Boot 4.0 Migration Guide
• Spring Boot Upgrading Documentation

Spring Security 7.x

• Spring Security Migration Guide
• Spring Security 6.5 to 7 Migration Reference

Hibernate ORM 7.x

• Hibernate ORM 7.0 Migration Guide

Jackson 3

• Migrating to Jackson 3
• Introducing Jackson 3 Support in Spring

Solr 9.10.x

• Major Changes in Solr 9

Code & Configuration Changes

Removed Classes

The following classes were removed in Broadleaf 7.1:

Note on Channel Processors: If your project previously configured ProtoChannelBeanPostProcessor, ProtoInsecureChannelProcessor, or ProtoSecureChannelProcessor in applicationContext-security.xml, remove these bean definitions. Modern servlet containers and reverse proxies handle SSL termination headers (e.g. X-Forwarded-Proto) natively via standard Spring ForwardedHeaderFilter or container configuration.

Deprecated Classes & Methods

• No new classes were deprecated in Broadleaf 7.1.
• Instead, Broadleaf cleaned up previously deprecated items and upstream deprecated APIs:
  • org.broadleafcommerce.common.util.UpdateExecutor.executeUpdateQuery(...): This previously deprecated method (which cleared the global L2 cache) was removed. Use executeUpdateQuery(EntityManager, String, String, Object[], Type[], List) instead.
  • Spring CookieLocaleResolver#determineDefaultLocale(): Deprecated in Spring 6 and removed in Spring 7. Custom overrides should be updated to modern Spring locale resolution mechanisms.
  • Spring Security AntPathRequestMatcher: Migrated to PathPatternRequestMatcher.

Newly Added Classes

The following classes and annotations were introduced in Broadleaf 7.1:

Runtime Bytecode Transformers with @Persister Annotation

Broadleaf historically relied on the org.hibernate.annotations.Persister annotation for bytecode transformation for sandboxable and auditable entities. In Hibernate 7, this annotation was removed entirely from Hibernate ORM without a direct replacement. Therefore, Broadleaf 7.1 introduces org.broadleafcommerce.common.extensibility.jpa.Persister as a drop-in replacement with the same target types (TYPE, METHOD, FIELD) and attribute (impl).

/* Example 1: Entity-Level Usage (Custom Entity Persister) */
@Entity
@Table(name = "MY_CUSTOM_PRODUCT")
@Persister(impl = MyCustomProductPersister.class) // Declares the custom entity persister
public class MyCustomProductImpl { 
    ....
    ....
    /* Example 2: Field / Method-Level Usage (Custom Collection Persister) */
    @OneToMany(mappedBy = "order", cascade = CascadeType.ALL) 
    @Persister(impl = MyCustomCollectionPersister.class) // Declares custom collection persister
    protected List<MyOrderItemImpl> orderItems = new ArrayList<>();

}

Entity ID Generation with @BroadleafIdGenerator Annotation

Hibernate 6/7 deprecated and removed support for @GenericGenerator in favor of @IdGeneratorType. Broadleaf 7.1 introduces @BroadleafIdGenerator to encapsulate the Broadleaf IdOverrideTableGenerator directly without requiring Hibernate's generic mechanism. In custom domain entities extending Broadleaf, replace @GeneratedValue and @GenericGenerator with @BroadleafIdGenerator:

// Before (7.0)
@Id
@GeneratedValue(generator = "CustomEntityId")
@GenericGenerator(
    name = "CustomEntityId",
    strategy = "org.broadleafcommerce.common.persistence.IdOverrideTableGenerator",
    parameters = {
        @Parameter(name = "segment_value", value = "CustomEntityImpl"),
        @Parameter(name = "entity_name", value = "com.mycompany.domain.CustomEntityImpl")
    }
)
@Column(name = "CUSTOM_ENTITY_ID")
protected Long id;

// After (7.1)
@Id
@BroadleafIdGenerator(
    segmentValue = "CustomEntityImpl",
    entityName = "com.mycompany.domain.CustomEntityImpl"
)
@Column(name = "CUSTOM_ENTITY_ID")
protected Long id;

Spring Related Changes

The Spring Security upgrade will require updating existing security configurations. Please consult the Spring migration guides mentioned above and update configurations as needed. Here is an example of modernizing HTTP security configuration:

public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
    http 
        .authorizeHttpRequests(req -> { // Recommended modern approach (replaces WebSecurityCustomizer / antMatchers)
            req.requestMatchers("/css/**", "/js/**", "/img/**", "/fonts/**", "/" + assetServerUrlPrefixInternal + "/**", "/favicon.ico", "/robots.txt").permitAll();
        })
        .redirectToHttps(Customizer.withDefaults()) // Replaces requiresChannel to enforce HTTPS and channel security
        .....;
    return http.build();
}

LOB/CLOB Text Mapping Changes

How LOB data is handled by JDBC varies from driver to driver. The approach below is used within the framework and has been proven to work best across all supported databases. However, review the Hibernate documentation for any database-specific handling.

@Lob
@JdbcType(LongVarcharJdbcType.class)
@Column(name = "STRUCTURED_DATA_TEXT", length = Length.LONG32 - 1)
private String structuredDataText;

Database & Properties Changes

1. Database Schema Changes

Domain Changes

Note: All SQL statements below are for MySQL. Adjust column types and syntax for other databases accordingly.

Scheduled Job Audit Columns

Added audit tracking columns CREATED_BY, DATE_CREATED, and UPDATED_BY:

ALTER TABLE `BLC_SCHED_JOB`
    ADD COLUMN `CREATED_BY` bigint DEFAULT NULL,
    ADD COLUMN `DATE_CREATED` datetime(6) DEFAULT NULL,
    ADD COLUMN `UPDATED_BY` bigint DEFAULT NULL;

Customer Index Additions

Broadleaf 7.1 adds indexes for customer username authentication and password reset token lookups:

CREATE INDEX CUSTOMER_USERNAME_INDEX ON BLC_CUSTOMER (USER_NAME);
CREATE INDEX CUST_PWD_TOKEN_CUST_USED_IDX ON BLC_CUSTOMER_PASSWORD_TOKEN (CUSTOMER_ID, TOKEN_USED_FLAG);

Translation Column Length Reductions (MySQL UTF8MB4)

To ensure the composite TRANSLATION_INDEX stays within MySQL's 3072-byte key prefix limit under utf8mb4 encoding, reduce column lengths:

ALTER TABLE BLC_TRANSLATION MODIFY COLUMN ENTITY_TYPE VARCHAR(100);
ALTER TABLE BLC_TRANSLATION MODIFY COLUMN LOCALE_CODE VARCHAR(50);

Creating Schema Changelog with Liquibase

To generate a complete diff changelog between your 7.0 database and the 7.1 schema:

1. Create a reference database from your 7.0 codebase.
2. Upgrade your local application configuration to 7.1 and point to a fresh database with hbm2ddl.auto=create.
3. Run liquibase diffChangeLog comparing the two databases:

changeLogFile: dbchangelog-7.0-to-7.1.xml
driver: com.mysql.cj.jdbc.Driver
url: jdbc:mysql://localhost:3306/broadleaf_70?characterEncoding=utf8&useUnicode=true&serverTimezone=UTC
username: root
password: password
referenceDriver: com.mysql.cj.jdbc.Driver
referenceUrl: jdbc:mysql://localhost:3306/broadleaf_71?characterEncoding=utf8&useUnicode=true&serverTimezone=UTC
referenceUsername: root
referencePassword: password
classpath: mysql-connector-j-8.0.33.jar

2. Property Changes

Starting with Hibernate 6.0, Hibernate overhauled its dialect architecture. In previous versions (Hibernate 5 and earlier), dialects had to be specified explicitly with a version number (such as MySQL57Dialect or PostgreSQL10Dialect). In Hibernate 6 and 7, these version-specific classes are deprecated/removed, and a single base dialect class dynamically alters its behavior at runtime based on the database version auto-detected from metadata. Update dialect properties to use one of the following:

blPU.hibernate.dialect=org.hibernate.dialect.MySQLDialect ## For MySQL
blCMSStorage.hibernate.dialect=org.hibernate.dialect.PostgreSQLDialect ## For PostgreSQL
blSecurePU.hibernate.dialect=org.broadleafcommerce.common.dialect.BroadleafOracleDialect ## Custom dialect extending org.hibernate.dialect.OracleDialect for Oracle
blEventPU.hibernate.dialect=org.hibernate.dialect.MariaDBDialect ## For MariaDB
blDemoPU.hibernate.dialect=org.hibernate.dialect.HSQLDialect ## For HSQLDB