1.5 to 1.6 Migration
Maven Dependencies
Separate dependencies for "sources" jars are no longer required. If specified, separate dependencies on the "sources" classifier for the following can be removed:
- broadleaf-framework
- broadleaf-profile
- broadleaf-admin-module
- broadleaf-contentmanagement-module
- broadleaf-open-admin-platform
Package Refactoring
We have separated out commonly used elements and API into a separate jar. Not coincidentally, the maven module for this is called common and is located as a new first level module in the Broadleaf Commerce maven structure. This has caused a number of package changes for commonly used classes. Here are the most common changes - you will likely experience these as compile errors in an existing 1.5.x based build. Usually, these compilation errors can be easily handled with an update imports command in your Java IDE. However, you will need to also correct fully qualified classnames that have been declared in your custom Spring application context files.
| Old Location | New Location |
|---|---|
| org.broadleafcommerce.money | org.broadleafcommerce.common.money |
| org.broadleafcommerce.openadmin.client.dto | org.broadleafcommerce.common.presentation.client |
| org.broadleafcommerce.presentation | org.broadleafcommerce.common.presentation |
| org.broadleafcommerce.openadmin.client.presentation | org.broadleafcommerce.common.presentation |
| org.broadleafcommerce.openadmin.time | org.broadleafcommerce.common.time |
| org.broadleafcommerce.profile.extensibility | org.broadleafcommerce.common.extensibility |
| org.broadleafcommerce.openadmin.audit | org.broadleafcommerce.common.audit |
| org.broadleafcommerce.profile.cache | org.broadleafcommerce.common.cache |
| org.broadleafcommerce.config | org.broadleafcommerce.common.config |
| org.broadleafcommerce.profile.email | org.broadleafcommerce.common.email |
| org.broadleafcommerce.profile.encryption | org.broadleafcommerce.common.encryption |
| org.broadleafcommerce.profile.extensibility | org.broadleafcommerce.common.extensibility |
| org.broadleafcommerce.profile.jmx | org.broadleafcommerce.common.jmx |
| org.broadleafcommerce.profile.logging | org.broadleafcommerce.common.logging |
| org.broadleafcommerce.profile.payment | org.broadleafcommerce.common.payment |
| org.broadleafcommerce.persistence | org.broadleafcommerce.common.persistence |
| org.broadleafcommerce.core.security | org.broadleafcommerce.common.security |
| org.broadleafcommerce.profile.util | org.broadleafcommerce.common.util |
| org.broadleafcommerce.profile.core.util | org.broadleafcommerce.common.util |
| org.broadleafcommerce.profile.vendor | org.broadleafcommerce.common.vendor |
| org.broadleafcommerce.profile.web | org.broadleafcommerce.common.web |
| org.broadleafcommerce.common | org.broadleafcomemrce.common.time |
| org.broadleafcommerce.profile.core.domain.annotation | org.broadleafcommerce.common.time.domain |
| org.broadleafcommerce.profile.core.domain.listener | org.broadleafcommerce.common.time.domain |
Component Scans
Review the component scan definitions in your application context files. Make sure the packages are still correct. Also, you will likely need to add a component scan for org.broadleafcommerce.common to your main application context file.
<context:component-scan base-package="org.broadleafcommerce.common"/>
web.xml
Review filter and listener definitions in your web.xml files to make sure you have the correct package for any Broadleaf filters or listeners that you may be using. The most notable will be org.broadleafcommerce.profile.web.extensibility.MergeContextLoaderListener, which has been moved to org.broadleafcommerce.common.web.extensibility.MergeContextLoaderListener.
ehcache.xml
Review your ehcache configuration. If you've configured the HydratedCacheEventListenerFactory, it will need to change from org.broadleafcommerce.profile.cache.engine.HydratedCacheEventListenerFactory to org.broadleafcommerce.common.cache.engine.HydratedCacheEventListenerFactory.
Admin Security Config
Additional pages are now required to manage login and forgot password functionality for the admin. First, a change is required to applicationContext-admin-security.xml, however. Change this line:
<sec:form-login login-page='/login.jsp' default-target-url='/admin.html' authentication-failure-url="/login.jsp?login_error=true" login-processing-url="/admin/login_admin_post"/>
to this:
<sec:form-login login-page='/blcadmin/login' default-target-url='/admin.html' authentication-failure-url="/blcadmin/login?login_error=true" login-processing-url="/admin/login_admin_post"/>
Also, some additional config must be added to the applicationContext-servlet-admin.xml file. Add the following lines before bean definition for SimpleControllerHandlerAdapter:
<context:component-scan base-package="org.broadleafcommerce.openadmin.web"/>
<bean id="viewResolver" class="org.springframework.web.servlet.view.InternalResourceViewResolver">
<property name="viewClass" value="org.springframework.web.servlet.view.JstlView"/>
<property name="prefix" value="/WEB-INF/jsp/"/>
<property name="suffix" value=".jsp"/>
</bean>
<bean class="org.springframework.web.servlet.mvc.annotation.DefaultAnnotationHandlerMapping"/>
Several new jsp files must be added for login and forgot password support. The files, forgotPassword.jsp, forgotUsername.jsp, login.jsp and resetPassword.jsp must be added to WEB-INF/jsp/blcadmin in your admin project. A zip archive containing these files has been attached to this wiki page for your convenience (jsp.zip). Also, there are some associated css and image files associated with the login page. The attached zip archive (css.zip) must be expanded at the same level as your WEB-INF directory in your admin project.
Also, make sure the ACTIVE_STATUS_FLAG is set to true for your admin users in the BLC_ADMIN_USER table, or you will not be able to login to the admin application.
Note, the use of sec:jdbc-user-service in applicationContext-admin-security.xml has been deprecated. This bean definition should be abandoned in favor of Broadleaf's AdminUserDetailsService. This may be achieved by adding the following bean definitions to applicationContext-admin-security.xml.
<bean id="blAdminUserDetailsService" class="org.broadleafcommerce.openadmin.server.security.service.AdminUserDetailsServiceImpl"/>
<alias name="blAdminUserDetailsService" alias="userDetailsManager"/>
Schema Changes
The following sql script demonstrates the schema changes that have occurred between versions 1.5.5 and 1.6.0.
create table BLC_ADMIN_PASSWORD_TOKEN (PASSWORD_TOKEN varchar(255) not null, ADMIN_USER_ID bigint not null, CREATE_DATE timestamp not null, TOKEN_USED_DATE timestamp, TOKEN_USED_FLAG bit not null, primary key (PASSWORD_TOKEN))
alter table BLC_ADMIN_USER add column ACTIVE_STATUS_FLAG bit
alter table BLC_ADMIN_USER add column PHONE_NUMBER varchar(255)
alter table BLC_AMOUNT_ITEM add column SYSTEM_ID varchar(255)
alter table BLC_OFFER add column MAX_USES_PER_CUSTOMER bigint
alter table BLC_OFFER_AUDIT add column ORDER_ID bigint
create table BLC_ORDER_ATTRIBUTE (ORDER_ATTRIBUTE_ID bigint not null, NAME varchar(255) not null, VALUE varchar(255) not null, ORDER_ID bigint not null, primary key (ORDER_ATTRIBUTE_ID))
create table BLC_ORDER_ITEM_ATTRIBUTE (ORDER_ITEM_ATTRIBUTE_ID bigint not null, NAME varchar(255) not null, VALUE varchar(255) not null, ORDER_ITEM_ID bigint not null, primary key (ORDER_ITEM_ATTRIBUTE_ID))
alter table BLC_ADMIN_USER_PERMISSION_XREF add constraint FKF0B3BEED46EBC38 foreign key (ADMIN_USER_ID) references BLC_ADMIN_USER
alter table BLC_ADMIN_USER_PERMISSION_XREF add constraint FKF0B3BEEDE88B7D38 foreign key (ADMIN_PERMISSION_ID) references BLC_ADMIN_PERMISSION
create index OFFERAUDIT_ORDER_INDEX on BLC_OFFER_AUDIT (ORDER_ID)
alter table BLC_ORDER_ATTRIBUTE add constraint FKB3A467A589FE8A02 foreign key (ORDER_ID) references BLC_ORDER
alter table BLC_ORDER_ITEM_ATTRIBUTE add constraint FK9F1ED0C79AF166DF foreign key (ORDER_ITEM_ID) references BLC_ORDER_ITEM
The following script demonstrates the schema changes that have occurred between versions 1.5.0 and 1.6.0.
create table BLC_ADMIN_PASSWORD_TOKEN (PASSWORD_TOKEN varchar(255) not null, ADMIN_USER_ID bigint not null, CREATE_DATE timestamp not null, TOKEN_USED_DATE timestamp, TOKEN_USED_FLAG bit not null, primary key (PASSWORD_TOKEN))
alter table BLC_ADMIN_USER add column ACTIVE_STATUS_FLAG bit
alter table BLC_ADMIN_USER add column PHONE_NUMBER varchar(255)
alter table BLC_AMOUNT_ITEM add column SYSTEM_ID varchar(255)
alter table BLC_ASSET_DESC_MAP add column STATIC_ASSET_ID bigint not null
alter table BLC_OFFER add column MAX_USES_PER_CUSTOMER bigint
alter table BLC_OFFER_AUDIT add column ORDER_ID bigint
create table BLC_ORDER_ATTRIBUTE (ORDER_ATTRIBUTE_ID bigint not null, NAME varchar(255) not null, VALUE varchar(255) not null, ORDER_ID bigint not null, primary key (ORDER_ATTRIBUTE_ID))
alter table BLC_ORDER_ITEM_ADJUSTMENT add column APPLIED_TO_SALE_PRICE bit
create table BLC_ORDER_ITEM_ATTRIBUTE (ORDER_ITEM_ATTRIBUTE_ID bigint not null, NAME varchar(255) not null, VALUE varchar(255) not null, ORDER_ITEM_ID bigint not null, primary key (ORDER_ITEM_ATTRIBUTE_ID))
alter table BLC_QUAL_CRIT_SC_XREF add column SC_ID bigint not null
alter table BLC_SANDBOX_ACTION add column ACTION_COMMENT varchar(255)
create table CATEGORY_SHIPPING_COUNTRY_XREF (CATEGORY_ID bigint not null, SHIPPING_COUNTRY_ID bigint not null)
create table PRODUCT_SHIPPING_COUNTRY_XREF (SHIPPING_COUNTRY_ID bigint not null, PRODUCT_ID bigint not null)
create table PRODUCT_SKU_MYCOMPANY (RESTRICTED bit, PRODUCT_ID bigint not null, ZIP_CODE_ID varchar(255), primary key (PRODUCT_ID))
create table SHIPPING_COUNTRY (SHIPPING_COUNTRY_ID bigint not null, COUNTRY_ISO varchar(255), CURRENCY_CODE varchar(255) not null, primary key (SHIPPING_COUNTRY_ID))
alter table BLC_ADMIN_USER_PERMISSION_XREF add constraint FKF0B3BEED46EBC38 foreign key (ADMIN_USER_ID) references BLC_ADMIN_USER
alter table BLC_ADMIN_USER_PERMISSION_XREF add constraint FKF0B3BEEDE88B7D38 foreign key (ADMIN_PERMISSION_ID) references BLC_ADMIN_PERMISSION
alter table BLC_ASSET_DESC_MAP add constraint FKE886BAE367F70B63 foreign key (STATIC_ASSET_ID) references BLC_STATIC_ASSET
create index OFFERAUDIT_ORDER_INDEX on BLC_OFFER_AUDIT (ORDER_ID)
alter table BLC_ORDER_ATTRIBUTE add constraint FKB3A467A589FE8A02 foreign key (ORDER_ID) references BLC_ORDER
alter table BLC_ORDER_ITEM_ATTRIBUTE add constraint FK9F1ED0C79AF166DF foreign key (ORDER_ITEM_ID) references BLC_ORDER_ITEM
alter table BLC_QUAL_CRIT_SC_XREF add constraint FKC4A353AF13D95585 foreign key (SC_ID) references BLC_SC
alter table CATEGORY_SHIPPING_COUNTRY_XREF add constraint FK219B8EB4ABE9FE81 foreign key (CATEGORY_ID) references PRODUCT_SKU_MYCOMPANY
alter table CATEGORY_SHIPPING_COUNTRY_XREF add constraint FK219B8EB429501C36 foreign key (SHIPPING_COUNTRY_ID) references SHIPPING_COUNTRY
alter table PRODUCT_SHIPPING_COUNTRY_XREF add constraint FK982817C529501C36 foreign key (SHIPPING_COUNTRY_ID) references SHIPPING_COUNTRY
alter table PRODUCT_SHIPPING_COUNTRY_XREF add constraint FK982817C5B8BE1CF0 foreign key (PRODUCT_ID) references PRODUCT_SKU_MYCOMPANY
alter table PRODUCT_SKU_MYCOMPANY add constraint FKB4DFBCFF535236D2 foreign key (ZIP_CODE_ID) references BLC_ZIP_CODE
alter table PRODUCT_SKU_MYCOMPANY add constraint FKB4DFBCFF689F939C foreign key (PRODUCT_ID) references BLC_PRODUCT_SKU
create index CURRENCYCODE_INDEX on SHIPPING_COUNTRY (CURRENCY_CODE)
Obviously, some schema changes leaked into the support releases for the 1.5.x stream. It is our plan going forward to stick to a more strict policy of not introducing schema changes into support releases.
Additional Information
For additional information, or for a concrete configuration example, we highly suggest installing the latest 1.6.0-GA maven archetype locally and comparing the key configuration files mentioned above to those of the project you wish to migrate in order to get a better view of your target.
mvn archetype:create -DarchetypeGroupId=org.broadleafcommerce -DarchetypeArtifactId=ecommerce-archetype -DarchetypeVersion=1.6.0-GA -DgroupId=myGroupId -DartifactId=myArtifactId