5.1 to 5.2.0-GA Migration

These migration notes assumes that you are going from a Heat Clinic 5.1 demo to the 5.2 demo. There might be additional migration steps necessary for your particular implementation of Broadleaf. If so, please let us know through our Gitter, our Google Group, or by submitting a pull request to this documentation repo at https://github.com/BroadleafCommerce/docs.

Overview of new features in the 5.2.0-GA release are detailed within [[5.2.0-GA Release Notes | 5.2.0 GA]].

This document also assumes that you are on the latest 5.1 GA patch version of Broadleaf (at time of writing, 5.1.3-GA). If you have not upgraded your site to be on the latest 5.1 patch version, please do so before continuing and see the optional migration docs for each 5.1 patch version.

Module Compatibility with 5.2

If you are using any other Broadleaf modules, then those module versions will need to be updated to be compatible with broadleaf framework 5.2. Here is a compatibility chart listing all of the module versions that are compatible with broadleaf 5.2.

Database Updates

Data Changes

Table Renames

The BLC_PRORATED_ORDER_ITEM_ADJUSTMENT has been renamed as it is greater than 30 characters and fails startup on Oracle. Run the following query:

MySQL

RENAME TABLE BLC_PRORATED_ORDER_ITEM_ADJUSTMENT TO BLC_PRORATED_ORDER_ITEM_ADJUST;

Postgres

ALTER TABLE BLC_PRORATED_ORDER_ITEM_ADJUSTMENT RENAME TO BLC_PRORATED_ORDER_ITEM_ADJUST;

SQLServer

sp_rename 'BLC_PRORATED_ORDER_ITEM_ADJUSTMENT','BLC_PRORATED_ORDER_ITEM_ADJUST';

Oracle

Any class transformer that was added to fix the table name for oracle will need to removed, such as:

<bean id="proratedOrderItemAdjustmentTableClassTransformer" class="org.broadleafcommerce.common.extensibility.jpa.convert.AlterTableNameClassTransformer">
    <constructor-arg name="tableName" value="[CUSTOM_TABLE_NAME_FIX]" />
    <constructor-arg name="targetedClass" value="org.broadleafcommerce.core.offer.domain.ProratedOrderItemAdjustmentImpl" />
</bean>

and the table will need to renamed to BLC_PRORATED_ORDER_ITEM_ADJUST

RENAME [CUSTOM_TABLE_NAME_FIX] TO BLC_PRORATED_ORDER_ITEM_ADJUST;

Column Renames

MySQL

ALTER TABLE BLC_PRORATED_ORDER_ITEM_ADJUSTMENT CHANGE COLUMN PRORATED_ORDER_ITEM_ADJUSTMENT_ID PRORATED_ORDER_ITEM_ADJUST_ID BIGINT NOT NULL;

Oracle

Any class and class transformer that was added to fix the column name will need to be removed, such as:

<bean id="proratedOrderItemAdjustmentIdClassTransformer" class="org.broadleafcommerce.common.extensibility.jpa.copy.DirectCopyClassTransformer">
    <constructor-arg name="moduleName" value="custom" />
    <property name="xformTemplates">
        <map>
            <entry>
                <key><value>org.broadleafcommerce.core.offer.domain.ProratedOrderItemAdjustmentImpl</value></key>
                <value>com.custom.core.offer.domain.ProratedOrderItemAdjIdColumnWeave</value>
            </entry>
        </map>
    </property>
</bean>

and the id column will need to be renamed PRORATED_ORDER_ITEM_ADJUST_ID, here is some example sql to do that:

ALTER TABLE BLC_PRORATED_ORDER_ITEM_ADJUST ADD PRORATED_ORDER_ITEM_ADJUST_ID NUMBER(19,0);

UPDATE BLC_PRORATED_ORDER_ITEM_ADJUST SET PRORATED_ORDER_ITEM_ADJUST_ID = [CUSTOM_COLUMN_NAME_FIX];

ALTER TABLE BLC_PRORATED_ORDER_ITEM_ADJUST DROP CONSTRAINT SYS_C0041065;

ALTER TABLE BLC_PRORATED_ORDER_ITEM_ADJUST ADD CONSTRAINT SYS_C0041065 PRIMARY KEY (PRORATED_ORDER_ITEM_ADJUST_ID);

