|
|
|
|
|
|
Extending Webflow and Pipelines
Although the BEA WebLogic Commerce Server product provides default Webflow and Pipeline mechanisms that you can customize, the Webflow and Pipelines have also been designed for easy extensibility. For example, if your organizational requirements dictate the use of a new business process, the Java/EJB programmers on your development team can utilize the existing Webflow and Pipeline infrastructure to create and incorporate these components into the system. This topic describes how to accomplish this.
This topic includes the following sections:
Pipeline Sessions
Although Pipelines and their components are reusable, they must relate to a particular customer's experience on your e-commerce site to make their execution relevant. For this reason, Pipeline components always operate on a Pipeline session. This section provides you with information about the Pipeline session, and provides instructions for configuring the Pipeline session to meet your own needs.
What Is a Pipeline Session?
Clearly, it is necessary to keep track of information gathered from your customers and the data modified by Pipeline components as a customer moves through your site. To maintain this state of the business process, the BEA WebLogic Commerce Server product makes use of a Pipeline session. A Pipeline session is an object that is created and stored within the HTTP session, with the goal of providing a single point of communication for all Pipeline components in a given Pipeline. Additionally, Pipeline sessions provide central access and storage for all external classes that may also need to update the Pipeline session.
The Pipeline session is comprised of many name/value pairs called attributes. Pipeline components act on particular attributes that exist within the Pipeline session, and may also add new attributes as necessary.
Attribute Scoping
The Pipeline session provides an API that allows you to add Pipeline session attributes. All attributes in the Pipeline session can have one of two scopes: Pipeline Session scope or Request scope. The method signature for creating Pipeline session attributes is:
public void setAttribute(String key, Object attribute, int scope);
where scope is either PipelineConstants.PIPELINE_SESSION_SCOPE or PipelineConstants.REQUEST_SCOPE.
In the Pipeline Session scope, the attribute exists in the Pipeline session until the end of the current HTTP session. Pipeline Session scope is the default scope for Pipeline session attributes, and will be used if the third parameter to the setAttribute() method is not specified. In the Request scope, the attributes are made available in the HTTPServletRequest, and these attributes should be accessed via the getPipelineProperty JSP tag (that is, the attributes exist only for the life of an HTTP request).
Basically, Pipeline Session and Request scoping differ by how long the attribute is retained. When an attribute is specified with the Request scope, it is available from the time it is set, up to and including the display of the next JSP. The attribute is automatically deleted when a new request starts. Therefore, Request scope is useful for temporary objects that will only be needed for one page. For example, search results from the product catalog are stored as Request-scoped attributes. Attributes that must live longer should be specified as Pipeline Session scope, which will cause them to be retained throughout the customer's session. If you know that a Pipeline session attribute is only required for the current request, use the Request scope.
Note: All attributes added to the Pipeline session should be serializable. If they are not, the server will generate an error when trying to serialize the Pipeline session, and thus no Pipelines will be executed. To assist in debugging, set the pipelineSession.debug property in the weblogiccommerce.properties file to true. Then, when a Pipeline session setAttribute() method is called, the server console will indicate whether the attribute is serializable or not.
Managing the Pipeline Session
It is important that the Pipeline and HTTP sessions are associated with each other and that they are updated in parallel. This section contains information about accessing and storing the Pipeline session that is important to maintaining this relationship.
Accessing the Pipeline Session
It is highly recommended that clients requiring access to the Pipeline session use one of the APIs of the CommerceInputProcessor base class. The CommerceInputProcessor class is responsible for creating a new Pipeline session (if required), and for associating the Pipeline session with the HTTP session.
Note: For more information about CommerceInputProcessor, see The CommerceInputProcessor Base Class.
Storing the Pipeline Session in the HTTP Session
Each time the Pipeline session is updated, the HTTP session also needs to be updated so that the Pipeline session is replicated across all the nodes in a cluster. Because the Webflow infrastructure is responsible for setting the Pipeline session to the HTTP session at appropriate times, it is highly recommended that none of the InputProcessors directly store the Pipeline session in the HTTP session.
Note: For more information about InputProcessors, see Using the InputProcessor Interface.
Extending Input Processors
In addition to using the input processors provided in the BEA WebLogic Commerce Server product, you can create your own input processors. This section describes the conventions you must follow when creating new input processors.
Note: It is expected that a Java/EJB programmer (or someone with similar technical knowledge and abilities) will develop new input processors.
Using the InputProcessor Interface
New input processors must implement the InputProcessor interface and must supply an implementation for the process method. The process method accepts an HTTPServletRequest object as a parameter and returns a string (such as success) if execution is successful, as shown in the following method signature:
public String process (HTTPServletRequest request) throws ProcessingException
Notes: For more information about the InputProcessor interface, see the Javadoc.
For information about how the InputProcessor interface can be used to handle session time outs, see Handling Session Timeouts.
Input Processor Exceptions
All input processors must throw the ProcessingException exception, or one of its subclasses. To obtain the ProcessingException exception's exception message, use the scriptlet shown in Listing 4-1.
Listing 4-1 Obtaining the ProcessingException Exception Message
<% String errorMsg = (String)request.getAttribute(HttpRequestConstants.PIPELINE_MESSAGE); %>
Note: For more information about the ProcessingException exception, see the Javadoc.
The CommerceInputProcessor Base Class
CommerceInputProcessor is the abstract base class for all the BEA WebLogic Commerce Server classes that implement the InputProcessor interface. This class has a number of utility methods for all the derived classes to use, some of which allow you to:
Note: For more information on the CommerceInputProcessor base class, see the Javadoc.
Input Processor Naming Conventions
The name of an input processor should end with the suffix IP. For example, an input processor that is responsible for deleting a shipping address might be called DeleteShippingAddressIP.
Input Processors and Statelessness
Because the Webflow controls the life cycle of input processors, the Webflow may create and destroy input processors without regard for the data that may be contained within them. Therefore, input processors should always be stateless, and it is recommended that you do not define any instance variables in an input processor.
Other Development Guidelines
Execution of business (application) logic should not be done within input processors. Specifically, input processors should not call EJBs or attempt to access a database. All such logic should be implemented in Pipeline components. Although it is possible to execute this logic within an input processor, doing so would defeat the purpose of the Webflow/Pipeline infrastructure and would not easily lend itself to modification.
By separating business logic from the presentation logic, your e-commerce site is inherently flexible in nature. Modifying or adding functionality can be as simple as creating and plugging in new Pipelines and/or input processors.
Extending Pipelines and Pipeline Components
In addition to using the Pipelines and Pipeline components provided in the BEA WebLogic Commerce Server product, you can create your own Pipelines and Pipeline components. This section describes the conventions you must follow when creating new Pipelines and Pipeline components.
Note: It is expected that a Java/EJB programmer (or someone with similar technical knowledge and abilities) will develop new Pipelines and Pipeline components.
Using the PipelineComponent Interface
New Pipeline components must implement the PipelineComponent interface and must supply an implementation for the process method. The process method accepts a PipelineSession object as a parameter, and returns updated PipelineSession objects if the execution is successful, as shown in the following method signature:
public PipelineSession process(PipelineSession session) throws RemoteException, PipelineNonFatalException, PipelineFatalException
Notes: For more information about the PipelineComponent interface, see the Javadoc.
For information about how the PipelineComponent interface can be used to handle session timeouts, see Handling Session Timeouts.
Pipeline Component Exceptions
Pipeline components may throw a PipelineFatalException to signify that the component has failed. When this occurs, no further Pipeline components are executed and if the Pipeline is transactional, the transaction will be rolled back.
To obtain the PipelineFatalException exception's exception message, use the scriptlet shown in Listing 4-2.
Listing 4-2 Obtaining the PipelineFatalException Exception Message
<% String errorMsg = (String)request.getAttribute(HttpRequestConstants.PIPELINE_MESSAGE); %>
Note: For more information about fatal Pipeline exceptions in a transactional Pipeline, see Transactional Versus Nontransactional Pipelines.
Pipeline components may also throw a PipelineNonFatalException to indicate that the component has failed, but that subsequent Pipeline components should be executed. Lastly, a Pipeline component may throw a RemoteException.
The Webflow integrates with these exceptions as follows:
Note: For a detailed description about how Webflow searches transitions, see Webflow Search Order.
When an exception search is performed, the Webflow looks for the exact exception found as the event. If this exception is not found, the Webflow will begin looking through the search order, as decribed in Webflow Search Order.
The CommercePipelineComponent Base Class
CommercePipelineComponent is an abstract base class for all the BEA WebLogic Commerce Server classes that implement the PipelineComponent interface. This class provides a utility method that allows you to obtain database connections from the commercePool (set up in the WebLogic Server console).
Note: For more information about the CommercePipelineComponent base class, see the Javadoc.
Pipeline Component Naming Conventions
The name of a Pipeline component should end with the suffix PC. For example, a Pipeline component that is responsible for saving a shopping cart might be called SaveCartPC.
Implementation of Pipeline Components as Stateless Session EJBs or Java Objects
Pipeline components can be implemented as either stateless session EJBs or as Java objects. Table 4-1 describes the differences between the two implementations.
An implementing class that is a stateless session EJB must meet the following requirements:
Stateful Versus Stateless Pipeline Components
Whether Pipeline components are implemented as stateless session EJBs or as Java objects, Pipeline components themselves should be stateless. The business logic implemented in Pipeline components should only depend upon the PipelineSession object, the database, and other external resources. Should you define any instance variables, static variables, or static initializers within a Pipeline component, the results may be unpredictable.
Transactional Versus Nontransactional Pipelines
If all Pipeline components within the Pipeline will be invoked under one transaction, the respective Pipeline's isTransactional property should be set to true in the Pipeline definition (within pipeline.properties file). Transactional Pipelines provide support for rolling back the database transaction and for making changes to the Pipeline session. If a transactional Pipeline fails, any database operations made by each of its Pipeline components are rolled back.
If a Pipeline component in a transactional Pipeline is implemented as a stateless session EJB, then its transaction attribute must be Required. Also, be sure that each of the Pipeline components in a transactional Pipeline has the correct transaction flag. Transaction flags indicate whether or not each bean will participate in the transaction. If the Pipeline's isTransactional property is true and the participating Pipeline components (beans) have their transaction flag set to never, the Pipeline will fail to execute. Similarly, if the Pipeline's isTransactional property is false and the Pipeline components have the transaction flag set to mandatory, the Pipeline will also fail to execute.
If a Pipeline component in a transactional Pipeline is implemented as a simple Java object, then for all database operations, the Pipeline component must use the Transactional DataSource associated with the connection pool, as defined in the WebLogic Server console. A transactional Pipeline containing Pipeline components implemented as simple Java objects commits the transaction upon success, and rolls back the transaction upon failure.
Other Development Guidelines
All server-side coding guidelines apply for development of new Pipeline components. Specifically:
Handling Session Timeouts
In any Web application, the HttpSession is usually short-lived. Therefore, every time the HttpSession is accessed, it must be evaluated to determine whether the session is new or whether the client has joined the current session. If the session is new and an attempt is made to access the PipelineSession from the HttpSession, then a null value will be returned unless it is recreated. This section describes in more detail how to handle session timeouts using the InputProcessor base classes.
Using the getPipelineSession() Method
The CommerceInputProcessor provides an overloaded getPipelineSession() method to help you handle session timeouts.
The first version of the getPipelineSession() method attempts to get the PipelineSession from the HttpSession. If the method is not able to locate the PipelineSession, then it will create a new instance and return a reference to the PipelineSession, as shown in the following method signature:
public PipelineSession getPipelineSession(HttpServletRequest request)
The second version of the getPipelineSession() method has an extra parameter, checkValidity, as shown in the following method signature. If checkValidity is true and the HttpSession is new, then the getPipelineSession() method throws an InvalidSessionStateException exception.
public PipelineSession getPipelineSession(HttpServletRequest
request, Boolean checkValidity) throws InvalidSessionStateException
Note: For more information about the InvalidSessionStateException exception, see The InvalidSessionStateException Exception in webflow.properties below.
The InvalidSessionStateException Exception in webflow.properties
The InvalidSessionStateException exception can be used for input processors. In the webflow.properties file, you can either provide the input processor name (as shown in the first line of Listing 4-3), or use the wildcard character (as shown in the second line of Listing 4-3).
Listing 4-3 Using InvalidSessionStateException in webflow.properties
InputprocessorName.inputprocessor.exception
(InvalidSessionStateException)= sessiontimeout.jsp
*.inputprocessor.exception(InvalidSessionStateException)=
sessiontimeout.jsp
The second option indicates that all input processors experiencing session timeout (throwing an InvalidSessionStateException) should load the sessiontimeout.jsp file.
Note: For more information about using the wildcard character in the webflow.properties file, see Using the Wildcard Character.
PipelineComponent and Session Timeouts
As part of handling session timeouts, each class that implements the PipelineComponent interface should determine whether or not a required attribute exists in the PipelineSession object. If the attribute does not exist, the subclass should throw an InvalidPipelineSessionStateException exception.
Note: For more information about the InvalidPipelineSessionStateException exception, see The InvalidPipelineSessionStateException Exception in webflow.properites below.
The InvalidPipelineSessionStateException Exception in webflow.properites
The InvalidPipelineSessionStateException exception can be used for Pipelines. In the webflow.properties file, you can either provide the Pipeline name (as shown in the first line of Listing 4-4), or use the wildcard character (as shown in the second line of Listing 4-4).
Listing 4-4 Using InvalidPipelineSessionStateException in webflow.properties
PipelineName.pipeline.exception
(InvalidPipelineSessionStateException)= sessiontimeout.jsp
*.pipeline.exception(InvalidPipelineSessionStateException)=
sessiontimeout.jsp
The second option indicates that all Pipelines experiencing session timeout (throwing an InvalidPipelineSessionStateException) should load the sessiontimeout.jsp file.
Note: For more information about using the wildcard character in the webflow.properties file, see Using the Wildcard Character.
About the sessiontimeout.jsp Template
The sessiontimeout.jsp template (shown in Figure 4-1) that ships with the BEA WebLogic Commerce Server product contains a link that calls the Webflow with the initial state, thereby giving the user a chance to start all over again.
Figure 4-1 The sessiontimeout.jsp Template
|
|
|
|
|
|
Copyright © 2001 BEA Systems, Inc. All rights reserved.
|
