WebSphere Commerce Portal integration architecture
WebSphere Commerce supports multiple presentations layers.
For example, if your business processes are represented by WebSphere Commerce business logic and data, then Struts is an appropriate choice for your presentation layer.
If you want to aggregate business processes from WebSphere Commerce with those from other (not WebSphere Commerce) applications, then it is appropriate to use WebSphere Portal for the presentation layer.
Both the Struts and WebSphere Portal presentation layers follow the model view controller (MVC) design pattern. The consequent separation of the presentation logic and the business logic enables a Web designer to develop the presentation layer at the same time as an application developer implements business logic.
In the Struts framework, a browser request is routed to a servlet that acts as a controller. Using local Java calls, the controller calls the model for processing. The controller then dispatches the appropriate view to render data. The model encapsulates all business logic implemented using the command pattern. The JSP pages retrieve data from the database using data beans, then format the output.
In the WebSphere Portal framework, the browser request is routed to a portlet that acts as a controller. The portlet calls client libraries (Java classes). The client library sends a service request to WebSphere Commerce business logic for processing. When the portlet renders the data, it dispatches it to a JSP page in the portlet container. The JSP pages use tags that delegate to the client libraries to retrieve data from the WebSphere Commerce system.
Samples are provided to demonstrated how to use portlets with WebSphere Commerce.
WebSphere Commerce and WebSphere Portal integration framework
WebSphere Commerce has provided an optional integration framework intended to reduce development effort when calling WebSphere Commerce services from your portlet. You do not need to use the framework to make use of the client libraries and the WebSphere Commerce foundation tag library in your portlet. The following diagram depicts the interactions between the key pieces of WebSphere Commerce Server and WebSphere Portal Server:
The following section briefly describes each of the key pieces of the framework:
Portlet
A portlet is similar to a servlet, except that it has parts that contribute to the MVC design pattern. MVCPortlet is a generic implementation of the MVC pattern that allows portal administrators to set up one or more portlets, each with its own configuration, to call various WebSphere Commerce business services.
Portlets have multiple states and view modes, as well as event and messaging capabilities. Portlets run inside the Portlet Container of the WebSphere Portal Server, similar to the way a servlet runs on an application server. The portlet container provides a runtime environment where portlets are instantiated, used, and then destroyed. Portlets rely on the WebSphere Portal infrastructure to...
- access user profile information
- participate in window and action events
- communicate with other portlets
- access remote content
- look up credentials
- store persistent data
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 that are packaged as part of the WebSphere Commerce Portlet application. You can find these files on the file system after you install the portlet application to the WebSphere Portal Server.
Event Handlers
Portlets and servlets have different processing and rendering sequences. A servlet does all of its processing in the service() method. A portlet, on the other hand, uses a two-phase processing that is split between an action phase and a render phase. This split is necessary to accommodate communication between portlets before rendering output in the service stage. The action phase is guaranteed to be completed before a portlet is called to render.
The WebSphere Commerce and WebSphere Portal integration framework is designed so that each portlet request can be handled differently using an event handler. For each action event and render event, you can define a corresponding event handler in the portlet MVC configuration file.
Although the render phase is always called, the action phase may not be called in certain circumstances.
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 as well as maintaining a consistent behavior across all WebSphere Commerce portlet events.
Similar to the way WebSphere Commerce resolves any given URL controller command from the Struts configuration file, an action name is used as the unique identifier for looking up the corresponding action definition from an MVC configuration file.
- If the action is found, then the class name defined in the parameter attribute,
such as...
-
com.ibm.commerce.foundation.client.portal.handlers.MVCPortletActionHandler
...is loaded and its execute() method is called.
- Once the action phase is completed, the WebSphere Portal server will redirect the request to the render phase, using the render name defined in the MVC configuration file or from a parameter defined in the action request.
- If no action is found, the action handler will simply take its input parameters
and set them as render parameters. This is a typical scenario of a portlet
refresh triggered by a cooperative portlet wire where only the render name
is given. In general, for best practice programming, if a portlet only needs
to be refreshed and its action phase is not required, then IBM recommends
to use the tag...
-
<portlet:renderURL>
...on the JSP instead to avoid an action request.
A similar idea applies to the portlet render request. The render name is used as the unique identifier for looking up the corresponding render definition from the MVC configuration file. If none is found, then the fallback render definition (with the "default" name) is used. (Even if there is a render definition for this given name, it is optional to have a view defined for each portlet mode.) In addition, the portlet developer can override the render behavior by specifying a different render name in the portlet request URL. Add "renderName" to the parameter list for overriding the name of the renderer.
Portlet Action Handler
This handler...
-
com.ibm.commerce.foundation.client.portal.handlers.MVCPortletActionHandler
...retrieves two properties...
- clientLibrary
- clientMethod
...and then calls the method, passing a parameter map that is composed of name-value pairs given in the URL.
When the client library returns a response, this handler takes the response name-value pair that was returned from the client library and adds it to the URL as render parameters so that the context and core business data are not lost in an event of a page refresh. A page refresh issued from the portlet container does not involve processAction(), so certain business data might be lost as a result of a refresh request.
Portlet Render Handler
The render generic handler...
-
com.ibm.commerce.foundation.client.portal.handlers.MVCPortletRenderHandler
...does not call WebSphere Commerce services. Instead, it simply checks for the current state and mode of the portlet to determine the appropriate JSP file path to be used when calling the request dispatcher for rendering.
Portlet JSP file
The Portlet JSP file is a view template for displaying business data and getting inputs from the portal user. Special UI tags, such as Portlet tags and WebSphere Commerce foundation 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 portal environment, whereas WebSphere Commerce foundation tag library tags are for retrieving populated service data objects from WebSphere Commerce services.
Client library
A client library is a WebSphere Commerce Component Service interface for client side invocation. Client libraries should not be aware of any artifacts specific to WebSphere Portal, such as Portlet Session and Credential Service Vault. Upon each invocation, business objects, such as BusinessContextType and AuthenticationCallbackHandler, are passed to the interface so that it can hand over specific information to the service binding layer.
WebSphere Commerce foundation tag library
A getData tag is provided as part of the WebSphere Commerce UI Runtime. It retrieves populated service data objects from WebSphere Commerce services.
WebSphere Commerce and WebSphere Portal integration framework interaction
Use the WebSphere Commerce Portlet provided, a portlet developer can create or remove actions and renders through configurations. The following description summarizes the interactions:
- The request from the WebSphere Portal user is directed to the Presentation Layer (Portlet container) in the WebSphere Portal Server.
- The Portlet Container then calls the processAction() method in the WebSphere Commerce Portlet where the definition of the requested action is looked up from the MVC configuration stored in the Configuration Registry.
- The designated PortletActionHandler for this portlet action retrieves the client library interface definition and the required parameters from the Configuration Registry.
- The PortletActionHandler gathers the parameter map from the request, along with the required business context and authentication callback handler (which can be acquired through the credential plug-in), and passes them to the pre-configured client library method defined in the Configuration Registry.
- The client library retrieves the required request parameters from the
parameter map and converts them into a message which is then forwarded to
a WebSphere Commerce service on WebSphere Commerce Server. The designated
WebSphere Commerce component performs the requested business operation and,
after the operation is completed, a response is returned to the client library.
The PortletActionHandler analyzes the response and generates the required render parameters, including the context Id for future references to the context object and authentication callback handler in the session, and all properties defined in the response parameter map, for the upcoming render request. In the event of an exception or service fault received from the client library, the PortletActionHandler displays the error view.
- The Portlet Container generates another render request and calls the render() method in the WebSphere Commerce Portlet for rendering a page back to the WebSphere Portal user. The Portlet Container calls the MVCPortlet's render() method where the definition of the requested render will be looked up from the MVC configuration stored in the Configuration Registry.
- The designated PortletRenderHandler retrieves the JSP file path from the Configuration Registry and assigns the portlet JSP page to the request dispatcher for rendering.
- The JSP file retrieves data from the WebSphere Commerce tag library.
- The WebSphere Commerce tag library calls the client library.