Develop > Presentation layer > WebSphere Commerce integration with WebSphere Portal > Customize WebSphere Commerce Portal integration > Use the provided WebSphere Commerce MVCPortlet class (MVC style)
WebSphere Commerce MVCPortlet framework
The MVCPortlet framework uses the JSP model 2 architecture to interact with WebSphere Commerce. A Model-View-Controller (MVC) design pattern is used in this architecture to separate presentation from content data. The Model represents the business or database code, the View represents the rendered content on a page, and the Controller determines how a request should be processed by the Model and which View to be used for display.
The goal of this MVCPortlet is to efficiently separate the model, that is the application logic that interacts with a database, from the view, that is the HTML pages presented to the client, and the controller, that is the instance that passes information between view and model. The framework provides the controller class, known as MVCPortlet, and facilitates the writing of JSP file templates for the view. A central portlet-config.xml configuration file is used to bind together model, view and controller.
MVCPortlet is a controller that uses a MVC style portlet-config.xml configuration file to invoke appropriate client libraries provided by WebSphere Commerce. This MVCPortlet invokes the client libraries using an action class called MVCPortletActionHandler. This action class retrieves the parameters from the PortletRequest and the PortletSession and converts these into the values required by the Client Library. Portlet action request is the typical programming pattern for update operations used in this MVCPortlet framework. An event handler class called MVCPortletRenderHandler is used for determining which JSP file template to be used for rendering, based on the render defined in the portlet-config.xml configuration file.
To retrieve additional business data for rendering, the getData tag of the JSTL tag library is provided to issue read operations, that is Get service calls, against the WebSphere Commerce service modules. The result set is a list of data objects that can be used directly on the JSP file. In the MVCPortlet framework programming model, it is not recommended to perform update operations in the render phase.
The MVCPortlet framework is very similar to Struts, with the ability to make service calls to the WebSphere Commerce service modules. A portlet action request is represented as action, similar to the Actions term used in Struts, while a portlet render request is represented as render, which is equivalent to the ActionForwardstring in Struts. The purpose of render is for informing the controller which output page to be used for rendering. For passing information between the model and view, the MVCPortlet framework uses DataObject, or service data object (SDO). JSP file developers who are familiar with JavaBeans can also interpret SDO to be conceptually equivalent and can be used directly on a JSP file.
The following diagram depicts the interactions between the key components of WebSphere Commerce MVCPortlet. A brief description of the key components follows the diagram.
MVCPortlet class
MVCPortlet is a generic implementation of the MVC pattern that allows WebSphere Portal administrators to set up one or more portlets, each with its own configuration, to call various WebSphere Commerce services.
Configuration registry
The portlet configuration registry is a cached version of configurations related to all portlet operations, such as portlet actions and portlet renders. These static configurations are defined in XML files packaged as part of the WebSphere Commerce MVCPortlet application.
Event handlers
The MVCPortlet framework is designed in a flexible way so that each portlet request can be handled differently using an event handler. It is possible to define a corresponding event handler in the portlet MVC configuration file for each action event and render event. Although the MVC configuration allows you to define any customized event handler, the use of two generic event handlers is recommended:
- A generic portlet action handler, MVCPortletActionHandler, which calls client libraries through configurations specified in the MVC configuration file.
- A generic portlet render handler, MVCPortletRenderHandler, which returns the proper portlet JSP page according to the current portlet mode.
This programming pattern greatly reduces code redundancy and maintains consistent behaviors across all WebSphere Commerce portlet events.
Portlet JSP files
The portlet JSP file is a view template for displaying business data and getting inputs from the WebSphere Portal user. Special UI tags, such as portlet tags and getData tags, are used on these pages to avoid inline JSP Java coding. Portlet tags are provided by WebSphere Portal to access information specific to the WebSphere Portal environment, whereas WebSphere Commerce getData tags are used for retrieving populated service data objects from WebSphere Commerce services.
Client libraries
A Client Library is a WebSphere Commerce component service interface for client-side service invocation. Client libraries should not be aware of any artifacts specific to WebSphere Portal, such as portlet session and credential service vault. Business objects, such as BusinessContextType and AuthenticationCallbackHandler, are passed to the interface upon each service invocation, so that it can hand over specific information to the service binding layer.
getData tag expression builders
A getData tag is provided as part of the WebSphere Commerce UI runtime. It retrieves populated service data objects from WebSphere Commerce services. See GetData tag configuration for more information.
MVCPortlet interaction flow
The following interaction diagram illustrates the high-level interaction of the MVCPortlet and the backend component services from the WebSphere Commerce server:
- Portlet container calls into the portlet’s processAction() where the definition of the requested action is looked up from the MVC configuration file stored in the Configuration Registry.
- PortletActionHandler retrieves the Client Library interface definition and required parameters from the Configuration Registry where the name-value pair map from the request, with the required business context and identity token, and can be passed to that configured Client Library method.
- The Client Library converts the given name-value pair map into a request BOD which forwards to the Invocation Service where the message is binded against a service endpoint for transmission to the WebSphere Commerce server.
- The WebSphere Commerce component performs the requested business operations and returns a response BOD back to Invocation Service.
- The Client Library converts the response BOD to a name-value pair map where this response name-value pair map can be returned back to the PortletActionHandler.
- PortletActionHandler analyzes the response and generates required render parameter, including the context ID for future references to the context object and identity token in the session, and all properties defined in the response name-value pair map, for the upcoming render request.
- In the event of an exception or service fault received from the component Client Library, the PortletActionHandler forwards to the generic application error view by providing or overriding the render name using the faultRenderName parameter.
- The portlet container generates another render request into this portlet to display the response page to the user.
- The portlet container, depending on the current portlet mode, calls the portlet’s render() method, where the definition of the requested render is looked up from the MVC configuration file stored in the Configuration Registry.
- PortletRenderHandler retrieves the JSP file path from the Configuration Registry and assigns the specified JSP file to request dispatcher for rendering.
- The portlet container refreshes the content of the WebSphere Commerce portlet by loading the specified JSP file. Data on the portlet page is populated using tag libraries.
- Tag attributes, such as Client Library class name and method name, page size, data object type for the returning objects, and expression builder name, will be used to formulate a Get expression.
- This getData tag invokes the client API using the business context object and identity token from the portlet session.
- The specified Client Library transforms the Get expression into a Get BOD, which is forwarded to the Invocation Service where the message is binded against a service endpoint for transmission to the WebSphere Commerce server.
- The component successfully performs the service and returns Show BOD to Invocation Service.
- The Client Library converts the Show BOD in the response to a java.util.List that contains a list of business objects. These objects are available for use on the portlet JSP file. If there is an error or exception encountered in the process, an empty list is returned and the error message is stored in a request attribute called com.ibm.commerce.foundation.service_fault.