Spring MVC and store controller customization

The model-view-controller (MVC) framework that is used for the store is Spring. Spring is popular, supported, and easy to adopt by developers with previous Struts and HCL Commerce experience. The following information details the store Spring MVC implementation, and details on how to customize actions and views. After customizations are made, respective modifications need to be made to the REST template configurations.

For more information about the Spring framework and its API, see:

The store server implements three controllers to fulfill its functions:

RESTActionController: This component is the core framework controller, which manages the core functions of loading the services and framework configuration, validation of requests and mapping the requests with configured REST actions and runs the actions. Handles traditional page requests. In the store separated environment, it calls the backend REST service to interact with the transaction server to run business logic.
AjaxRESTActionController: Handles Ajax requests. In the store separation environment, it also calls the backend REST service.
ViewController: The controller for the page view. It does not run REST actions according to the REST templates.

Store MVC customization

Since most business logic is handled by the transaction server through REST, extension of methods within the RESTActionController class allows for information to be properly handled and passed on by the store server.

The REST Action controller does the following to communicate with the Transaction server:

Resolves the input parameter which includes decryption of the krypto parameter, and parameter validations.
Converts the input parameter into the REST URL and the JSON string by using the REST template.
Calls the REST API with that REST URL and JSON string.
Processes the response of the REST API, and return to the appropriate view.

Action controllers

Figure 1.

The following example is a URL to controller mapping in the workspace_dir/crs-web/WebContent/WEB-INF/spring/controllers.xml file:

<prop key="1/Logon">2logon</prop>

Note: If store specific customization is needed, a store alias postfix can be used. For example:

<prop key="/Logon/AuroraStorefrontAssetStore">mylogon</prop>

Where the alias is the store directory name as it is set in the database.

1 The key /Logon is the action URL path name for the HTTP request.
2 The element value logon is the name of the controller bean.

Figure 2.

The following example is an action controller bean definition in the workspace_dir/crs-web/WebContent/WEB-INF/spring/member-controllers.xml file:

<bean id="1logon" class="2com.ibm.commerce.store.mvc.controller.spring.LogonController">
<property name="https" value="1"/>
<property name="authenticate" value="0"/>
<property name="credentialsAccepted" value="P"/>
<property name="parameter" value="loginIdentityHandler.logon"/>
<property name="generic" value="1"/></bean>

1 The bean ID logon must match the value in the prop element in the URL-to-bean mapping.
2 The class LogonController is the bean class.
The property elements are the HTTP request properties for the action.

Each default action controller is of class RESTActionController or its extension (such as LogonController), and each action calls one REST service for processing business logic.

The following HTTP request properties are supported by actions:

https: Specifies whether the request needs HTTPS redirection when it is sent in HTTP. The value of 1 indicates that the request was expected to be received on a secure channel (HTTPS) and a redirect to the SSL port is issued if it is received on an insecure channel (HTTP).
credentialsAcceped: Specifies whether the request allows partial credential. A value of P indicates that partially authenticated users are entitled to access this resource. Partially authenticated users are those users that are logged off, but in a remembered user state. That is, when rememberMe is set to true for the Logoff command.
generic: Specifies whether the request allows generic users to call it. A value of 1 indicates that the request allows generic execution and a guest user does not get created.
authenticate: Specifies whether the request can only be called by registered users. A value of 1 indicates that user logon is required for this URI. Only non-guest, non-generic users are allowed to access pages with this property set to 1.
csrfProtected: Specifies whether the request is CSRF protected. A value of 1 indicates enabling cross-site request forgery protection for this request.
parameter: The name of the REST service to call. The corresponding REST services are defined in the REST templates, located in workspace_dir/crs-web/WebContent/WEB-INF/xml/config/com.ibm.commerce.component_name/rest-template-config.xml.

View controllers

Figure 3.

The following example is a URL to a view controller mapping in the controllers.xml file:

<prop key="1/CategoryDisplay">2browsingController</prop>
<prop key="/TopCategoriesDisplay">browsingController</prop>
<prop key="*">viewController</prop>

