Using the provided WebSphere Commerce MVCPortlet class (MVC style)

The WebSphere Commerce Portlet, MVCPortlet, is a generic implementation of the MVC pattern. It allows you to set up one or more portlets, each with its own configuration, to call various WebSphere Commerce services. The goal of this MVCPortlet is to cleanly separate the model (application logic that interacts with a database) from the view (HTML pages that are presented to the client) and the controller (instance that passes information between view and model). This programming pattern greatly reduces code redundancy and maintains a consistent behavior across all WebSphere Commerce portlet actions.
The following is a high-level overview of what the MVCPortlet controller does upon an action request. It mainly consists of going through the following three stages:
  1. Validation

    Performs a general validation of parameters that are used for this portlet action request.

    The following is a list of mandatory things that are currently performed as part of this validation:
    • Scans for cross site scripting violations. Checks if all parameter names and their corresponding values are safe from cross site scripting.
  2. Execution
    Invokes the logic for handling this portlet action request:
    • Captures all request parameters and transfers to the upcoming render request as render parameters. Exceptions are parameters that are named actionName or a name that starts with com.ibm.portal.propertybroker.action.
    • Determines whether a session is required for processing the action request, using the action definition in the portlet-config.xml file.
    • Checks whether another action is required to be executed before this action processes. To define a pre-action operation, a set-property named preActionName must be declared along with the action definition in the portlet-config.xml file.
    • Determines the renderName to be used for the upcoming render request in the following order:
      1. Use the render name if renderName is specified in the request.
      2. Use the default render name that is defined along with the action definition in the portlet-config.xml file.
      3. Use the action name as the render name.
    • Loads from the portlet session the business context object and the callback handler object for use when calls are made into client library. A new object is created if one does not exist in the session or a session is not available at the time of this operation.
    • Executes the action class by calling into the execute() method using Java reflection.
    • Checks if another action is required to be executed after this action is processed. To define a post-action operation, a set-property named postActionName must be declared along with the action definition in the portlet-config.xml file.
    • If an error occurs during the execution of this method, a PortletException is expected to be thrown. This PortletException is a wrapper of the original exception that causes the error condition.
    Notice that the result returned through action chaining is not available as part of the main response.
  3. Compensation

    Handles exceptions that are generated as a result of executing this portlet action request.

    This handler inspects the exception type and determines:
    • If it is an instance of InvocationTargetException and AbstractBusinessObjectDocumentException. The error code and error message can either be retrieved from the ChangeStatusType for server-side errors, or the ClientError for client-side errors.
    • In addition, the exception can also be of type AbstractApplicationException and AbstractSystemException, such as MVCPortletApplicationException and MVCPortletSystemException. These exceptions are generic application-level exceptions that can be handled by the MVCPortlet.
    • Otherwise, all other exceptions are treated as unknown exceptions and are wrapped by PortletException to be thrown again from the MVC portlet.
    The error message object of this exception can be found in the request attribute name, MVCPortletConstants.REQUEST_ATTRIBUTE_SERVICE_FAULT. This error object could either be of:
    • ChangeStatusType for server-side errors.
    • ClientError list for client-side errors, or
    • ApplicationError list for client-side errors.
    • MVCPortletApplicationException for generic application-level exceptions from the MVCPortlet.
    • MVCPortletSystemException for generic system-level exceptions from the MVCPortlet.
    • Throwable for general exceptions.

    Once the exception is classified, the final step is to determine which render to be used for displaying upon this exception event. If faultRenderName is passed in, this render name is used as the renderer for this request. Otherwise, the handler tries to look up the MVC configuration registry for the default render name for this action request. However, if no match is found, then the last alternative is to reuse the action name as the render name.

When a render request is received, the MVCPortlet controller performs the following tasks:
  1. Checks if a renderName is provided. If not, the fallback default render name is used instead.
  2. Determines whether a session is required for processing the render request, using the render definition in the portlet-config.xml file.
  3. Checks if another render operation is required to be executed before this render is processed. To define a pre-render operation, a set-property named preRenderName must be declared along with the render definition in the portlet-config.xml file.
  4. Loads from the portlet session the business context object and the callback handler object for use when calls are made into the client library. A new object is created if one does not exist in the session or a session is not available at the time of this operation. These objects are made available for the getData tag on the JSP through an internal request attributes.
  5. Executes the render class using Java reflection.
  6. Checks if another render operation is required to be executed after this render process completes. To define a post-render operation, a set-property with name postRenderName must be declared along with the given render definition in the portlet-config.xml file.
There is no implicit validation performed in this render phase. Validation is only performed in action requests.

Portlet Action and Render Configuration

Each portlet can have one or more MVC configuration files and they are loaded in the order that is specified in the portlet deployment descriptor. In each MVC configuration file, an action definition is required to define how the request can be mapped out into a WebSphere Commerce service request. A render definition might also be required, depending on the nature of the request. For more information, see Portlet configuration file syntax.

Portlet JSP file

The Portlet JSP file is a view template for displaying business data and getting inputs from the portal user. These JSP files contain markup tags that provide a consistent, clean, and complete user interface. The portal page is displayed using skins and themes that are defined by the portal designer or administrator. For portlets to appear integrated with an organization's portal or user's customized portal, they should generate markup. This markup must invoke the generic style classes for portlets, rather than using tags or attributes to specify colors, fonts, or other visual elements.

Portlets are allowed to render only markup fragments, which are then assembled by the portlet framework for a complete page. Portlet output should contain complete, well-structured, and valid markup fragments. This output helps to prevent the portlet's HTML code, for example, from corrupting the portal's aggregated HTML code.

For more information about the JSP coding guidelines for JSR 168 portlet API, see Markup guidelines.

WebSphere Commerce foundation tag library

A <wcf:getData> action tag is provided as part of the WebSphere Commerce foundation tag library. This tag retrieves populated service data objects from the WebSphere Commerce services. For more information, see Tag: getData.

Client Library

Each WebSphere Commerce service module provides a client library that is responsible for building the messages to be sent to the WebSphere Commerce services. Upon each invocation, business objects, such as BusinessContextType and AuthenticatoinCallbackHandler, are passed to the interface so that it can hand over specific information to the service binding layer.

For more information, see Client library for WebSphere Commerce services.

WebSphere Commerce services

WebSphere Commerce provides services that are created with existing WebSphere Commerce controller commands and data beans, fronted by a component facade interface. These services can be used on the portlet by using the WebSphere Commerce foundation tag library. For more information, see WebSphere Commerce services.