WebSphere 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 WebSphere Commerce Web application. A brief description of each key component follows the diagram. For general information about Struts, refer to the Struts official home page.

 

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 WebSphere 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 WebSphere Commerce components.

This implementation is defined as the action servlet in the WebSphere Commerce Web application descriptor and must be used within the WebSphere 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, WebSphere Commerce is configured to use the standard request processor implementation provided by the Struts framework. Because it does not require a custom implementation, the WebSphere Commerce Web application can exploit any specialized request processor, such as one required for Tiles support.

 

Actions

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 WebSphere Commerce extension of the Struts Action class (org.apache.struts.action.Action). It supplies the functionality that is necessary to invoke WebSphere 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 pre and post processing logic.

Any custom action that invokes WebSphere 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 WebSphere Commerce extension of the Struts ActionMapping class (org.apache.struts.action.ActionMapping) that allows custom configuration information to be passed to actions of the WebSphere Commerce Web application. These include both WebSphere Commerce-specific custom properties and arbitrary additional properties:

• The https, authenticate, and credentialsAccepted properties are examples of WebSphere Commerce-specific custom properties. (See Configuring the 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.

  The defaultProperties property replaces the parameter attribute used in org.apache.struts.action.ActionMapping. In WebSphere 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, 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 WebSphere 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 the 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)

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, WebSphere 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.

• Configure a Web application
  All major aspects of a Web application are configured declaratively by means of Struts configuration files.

• Customizing the Web application configuration
  To customize the configuration of your WebSphere Commerce instance, edit the WebSphere Commerce Struts custom configuration files, struts-config-ext.xml, which are included in each of the WebSphere Commerce Web modules. Confining customization to these files, in place of struts-config.xml, will ensure that your customizations are not overwritten during subsequent migration, fix pack installation, and other similar activities.

• Updating the Web application configuration
  You have two options for updating the WebSphere Commerce Struts configuration while the WebSphere Commerce application is running.

• JSP pages and data beans
  A data bean is a Java bean that is used within a JSP page to provide dynamic content. A data bean normally provides a simple representation of a WebSphere Commerce entity bean. The data bean encapsulates properties that can be retrieved from or set within the entity bean. As such, the data bean simplifies the task of incorporating dynamic data into JSP pages.

Related tasks

Configure a Web application
Customizing the Web application configuration
Updating the Web application configuration
Define WebSphere Commerce error message resources: message-resources
Mapping URLs to controller commands: action-mappings
Representing view implementations: action-mappings and global-forwards
Tutorial: Using Struts tags, action forms, and validation
Tutorial: Extending a Struts action