1 The key /CategoryDisplay is the action URL path name for the HTTP request.
2 The element value browsingController is the name of the controller bean.
Two kinds of controllers are used to check security and retrieve spring view objects (ModelAndView Object):
- browsingController for the catalog-related views: CategoryDisplay and TopCategoriesDisplay. The browsingController contains logic to retrieve and save request parameters (catelogId, categoryId, productId) during the pre-process stage, and set those parameters to HTTP requests during the post-process stage.
- viewController for ordinary views.
The controllers do contain common behavior, such as running services with different pre-process and post-process actions, as defined in the AbstractWebControllerExecutor.preprocess and postprocess methods. The following chain of commands is used:
- For pre-process: Request parameters > White list > Cross-site scripts > Login timeout > CSRF > Authentication > HTTPS redirection > Partial credentials > Non-generic request
- For post-process: Response parameters > Persistent cookies update > Session update
Note: While the following code snippets show the viewController definitions in the views XML files, the browsingController logic is defined in the com.ibm.commerce.store.mvc.controller.spring.BrowsingViewController class.

Figure 4.

The following example is a view controller bean definition in the workspace_dir/crs-web/WebContent/WEB-INF/spring/order-views.xml file:

<bean 1id="AjaxOrderItemDisplayView/2-21" 3class="com.ibm.commerce.store.mvc.view.spring.StoreInternalResourceView">
<property 4name="url" value="/mobile30/ShoppingArea/ShopcartSection/OrderItemDisplay.jsp"/>
<property name="https" value="1"/>
<property name="credentialsAccepted" value="P"/>
<property name="generic" value="1"/>
</bean>

1 The bean ID AjaxOrderItemDisplayView corresponds to the URL path name without forward slash.
2 Optional: The device ID /-21 indicates that this view controller is the mobile version of the view controller. If a mobile device is detected through the browser user-agent, then the /-21 version is used to return the appropriate view.
Note:
- The device ID is only required if the controller is shared between two or more device types. For example, if differences exist between a desktop and mobile version of AjaxOrderItemDisplayView. If the view controller is device type specific, then it is not required. For example, if the view controller is mobile-only, then /-21 can be omitted.
- Device IDs are not customizable. The only device ID that is active is /-21, and is mapped to device browsers that match Android or iOS devices.
3 The class attribute com.ibm.commerce.store.mvc.view.spring.StoreInternalResourceView is the implementation of the Spring Java standard tag library (JSTL) view.
4 The url property value /mobile30/ShoppingArea/ShopcartSection/OrderItemDisplay.jsp is the forward location of the view.

The additional property elements are the HTTP request properties for this view. The following HTTP request properties are supported by views:

https: Whether the request needs HTTPS redirection when it is sent in HTTP. The value of 1 indicates that the request was expected to be received on a secure channel (HTTPS) and a redirect to the SSL port is issued if it is received on an insecure channel (HTTP).
credentialsAcceped: Specifies whether the request allows partial credential. A value of P indicates that partially authenticated users are entitled to access this resource. Partially authenticated users are those users that are logged off, but in a remembered user state. That is, when rememberMe is set to true for the Logoff command.
generic: Specifies whether the request allows generic users to call it. A value of 0 indicates that the request does not allow generic execution and a guest user is created automatically when the request is sent in generic.
authenticate: Specifies whether the request can only be called by registered users. A value of 1 indicates that user logon is required for this URI. Only non-guest, non-generic users are allowed to access pages with this property set to 1.
csrfProtected: Specifies whether the request is CSRF protected. A value of 1 indicates enabling cross-site request forgery protection for this request.
storeDir: Specifies whether the forward location should be appended after the store-specific directory. The value no indicates that this URL is relative to the store directory. All other values, or if left unspecified, means that the URL path is relative to the root JavaServer Page file (JSP file) directory.
skipAccessControlCheck: Specifies whether this view is checked against the view access control policies that are configured in the database. A value of 1 means that access control is not checked for this view. This option is provided by customers for adding new views. By default, views are checked for their access control. To load access control policies into the database for new views, see Loading access control policy data.
targetServletName: The target servlet name for the JavaServer Page (JSP). This property is used for locating views across different web archives (WAR).