The upgrade process from 2.x to 3.0 includes several important changes that must be addressed manually. These important manual tasks are listed below. In addition, if you have customized SoftSlate Commerce, we strongly encourage you to perform the upgrade first in a development environment. The new release includes a number of API changes which may need to be addressed if you have subclassed core SoftSlate Commerce classes. These issues should be addressed in a development environment, where all the customized functionality may be tested before deploying to a live environment.
Starting with version 3.0, upgrades will distribute a new /WEB-INF/classes/appComponents.properties file
which will overwrite the existing appComponents.properties file in your installation. Even if you
have not edited that file directly, there are functions in the Administrator that alter it. For this reason, to preserve
those changes, you must rename your existing appComponents.properties to appComponents-custom.properties
before copying the upgrade into place. The custom file will not be overwritten with future upgrades, and any
configurations in it will take precedence.
![[Note]](images/note.png) | Note |
|---|---|
Each time the application is started up, it will review the contents of |
Because of the introduction of appComponents-custom.properties, references to the internal
"appComponents" object should be updated in any custom JSP templates you have created.
Specifically, if you have created custom versions of any of the following templates,
you will need to update references to "appComponents" in them:
/WEB-INF/layouts/custom/order/cart.jsp/WEB-INF/layouts/custom/order/paymentFormGuts.jsp/WEB-INF/layouts/custom/order/paymentForms.jsp
Please refer to the new default versions of those templates distributed with version 3.0.0 for how to refer to the
"appComponents" object. In brief, where before the properties of appComponents could be referred to directly in a JSP
tag, they must now be referred to using the Properties.getProperty() method. Here is an example from cart.jsp:
<%--Third party checkout buttons--%>
<%
java.util.Properties appComponents = (java.util.Properties) application.getAttribute("appComponents");
String activePaymentFormTemplates = appComponents.getProperty("activePaymentFormTemplates");
pageContext.setAttribute("activePaymentFormTemplates", activePaymentFormTemplates);
%>
<%--PayPal Express checkout button--%>
<logic:match name="activePaymentFormTemplates" value="paypalExpressForm.jsp">
...
Starting with version 3.0, the method for extending the system's beans has changed and if you have
created any custom beans that extend a built-in bean, you must update your Hibernate mappings accordingly.
To illustrate the change, let's assume you have customized the ProductBean class
and added a field named "author". Prior to 3.0, you would have created a custom mapping file by copying the
ProductBean.hbm.xml mapping file and then
replacing the "subclass" element to include the name of the new custom class and the new "author" field.
As of 3.0, you should update these custom mapping files so that they instead just contain a single "subclass"
element that refers to the original
mapping with the "extends" attribute, like this:
<hibernate-mapping> <subclass name="com.softslate.commerce.demo.CustomProduct" extends="com.softslate.commerce.businessobjects.product.ProductBean"> <property name="author" length="255"/> </subclass> </hibernate-mapping>
Not updating the mappings files will result in errors and the application will not start up. This new method will make it easier to incorporate future versions of the built-in beans, since the details of their mappings will not have been copied into a custom file.
In support of the upgrade to the JSTL 1.1 tag library descriptors (.tld files) and the 2.4 servlet specification, a critical change is required in the /WEB-INF/web.xml file. Since that file is not distributed with upgrades, it must be manually upgraded prior to the upgrade.
To execute the change, open the web.xml file and replace the following lines at the very top of the file ...
<?xml version="1.0" encoding="ISO-8859-1"?> <!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN" "http://java.sun.com/dtd/web-app_2_3.dtd"> <web-app>
... with the following lines, declaring the servlet 2.4 specification:
<?xml version="1.0" encoding="ISO-8859-1"?> <web-app version="2.4" xmlns="http://java.sun.com/xml/ns/j2ee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd">
Numerous JSP and Struts changes have taken place within the Administrator to support the new look and feel and other improvements. If you have created custom screens in the Administrator, or customized any of the default templates, please deploy the upgrade to a development environment first so you can review all of the custom functionality and make any necessary changes.
Table B.2. Potential JSP and Struts Customization Conflicts
| Screen | Symptom | Error message in log file | How to fix |
|---|---|---|---|
| Administrator -> Product Catalog -> Products | Blank product control screen | Cannot find bean: "manufacturerCollection" in any scope | Copy the new default productFieldColumns.jsp file into the custom directory and merge your customizations into it. |
| Any Administrator Settings Screen | Both the setting name and value are squeezed into the first cell of each row | (No error in logs) | If you have customized setting.jsp, copy the new default setting.jsp file into the custom directory and merge your customizations into it. |
| Any Administrator Control Screen | Clicking the control screen links from the left hand menu do not clear the control screen parameters. | (No error in logs) | If you have customized the Struts action mappings for any control screen, you must change the "scope" attribute to "request". |
| Any Administrator Screen | Blank screen. | Error - Tag Insert : No value found for attribute 'breadcrumbs'. | If one of your custom JSP files includes a tiles:insert tag for "breadcrumbs", remove it. Breadcrumbs are produced globally now and need not be included by each JSP file. |
| Any Administrator Screen | Blank screen. | Error - Tag Insert : No value found for attribute 'links'. | If one of your custom JSP files includes a tiles:insert tag for "links", remove it. Links are produced globally now and need not be included by each JSP file. |
| Any Administrator Screen | Blank screen. | Error - Tag Insert : No value found for attribute 'heading'. | If one of your custom JSP files includes a tiles:insert tag for "heading", remove it. Links are produced globally now and need not be included by each JSP file. |
| Any Administrator Screen | Breadcrumbing links don't work. | (No error in logs) | Breadcrumbs are now built more dynamically. If you have customized the Struts actions in the Administrator, you may now be missing needed queries to pull in the parent record of the item being edited. Review the default actions and copy the code blocks that load the parent entity into your custom class. In addition, if you have customized *EditForm.jsp, you may need to add the parent's ID to the Delete form. Refer to the new default templates. |
| Product Page or Any Product List Page | Blank screen. | (Various) | Check logs for specific JSP error. If you have customized inventoryAndDiscountSettings.jsp, review the new default template. |
Numerous interface changes have been made to the application's API to support new features. While the specific changes are too numerous to outline here, the follow areas are where most of the changes took place. If you have created your own custom Java classes please take note. If you have created an implementation of any of the interfaces, we recommend deploying the upgrade to a development environment first and setting aside some time to refactor the code to make it conform to the changes.
- The signature for the
setPropertiesmethod ofcom.softslate.commerce.administrator.core.BaseSerializableFormhas changed to require one argument of typeHttpServletRequest. Add the request object to this method call in any custom action class you have created for the Administrator. - Implementations of
com.softslate.commerce.businessobjects.order.Ordermust now implementCollection getEstimatedShippingOptions()andvoid setEstimatedShippingOptions(Collection options). - Implementations of
com.softslate.commerce.businessobjects.core.Userno longer need to implementMap getDynamicShippingOptions()norvoid setDynamicShippingOptions(Map options) - Most of the Processors under
com.softslate.commerce.businessobjectshave had some method signatures updated so that return Maps instead of void. - Other interface changes took place within
com.softslate.commerce.businessobjects.product.Manufacturer,com.softslate.commerce.businessobjects.order.OrderItem,com.softslate.commerce.businessobjects.order.OrderItemAttribute,com.softslate.commerce.businessobjects.order.OrderDiscount,com.softslate.commerce.businessobjects.product.Discount, and other classes. Please deploy the upgrade to a development environment first if you have made extensive customizations.