ALTER TABLE BLC_PRORATED_ORDER_ITEM_ADJUST DROP COLUMN [CUSTOM_COLUMN_NAME_FIX];

Schema Changes

The large majority of database changes can be generated by allowing Liquibase to automatically generate a database diff for you. This is detailed in Managing DB Versions Migrations With Liquibase.

Dependency Changes

The migration from 5.1 to 5.2 includes several dependency changes.

New Broadleaf BOM

In your root pom.xml of your project you might have individual properties that define every Broadleaf dependency. This might look something like this:

<properties>
    <blc.version>5.3.1-GA</blc.version>
    <broadleaf-pricelist.version>3.1.1-GA</broadleaf-pricelist.version>
    <broadleaf-enterprise.version>3.1.1-GA</broadleaf-enterprise.version>
    ...

We have released a Maven BOM ("Bill of Materials") that eliminates the need to specify each of these individual dependencies and ensures that you have a harmonized set of compatible Broadleaf dependencies. Add this to your root pom.xml in the <dependencyManagement> section:

<dependency>
    <groupId>com.broadleafcommerce</groupId>
    <artifactId>broadleaf-bom</artifactId>
    <version>5.2.0-GA</version>
    <type>pom</type>
    <scope>import</scope>
</dependency>

Once you do this, you can remove all of the broadleaf-* artifact <dependency> entries from your root pom.xml.

This still supports overriding individual versions of Broadleaf modules. For instance, to maintain your own version of Pricelist (for a hotfix, etc), simply override the property in your root pom.xml:

<properties>
    ...
    <broadleaf-pricelist.version>3.2.1-SNAPSHOT</broadleaf-pricelist.version>
</properties>

Spring and Spring Instrument

We have updated Spring to the current latest release version, 4.3.8.RELEASE. If you are running embedded Tomcat locally (meaning, you are using startsite.sh/bat and startadmin.sh/bat) then you should update the spring.instrument.version property to 4.3.9.RELEASE.

Log4j

To continue using Log4j, you will need to add your own dependency on log4j to your core pom.xml as we have removed our default dependency on it:

<dependency>
    <groupId>org.slf4j</groupId>
    <artifactId>slf4j-log4j12</artifactId>
    <version>1.6.1</version>
</dependency>

You may also take this opportunity to use a different logging framework. All new Broadleaf projects use Logback as the default logging implementation.

Configuration Changes

One of the main features of the Broadleaf 5.2 release is first-class support for Java @Configuration classes. XML configuration is still viable and existing xml will still work, but there are some slight differences in how the configuration is included. This section will cover the different configuration changes that need to be made to migrate to 5.2.

Update web.xml in the site project

The first part of moving to java configuration is to modify the web.xml files for site and admin. We are going to make several changes in these files:

1. Replace the lists of xml configuration in patchConfigLocation with an @Configuration classes and use a particular Spring contextClass to look for it
2. Replace the removed Broadleaf MergeContextLoader with spring's ContextLoaderListener
3. Add contextInitializerClasses to properly initialize the Broadleaf enviroment classes

Create a new @Configuration class

