HCL Commerce Struts framework

Struts is a well documented, mature and popular framework for building front ends to Java applications. To address concerns in software applications, it uses a Model-View-Controller (MVC) architecture: The Model represents the business or database code, the View represents the page design code, and the Controller represents the navigational code.

The following diagram depicts the interactions between the key components of the HCL Commerce Web application. A brief description of each key component follows the diagram. HCL Commerce currently uses Struts version 1.1. For general information about Struts, refer to the Struts official home page.

Interactions between the key components of the HCL Commerce Web application

Action servlet

Action servlet is a key controller component that implements the same methods and has the same life cycle as javax.servlet.http.HttpServlet.

As illustrated in steps 1 and 2 of the preceding diagram, the action servlet receives an HTTP request, uses the Struts configuration files to determine the appropriate application module, and routes the request to the module's request processor.

The action servlet is also responsible for initialization and clean-up of resources.

ECActionServlet (com.ibm.commerce.struts.ECActionServlet) is the HCL Commerce extension of the Struts ActionServlet class (org.apache.struts.action.ActionServlet). It provides additional functionality, such as the ability to refresh the Struts configuration without restarting the Web application, that is required by various HCL Commerce components.

This implementation is defined as the action servlet in the HCL Commerce Web application descriptor and must be used within the HCL Commerce Web application.

Request processor

Having received an HTTP request from the action servlet, the request processor, another key controller component, performs core request processing as follows:

  1. Determines a number of request characteristics, such as locale and content type, necessary for further processing.
  2. Uses the module's Struts configuration file to determine the configured action mapping for the request.
  3. Uses the module's Struts configuration file to locate or instantiate an appropriate action form for the request, if necessary, and populates and validates it.
  4. Uses the module's Struts configuration file to locate or instantiate an appropriate action for the request.
  5. Passes the request, action form, and action mapping to the action (step 3 in the preceding diagram).
  6. Forwards the user to the appropriate view element when the action is completed (step 6 in the preceding diagram).

By default, HCL Commerce is configured to use the standard request processor implementation provided by the Struts framework. Because it does not require a custom implementation, the HCL Commerce Web application can exploit any specialized request processor, such as one required for Tiles support.


Actions carry out the controller logic for the individual request, such as authorization and session logic, locating and calling the appropriate business (model) logic, and so forth.

Actions bridge an incoming request and the corresponding business logic that should be executed to process it. Actions use action form data to invoke business logic operations on behalf of the client (step 4 in the preceding diagram) and return an ActionForward object that indicates where the controller should forward the user (step 5 in the preceding diagram).

An Action class is created to support each type of request that can be received by the controller.

BaseAction ( com.ibm.commerce.struts.BaseAction) is the HCL Commerce extension of the Struts Action class (org.apache.struts.action.Action). It supplies the functionality that is necessary to invoke HCL Commerce commands based on the action's configuration as provided by the corresponding action mapping. The base action also provide additional callout hooks for the action to be extended to include addition preprocessing and postprocessing logic.

Any custom action that invokes HCL Commerce commands must extend this class.

Action mappings

Action mappings represent the information that the controller knows about the mapping of a particular request to an instance of a particular Action class. The request processor selects an appropriate action for each request based on the action mappings ( action-mapping elements) defined in the Struts configuration file.

The base ActionMapping class extends org.apache.struts.config.ActionConfig, which represents all configuration information provided in an action element of a Struts module configuration file.

ECActionMapping ( com.ibm.commerce.struts.ECActionMapping) is the HCL Commerce extension of the Struts ActionMapping class (org.apache.struts.action.ActionMapping) that allows custom configuration information to be passed to actions of the HCL Commerce Web application. These include both HCL Commerce-specific custom properties and arbitrary additional properties:

  • The https, authenticate, and credentialsAccepted properties are examples of HCL Commerce-specific custom properties. (See Configuring a Web application for examples of setting these properties declaratively.)
  • Arbitrary additional properties can be passed to instances of the action classes based on the BaseAction class by setting the property named defaultProperties.
    Note: The defaultProperties property replaces the parameter attribute used in org.apache.struts.action.ActionMapping. In HCL Commerce, the latter is used to supply the name of the interface of the controller command to be used by an action.

To specify a mapping for an instance of the BaseAction class or its descendants, you must use or extend the ECActionMapping class.

Action forms

Action forms are a key view component that is used to transfer information between the view and the controller-model pair.

An ActionForm object is a Java (JavaBeans) representation of HTML form data. As such, it encapsulates form data for easy population and retrieval, supports form data validation, and is reusable.

Input data is transferred to ActionForm objects automatically by the Struts framework.

Beginning with version 1.1, Struts also supports dynamic action forms. These are built-in reusable ActionForm subclasses that can be configured using XML rather than explicitly creating an ActionForm class for each input form. Dynamic action forms allow developers to create action forms declaratively in the Struts configuration file without having to create an ActionForm class for each kind of HTML form or change the class every time the corresponding HTML form is altered.

The Struts framework creates an instance of the DynaActionForm class for each form-bean definition of type DynaActionForm (or its subtype) at run time.

Action forwards

Action forwards, properly considered to be a part of the controller, represent the next Web resource, typically an HTML or JSP page, in the control flow of the application. Returned by an action, an ActionForward object indicates where the request processor should forward the requestor.

ActionForward instances can be explicitly created in an Action class or preconfigured in the Struts configuration file (by means of forward elements within global-forward or action elements) and located at run time.

ECActionForward ( com.ibm.commerce.struts.ECActionForward) is the HCL Commerce extension of the Struts ActionForward class (org.apache.struts.action.ActionForward). Its distinguishing features are as follows:

  • Ability to specify extra, special-purpose forward properties such as resourceClassName
  • Ability to pass a collection of user-defined view properties (and their values) by means of a multi-valued property, named properties, in the form of an HTTP request query string (see Configuring a Web application for examples of setting this and preceding properties declaratively)
  • Ability to execute a view directly (see the ECActionForward class API documentation for details)


Be aware of the following limitations when working with the HCL Commerce Struts framework:
  • Caching is not supported for commands that use AjaxAction. Instead, use an approach that is cache enabled. For example:
    • Use REST services. REST services support server-side caching using dynacache, and client-side caching using cache directives in the response header.
    • Use the BaseAction command. Caching can be used for action commands that only show information, but not cause database updates or changes of state. To generate error information in the AJAX response, pass in a requesttype=ajax parameter as part of the action request.

Struts configuration files

Both the action servlet and request processor rely on Struts configuration files for application-specific component information, allowing for a declarative, rather than programmatic, configuration of a Struts-based Web application.

The Struts configuration file is parsed during action servlet initialization, and a ModuleConfig object is created to represent it at run time.

An application can have a single Struts configuration file (struts-config.xml) or multiple Struts configuration files, defined in the Web application deployment descriptor (by means of init-param elements). By default, HCL Commerce provides multiple Struts configuration files per module, one for definitions, and the other for customizations and migration. Using multiple Struts configuration files is a "best practice", making parallel development easier and configuration less error- and conflict-prone.