In the site project, create a new @Configuration class to hold the values in the web.xml patchConfigLocation param-value via an @ImportResource. Remove all of the entries that start with bl (these are all encapsulated within a single @EnabledBroadleafSiteRootAutoconfiguration) and move the remaining ones into an@ImportResource`.

For instance, given this patchConfigLocation:

<context-param>
    <param-name>patchConfigLocation</param-name>
    <param-value>
        classpath:/bl-open-admin-contentClient-applicationContext.xml
        classpath:/bl-cms-contentClient-applicationContext.xml
        classpath*:/blc-config/site/bl-*-applicationContext.xml
        classpath:/applicationContext-email.xml
        classpath:/applicationContext.xml
        /WEB-INF/applicationContext-datasource.xml
        /WEB-INF/applicationContext-rest-api-security.xml
        /WEB-INF/applicationContext-security.xml
        /WEB-INF/applicationContext-filter.xml
        /WEB-INF/applicationContext-workflow.xml
        /WEB-INF/applicationContext.xml
        /WEB-INF/applicationContext-multitenant-overrides.xml
        classpath:/applicationContext-core-postMultitenant.xml
    </param-value>
</context-param>

You will create a new @Configuration class like this:

@Configuration
@EnableBroadleafSiteRootAutoConfiguration
@ImportResource(value = {
        "classpath:/applicationContext-email.xml",
        "classpath:/applicationContext.xml",
        "/WEB-INF/applicationContext-datasource.xml",
        "/WEB-INF/applicationContext-rest-api-security.xml",
        "/WEB-INF/applicationContext-security.xml",
        "/WEB-INF/applicationContext-filter.xml",
        "/WEB-INF/applicationContext-workflow.xml",
        "/WEB-INF/applicationContext.xml",
        "/WEB-INF/applicationContext-multitenant-overrides.xml",
        "classpath:/applicationContext-core-postMultitenant.xml"})
public class SiteRootConfiguration { }

Replace the patchConfigLocation param

Now that we have moved the XML import files, delete the patchConfigLocation section from your web.xml. Then, add the following params to point to your new SiteRootContextConfiguration:

<context-param>
    <param-name>contextConfigLocation</param-name>
    <param-value>com.yourcompany.config.SiteRootAutoConfiguration</param-value>
</context-param>
<context-param>
    <param-name>contextClass</param-name>
    <param-value>org.springframework.web.context.support.AnnotationConfigWebApplicationContext</param-value>
</context-param>

Now, replace org.broadleafcommerce.common.web.extensibility.MergeContextLoader with org.springframework.web.context.ContextLoaderListener in the <listener-class> reference.

Update the Servlet configuration

Look for the DispatcherServlet entry that is mapped to / (this is the servlet that has classpath*:/blc-config/site/bl-*-applicationContext-servlet.xml in the contextConfigLocation). We will create a new @Configuration class out of the values here, again removing any entries that start with bl- which is converted to @EnableBroadleafSiteServletAutoConfiguration:

@Configuration
@EnableBroadleafSiteServletAutoConfiguration
@ImportResource({"/WEB-INF/applicationContext-servlet.xml"})
public class SiteServletContextConfiguration {}

Then update the servlet to point to this configuration class. Given a servlet configuration like this:

<servlet>
    <servlet-name>mycompany</servlet-name>
    <servlet-class>org.springframework.web.servlet.DispatcherServlet</servlet-class>
    <init-param>
        <param-name>contextConfigLocation</param-name>
        <param-value>
            classpath*:/blc-config/site/bl-*-applicationContext-servlet.xml
            classpath:/applicationContext-servlet-cms-contentClient.xml
            /WEB-INF/applicationContext-servlet.xml
        </param-value>
    </init-param>
    <load-on-startup>1</load-on-startup>
</servlet>

Replace it with this:

<servlet>
    <servlet-name>mycompany</servlet-name>
    <servlet-class>org.springframework.web.servlet.DispatcherServlet</servlet-class>
    <init-param>
        <param-name> contextClass </param-name>
        <param-value>
            org.springframework.web.context.support.AnnotationConfigWebApplicationContext
        </param-value>
    </init-param>
    <init-param>
        <param-name>contextConfigLocation</param-name>
        <param-value>
            com.yourcompany.SiteServletContextConfiguration
        </param-value>
    </init-param>
    <load-on-startup>1</load-on-startup>
</servlet>

Add a new contextInitializerClasses parameter

Add this anywhere in web.xml (usually near the top):

<context-param>
    <param-name>contextInitializerClasses</param-name>
    <param-value>org.broadleafcommerce.common.config.BroadleafEnvironmentConfiguringApplicationListener</param-value>
</context-param>

Example final version of the site web.xml

Update web.xml in the admin project

Follow the same steps as above that you did for the site project. The difference is that in your @Configuration classes, use @ EnableBroadleafAdminRootAutoConfiguration and @EnableBroadleafAdminServletAutoConfiguration

Example final version of the admin web.xml

Update applicationContext-servlet-admin.xml in the admin project

Remove anything with <mvc:annotation-driven /> and <mvc:default-servlet-handler />. This is added by default now by Broadleaf and keeping this here will interfere with out-of-the-box admin API endpoints.

Remove the entire <mvc:interceptors> section that contains the LocaleChangeInterceptor. If you have more interceptors then those can stay but the LocaleChangeInterceptor is added by default.

Remove Explicit XML Schema Versioning

In the past we have used explicit versioning for our xml namespaces. This has been known to lead to Spring enabling/disabling behavior depending on what xsd schema is referenced. We want to consistently be using the most recent xsd so we are removing the version qualifier. To do this in your code base, simply do a find and replace using the following regex:

Find: (spring-.*)-[0-9]\.[0-9].xsd
Replace: $1.xsd

Remove duplicated bean ids in favor of MergeBeanPostProcessor

Part of the 5.2 release is a removal of the custom Broadleaf xml merge process. 5.1 and ealier versions of Broadleaf took a combined list of Spring xml configuration (from patchConfigLocations) together and merged things like list elements, collections and maps with the same bean ID. Since this XML merge process is no longer in play, redefining a bean ID in your own XML files has the same behavior that Spring has by default: overrides the bean definitions.

In order to allow the ability to continue merging collections and maps, we have added an EarlyStageMergeBeanPostProcessor and LateStageMergeBeanPostProcessor, depending on if the bean is necessary for persistence configuration or not. Here is an example of the before and after for merging entity contexts:

// BEFORE
<bean id="blMergedEntityContexts" class="org.springframework.beans.factory.config.ListFactoryBean">
    <property name="sourceList">
       <list>
          <value>classpath:applicationContext-entity.xml</value>
       </list>
    </property>
</bean>

// AFTER
<bean id="blMergedEntityContexts-core" class="org.springframework.beans.factory.config.ListFactoryBean">
    <property name="sourceList">
        <list>
            <value>classpath:applicationContext-entity.xml</value>
        </list>
    </property>
</bean>

<bean class="org.broadleafcommerce.common.extensibility.context.merge.EarlyStageMergeBeanPostProcessor">
    <property name="collectionRef" value="blMergedEntityContexts-core"/>
    <property name="targetRef" value="blMergedEntityContexts"/>
 </bean>

To help with this migration we have written a tool that can verify and modify your existing Spring XML files. Follow the instructions in the README of the Broadleaf XML Migrator for upgrading your project.

If you would like to move these definitions to Java @Configuration classes, you can also achieve the same results with this:

@Configuration
public class CustomEntityConfigs {
    @Merge(targetRef = "blMergedEntityContexts", early = true)
    public List<String> entityOverrides() {
        return Arrays.asList("classpath:applicationContext-entity.xml");
    }
}

Migrate Message Sources

The 5.2 release includes a change to how message sources are defined. There is no longer a BroadleafMergeResourceBundleMessageSource, and now adding a custom message source is much simpler. All one has to do to add a new message source is merge into the blMessageSourceBaseNames bean.

First, look for this bean in your XML files (both the site and admin projects will have this):

<bean id="messageSource" class="org.broadleafcommerce.common.util.BroadleafMergeResourceBundleMessageSource">
    <property name="basenames">
        <list>
            <value>classpath:messages</value>
        </list>
    </property>
</bean>

XML

<bean id="customMessages" class="org.springframework.beans.factory.config.ListFactoryBean">
    <property name="sourceList">
        <list>
            <value>classpath:messages</value>
        </list>
    </property>
</bean>

<bean class="org.broadleafcommerce.common.extensibility.context.merge.LateStageMergeBeanPostProcessor">
    <property name="collectionRef" value="customMessages" />
    <property name="targetRef" value="blMessageSourceBaseNames" />
</bean>

Java

@Merge("blMessageSourceBaseNames")
public List<String> customMessages() {
    return Arrays.asList("classpath:messages");
}

Migrate Property Configuration

The 5.2 release also includes some changes to property configuration that require migration. There are only a few changes that need to be made to ensure property configuration works when migrating to 5.2.

1. Remove any entries for the blConfiguration bean from applicationContext.xml and applicationContext-admin.xml.
2. Ensure the contextInitializerClasses with value org.broadleafcommerce.common.config.BroadleafEnvironmentConfiguringApplicationListener in your web.xml (this was done in an earlier section).

For more on the property configuration changes, go to Runtime Environment Configuration

Migrate Spring Security Configuration

We have upgraded our Spring Security dependency from 3.2.9.RELEASE to 4.2.2.RELEASE. One of the main differences with this version of Spring Security is the first-class support for Java configuration. We recommend following this migration guide to upgrade you Broadleaf Spring Security configuration, and then deciding whether or not to move to Java @Configuration classes (not required).

If you have custom Spring Security integrations then those will likely also need to be updated. Spring Security has a guide that covers an exhaustive list of items that you will need to migrate in order to use Spring Security 4.2.

Finally, this security section is geared towards complex setups (genally users that are using our MultiTenant product) so you might not have all of the XML configuration that you need to delete. If you can't find it in your files just skip over it.

Login Form Changes

Spring Security 3.2 used to assume the username and password inputs were named j_username and j_password. The new defaults are username and password so you will need to update any login forms to send these inputs instead to the /login endpoint.

Update applicationContext-admin-security.xml

1. Remove the component-scan for org.broadleafcommerce.profile.web.core.security and org.broadleafcommerce.core.web.order.security

2. Remove the entry-point-ref="adminAuthenticationEntryPoint" property from the sec:http configuration

3. If you have a blAdminFilterSecurityInterceptor, move all of the <sec:intercept-url> entries out of the <sec:filter-security-metadata-source> and into the <sec:http> section. Then you can delete the entire blAdminFilterSecurityInterceptor bean and its contents

   Once these entries are moved, they need to be converted to expressions. This is a pretty easy find/replace migration:

   1. Replace PERMISSION_OTHER_DEFAULT with isAuthenticated()
   2. Replace PERMISSION_(.*) with hasRole('$1')
   3. Replace ROLE_ANONYMOUS with permitAll

   Note that we no longer have a customized PERMISSION_ required prefix. These are now converted to ROLE_ in order to provide better out-of-the-box support for Spring Security. The older permissions are still added as apart of the Authentication user but they will eventually be removed.

4. Remove the following beans and their references:

   1. blSecurityFilter along with the <sec:custom-filter> that references it
   2. adminAuthenticationEntryPoint
   3. blAdminUserDetailsService
   4. blAdminFilterSecurityInterceptor along with the <sec:custom-filter> that references it
   5. blGlobalDecisionVoters
   6. blFilterDecisionVoters
   7. blMethodExpressionHandler
   8. blPreInvocationAdvice
   9. blMethodDecisionVoters
   10. blFilterAccessDecisionManager
   11. blMethodAccessDecisionManager

5. Disable the out of the box CSRF and frame-options handlings. Add this inside the <sec:http> section:

   <sec:csrf disabled="true" />
   <sec:headers>
       <sec:frame-options disabled="true">
   </sec:headers>
   

6. Add a login-page="/login" attribute to <sec:form-login>:

   <sec:form-login
        authentication-success-handler-ref="blAdminAuthenticationSuccessHandler"
        authentication-failure-handler-ref="blAdminAuthenticationFailureHandler"
        login-processing-url="/login_admin_post"
        login-page="/login"
        />
   

7. Add a logout-success-url="/login" to <sec:logout> and remove the success-handler-ref:

   <sec:logout invalidate-session="true"
          logout-url="/adminLogout.htm"
          logout-success-url="/login"/>
   

8. Add <sec:custom-filter ref="blAdminCsrfFilter" before="FORM_LOGIN_FILTER" /> to the other <sec:custom-filter> entries within <sec:http>

9. Modify sec:authentication-manager to remove the <sec:password-encoder> reference:

   <sec:authentication-manager alias="blAdminAuthenticationManager">
       <sec:authentication-provider ref="blAdminAuthenticationProvider" />
   </sec:authentication-manager>
   

10. Ensure that global method security with all annotations are enabled:

    <sec:global-method-security pre-post-annotations="enabled" secured-annotations="enabled"/>
    

Example final version of applicationContext-admin-security.xml

Update applicationContext-security.xml

1. Remove the <context:component-scan> entries for org.broadleafcommerce.common.web.security, org.broadleafcommerce.profile.web.core.security and org.broadleafcommerce.core.web.order.security

2. Disable csrf and security headers:

   <sec:csrf disabled="true"/>
   <sec:headers>
       <sec:frame-options disabled="true"/>
   </sec:headers>
   

3. Replace all ROLE_USER entries with isAuthenticated() since security expressions are enabled by default.

4. Optionally allow @Secured, @PreAuthorize and @PostAuthorize annotations by modifying <sec:global-method-security>:

   <sec:global-method-security pre-post-annotations="enabled" secured-annotations="enabled" />
   

Finally, recent browser versions have standarized on the assumption that cookies and sessions should not be shared between HTTP and HTTPS. Google also now uses SSL-only as an indicator to give your site a higher SEO boost. Because of this, all of our new Broadleaf starters are forced HTTPS by default, and we recommend you make that change as well. This is as simple as replacing any requires-channel="http" or requires-channel="any" with requires-channel="https". To ensure all of your pages use SSL, add the following after all of your other <sec:intercept-url> entries:

xml
<sec:intercept-url pattern="/**" requires-channel="https" />


Example final version of applicationContext-security.xml

Miscellaneous configuration updates

• Remove the <mvc:default-servlet-handler /> from applicationContext-servlet-admin.xml

• Replace any beans that use a property-specifier in a <bean class="" with a PropertyDrivenBeanFactory. Example, replace this:

  <bean id="blOrderAdminSolrServer" class="${oms.search.order.service.solr.className}">
  

  with this:

  <bean id="blOrderAdminSolrServer" class="org.broadleafcommerce.common.util.PropertyDrivenBeanFactory" factory-method="createInstance">
      <constructor-arg value="${oms.search.order.service.solr.className}"/>
  

  Keeping all of the other bean properties the same.

• Add an API component scan: <context:component-scan base-package="org.broadleafcommerce.api.common"/> to applicationContext-filter.xml, if you are using the out of the box Broadleaf APIs

• Remove the following beans that are now specified in Broadleaf core, in both site/src/main/webapp/WEB-INF/applicationContext.xml and admin/src/main/webapp/WEB-INF/applicationContext.xml:

  <bean id="blJsResources" parent="adminJsResourceHttpRequestHandlerBase" />
  <bean id="blCssResources" parent="adminCssResourceHttpRequestHandlerBase" />
  <bean id="blImageResources" parent="siteImageResourceRequestHandlerBase" />
  <bean id="blFontResources" parent="siteFontResourceRequestHandlerBase" />
  

SolrCloud Configuration

If you are using SolrCloud, then you will need to manually add the Zookeeper dependency to your project because it is now excluded from the transitive Solr dependency in the Broadleaf Commerce framework. Simply add this dependency to your pom.xml:

<dependency>
    <groupId>org.apache.zookeeper</groupId>
    <artifactId>zookeeper</artifactId>
    <version>3.4.9</version>
</dependency>

Data Changes

Root Categories Sort Order

In 5.2, the BLC_CATEWGORY table now has a column to sort the ROOT categories. Sub-categories are tracked in the BLC_CATEGORY_XREF table and will have a "sort order" relative to other sub-categories associated with a parent category. ROOT categories are not present in the "xref" table so another mechanism is needed to sort the root categories. The new column in BLC_CATEGORY called ROOT_DISPLAY_ORDER services this purpose. As part of your data migration to 5.2+, this column should be populated with the sort order desired for the ROOT cateogies on your site.

Miscellaneous and Optional

Import SQL Configuration

If you are not using Hibernate to import sql files using blPU.hibernate.hbm2ddl.import_files currently (this is true if you are already in production), you may skip this section.

We have made a transition from explicitly defining static files for import sql, to using java configuration. If you are using hibernate to import sql files, you can make the following changes to java configuration.

1. Remove your old blPU.hibernate.hbm2ddl.import_files entry

2. Create a ImportSQLConfig in core much like the following configuration from our demo

   @Configuration("blPrivateDemoData")
   @Conditional(ImportCondition.class)
   public class ImportSQLConfig {
   
       @Bean
       public AutoImportSql blPrivateDemoSecurityData() {
           return new AutoImportSql(AutoImportPersistenceUnit.BL_PU,"/sql/load_private_demo_admin_security.sql", AutoImportStage.PRIMARY_POST_MODULE_SECURITY);
       }
   
       @Bean
       public AutoImportSql blPrivateDemoAdminOverviewData() {
           return new AutoImportSql(AutoImportPersistenceUnit.BL_PU,"/sql/load_private_demo_admin_overview_data.sql", org.broadleafcommerce.cms.demo.ImportSQLConfig.BASIC_DATA_SPECIAL);
       }
   
       @Bean
       public AutoImportSql blPrivateDemoTenantData() {
           return new AutoImportSql(AutoImportPersistenceUnit.BL_PU,"/sql/load_private_demo_tenant_data.sql", AutoImportStage.PRIMARY_LATE);
       }
   
   }
   

Note: Any sql files you were referencing from within Broadleaf do not need to be included here, only custom sql files you created.

Embedded Solr

We have removed all support for using embedded Solr, which used to be the default on Community. To figure out if you are using embedded Solr, you should look for this configuration in site/src/main/webapp/WEB-INF/applicationContext.xml:

solr.source.primary=solrEmbedded
solr.source.reindex=solrEmbedded
solr.source.admin=solrEmbedded

If these properties are set to solrEmbedded, you must modify these as well as the beans within site/src/main/webapp/WEB-INF/applicationContext.xml. Follow the instructions in the comments around those properties/beans to update your configuration, and the instructions in Solr Standalone Setup.

To make it easier to run a Standalone server easier, we created a project called broadleaf-solr-starter. This will download a full version of Solr and tie the execution of it to your running server. To utilize this, add the dependency to your project:

<dependency>
    <groupId>org.broadleafcommerce</groupId>
    <artifactId>broadleaf-solr-starter</artifactId>
    <version>5.2.0-GA</version>
</dependency>

And then import SolrAutoConfiguration from a component-scanned @Configuration class. Automatically provisioning Solr in this way is likely not suitable for other environments other than local, so we recommend only enabling this configuration in certain environments with @Profile. This example enables the automatic Solr download for all environments except for production:

@Configuration
@Profile({"!production"})
@Import(SolrAutoConfiguration.class)
public static class SolrConfiguration { }

Migrate from BLCSystemProperty to Environment

Before 5.2 of Broadleaf, BLCSystemProperty.resolveSystemProperty was the standard way of resolving system properties. As of 5.2 this functionality is now deprecated and will be removed in the release after. The new way of resolving system properties uses Spring's Environment bean. This change is optional, but highly recommended as future releases may remove BLCSystemProperty altogether.

// BEFORE
protected Boolean getSomeBooleanProperty() {
    return BLCSystemProperty.resolveBooleanSystemProperty("some.boolean.property", false);
}

// AFTER
@Autowired
protected Environment env;

protected Boolean getSomeBooleanProperty() {
    return env.getProperty("some.boolean.property", Boolean.class, false);
}

@EnableAllFrameworkControllers

Additionally, if you are using any Broadleaf framework controllers, be sure to include EnableAllFrameworkControllers on your servlet configuration (this must be done for admin). For more on framework controllers, visit Framework Controllers.

Migrate environment specifiers

The previous way to specify which environment the application is running in was to use a system argument, -Druntime.environment=production. While this will still continue to work, you will get a warning message about moving to Spring profiles. To use this, replace all of the places in your startup arguments to use -Dspring.profiles.active instead. For more information see the Spring reference docs.

Default Environment

If you did not specify a -Druntime.environment value then the default was development. This is now registered as a -Dspring.profiles.default, but we recommend changing any specifiers that use development (like development.properties and development-shared.properties) to use default instead. For more information see the Spring reference docs .

Property Overrides

While environment-specific overrides using -Dproperty-override and -Dproperty-shared-override is still supported, you might consider using the default Spring overrides instead. If you decide to migrate to Spring Boot, you can use all of the externalized configuration that goes along with it. If you are not using Spring Boot, the normal Spring Framework allows you to specify individual property overrides as -D arguments or as environment variables.

Sizing the Default Enterprise Collections Cache

If you are utilizing the Enterprise module, you should consider the size of the defaultSandboxableCollectionQueryCache cache. Please see Caching Configuration for additional information.

Migrating to Spring Boot

Generally migrating to Spring Boot is not required.

Remove @EnableWebMVC from RestApiMvcConfiguration

Since Spring Boot Autoconfiguration maps in the the default RequestMappingHandlerMapping this unnecessarily duplicates it and interferes with the FrameworkControllerHandlerMapping

(Optional) Remove locale resolver configuration for site

Unless customized for the particular application, adding the LocaleChangeInterceptor and registering the localeResolver bean configuration for the site servlet can be removed as they have been added to the framework configuration. For example, this section can be removed from site/src/main/webapp/WEB-INF/applicationContext-servlet.xml:

<mvc:interceptors>
    <!-- Interceptor for blLocalCode-->
    <bean class="org.springframework.web.servlet.i18n.LocaleChangeInterceptor">
        <property name="paramName" value="blLocaleCode"/>
    </bean>
</mvc:interceptors>

<!-- Default locale set -->
<bean id="localeResolver" class="org.springframework.web.servlet.i18n.CookieLocaleResolver">
    <property name="cookieHttpOnly" value="true" />
    <property name="defaultLocale" value="en"/>
</bean>