Business Flow Strategy | Web Application | Component Object Model

Business Flow UI Strategy

1. Overview
Starting in phase 3, the UI must access the APIs via Business Flow. A business flow engine has been developed that takes configuration files that allow the order and number of API calls to be configurable for each flow. This document describes the common UI code that has been developed to make use of Business Flow and provides additional information on the overall strategy for combining classes in the web flow (via the struts-config file) to make use of business flow.

2. Business Flow Constants
BFConstants.java holds constants used by the common business flow classes for session keys, request keys and error handling. For example, the session key to obtain the session state object resides in this file. \\revcs\devref\Concorde\webapp\admin\WEBINF\classes\com\dstsystems\concorde\presentation\admin\commonModules\bf\web\common\BFConstants. java This class is not intended to hold all of the flow name and session variable name constants. A file exists in the business package to hold all of these constants for the enterprise. \\revcs\devref\Concorde\com\dstsystems\concorde\business\BusinessFlowConstants.java

3. ActionForm Classes
ActionForms should follow the same basic strategy as previously implemented.  ActionForms should contain one or more DTOs that are copies of those on the session state.  No additional getters and setters should be required in the ActionForm except for fields where extra conversions or validation must be done (i.e. dates, immutable fields).  The validate method in the ActionForm should call the validate method on the DTO. This strategy assumes that the DTOs are implemented in the following manner:  None of the getters and setters in the DTO should throw exceptions or do any validation.  All validation should be done in the validate method in the DTO.  When a setter method is called on the DTO, the DTO creates a snapshot if necessary. This way the snapshots are only created once and only when needed. The clients will not have to worry about when to make snapshots and they do not have to be created on the application tier. Basic field level validations (e.g. numeric only fields) should still be performed in the JSPs.

4. Action Classes
Common code has been developed that handles all interactions with Business Flow. The following action classes are now in PVCS in the following location: \\revcs\devref\Concorde\webapp\admin\WEBINF\classes\com\dstsystems\concorde\presentation\admin\commonModules\bf\web\frontController

4.1.

InvokeBusinessFlowAction

This class will invoke the business flow with the flowName (BFConstants. FLOW_NAME_REQUEST_KEY) sent on the request. It handles all interaction with the Business Flow business delegate. It obtains the session state object from the session and places the updated session state back on the session after the call is complete. If the business flow call fails, nothing is saved on the session state. It is up to the developer to make sure that the session state is cleaned up at the appropriate times.

9/3/2010

Page 1 of 6

4.2.

Subclasses of InvokeBusinessFlowAction

Various classes have been created to allow the appropriate error message to be supplied if a business flow error occurs. Some common error messages have been identified that will be used across all components for flows that perform functionality like retrieving summary information (e.g. for list screens), retrieving detailed information (e.g. for the add/modify entity screens), saving information, finding information, etc. These common behaviors each have a subclass that defines the error message for that action. The following classes currently exist:  InvokeFindBusinessFlowAction – used when invoking a business flow call that performs a search for information that is initiated by the user pressing a Find button.  InvokeRetrieveDetailBusinessFlowAction – used when invoking a business flow that retrieves the detailed information about an entity. This would usually occur when the user selects to Modify or View an entity.  InvokeRetrieveSummaryBusinessFlowAction – used when invoking a business flow that retrieves summary level data or initializes a screen. This should be used for calls to obtain data for list screens or for initialization of an entry point.  InvokeSaveBusinessFlowAction – used when invoking a business flow to save the modified information. Using this type of action requires two forward paths: success and ghost_update. If the save fails due to a GhostUpdateChainedException, then you will often need to forward to a different path to retrieve the data again.  InvokeValidateBusinessFlowAction – used when invoking a business flow that calls an API that performs validation only. If additional types of flows that are component specific are needed, the InvokeBusinessFlowAction should be subclassed in the component’s FrontController package to provide the correct error message. Component specific subclasses should not be placed in the commonModules packages.

5. Session State
The session state resides on the session under the BFConstants.SESSION_STATE_KEY. The session state should be kept pure, meaning that only data retrieved from the application tier or data that has been validated locally should be placed on the session state. Do not update a DTO on the session state directly until it has been validated. The following action classes manage the session state and are now in PVCS in the following location: \\revcs\devref\Concorde\webapp\admin\WEBINF\classes\com\dstsystems\concorde\presentation\admin\commonModules\bf\web\frontController

5.1.

InitializeSessionStateAction

This class is used to create the session state object and place it on the session. This action should be one of the first actions in the chain for initialization of an entry point in the application.

5.2.

UpdateSessionStateAction

This common class updates the session state object with one or more key/value pairs specified on the request. It should only be used for values that are of types that can be fully constructed using a String. For example, setting the retailer ID as a java.util.Long is possible since a Long can be instantiated by passing in a String value. For more complex updates where the object can’t be constructed with a String argument, custom Update actions must be written for each component.  The dataKey (BFConstants.DATA_KEY_REQUEST_KEY) specifies the key(s) to be updated in the hash map in the session state.  The dataValue (BFConstants.DATA_VALUE_REQUEST_KEY) specifies the value(s) to be stored. The value is sent as a string representation of the value.  The dataType (BFConstants.DATA_TYPE_REQUEST_KEY) specifies the type(s) of the value to be stored. The type is the fully qualified name of the class to be created. The class must have a constructor that takes a string since the UpdateSessionStateAction will 9/3/2010 Page 2 of 6

attempt to construct an instance of the object with the dataValue and place it on the session state. Multiple values may be passed when separated by a semicolon (BFConstants.DATA_DELIM_REQUEST_KEY). For example, you could pass the following on the request:  dataKey=retailerId;retailerName  dataValue=1;DIRECTV  dataType=java.util.Long;java.lang.String Values may be removed from the session state using this class as well. If only the dataKey is specified with no dataValue or dataType, the entry or entries associated with dataKey will be deleted.

6. Basic Flow
Struts actions will continue to be chained together to perform the required steps needed for many situations. By writing the actions as small units of work, it is easier to reuse the actions and to insert new ones into the flow. In general, the flow is as follows: Update Session State  Invoke Business Flow  Populate or Format Data  Display JSP

6.1.

Update Session State

In general there will be an Update action that updates (or creates) key/value pairs on the session state for the arguments needed by the API or APIs that will be called by the Business Flow. Custom Update action may be written to accomplish this or the common UpdateSessionStateAction may be used and the values passed in on the request. There are two kinds of Update actions: 1. Updates for retrieving data – These typically have the word “Criteria” in the name, indicating that they are for updating the session state with arguments used to retrieve data. For example: UpdateMessageCriteriaAction is used when the user selects to find messages. This type of Update action may handles caching of data by adding logic that checks for the existence of the desired data on the session state and forwards to the Invoke Business Flow action only if the call is needed. Otherwise it forwards directly to the Populate/Format action. Often, the first thing this class does is to cleanup any session and session state data from previous calls. 2. Updates for saving data – These updates place modified data on the session to be saved by the next call to invoke a business flow. An example is UpdateMessageAction. This type of Update action takes the DTO from the ActionForm and checks to see if it isNew or isModified. If changes have been made, it forwards to the Invoke Business Flow path, otherwise it terminates the flow and returns to a known state, indicating that no changes were saved on the status bar if needed.

6.2.

Invoke Business Flow

After a successful Update, the appropriate Invoke business flow subclass is called based on the type of action being performed. Each action forwards to a “success” path if the business flow does not throw any exceptions. If the business flow performs a save or any type of update to the database, there is a possibility that a ghost update could have occurred. As a result, when using InvokeSaveBusinessFlowAction, you need an additional path (“ghost_update”) to handle the ghost updates behavior.

9/3/2010

Page 3 of 6

6.3.

Populate/Format Data

After a successful business flow call, the appropriate Populate and/or Format actions are executed to format the data before the JSP is displayed. The Populate action retrieves the returned data from the session state and places form field data on the form along with the DTO(s) that represent the data on the screen. The Format action retrieves the returned data from the session state and formats it for display in by the table or tree applet. Format actions are only required when the JSP contains an applet.

6.4.

Examples

The following are examples of some basic chains using business flow:

6.4.1.

Search Functionality

This sequence of action mapping would be invoked when the Find button is pressed on a Find screen 1. Update the session state with the search criteria from the form. Uses a custom Update action. 2. Call InvokeFindBusinessFlowAction, sending in the flowName as a request parameter. This should be passed in the struts config as part of the forward of the previous action. 3. Call the appropriate Format action to format the results into a table and then forward to the find screen. The following is a sample struts-config mapping for the find functionality:
<!-- find_message.do: Update the session state with the search criteria data. --> <action path="/find_message"

type="com.dstsystems.concorde.presentation.admin.ccg.web.frontController.UpdateMessageCriteri aAction" name="findMessagesActionForm" scope="session" validate="false" input="/ccg/find_message_main.jsp"> <forward name="success" path="/invoke_get_messages.do?flowName=CCG_getMessages" /> </action> <!-- invoke_get_messages.do - Execute a search given the entered criteria. --> <action path="/invoke_get_messages"

type="com.dstsystems.concorde.presentation.admin.commonModules.bf.web.frontController.InvokeFindBu sinessFlowAction" name="findMessagesActionForm" scope="session" validate="false" input="/ccg/find_message_main.jsp" > <forward name="success" path="/format_message_results.do" /> </action> <!-- format_message_results.do - Format the results table with the list of messages. --> <action path="/format_message_results" type="com.dstsystems.concorde.presentation.admin.ccg.web.frontController.FormatMessagesAction" name="findMessagesActionForm" scope="session" validate="false" input="/ccg/find_message_main.jsp" > <forward name="success" path="/ccg/find_message_main.jsp"/> </action>

9/3/2010

Page 4 of 6

6.4.2.

Add/Modify/Copy/View Entity Functionality

This sequence of action mappings would be invoked when the Add, Modify, Copy or View buttons are pressed to cause the complete details of an entity to be displayed in a secondary window or in the workspace of the primary window. 1. Update the session state with the ID of the entity for which the details are to be displayed. Use a custom Update action or use the common UpdateSessionStateAction depending upon the complexity of the update. 2. Call InvokeRetrieveDetailsBusinessFlowAction sending the flowName as a request parameter. This should be passed in the struts-config as part of the forward of the previous action. 3. Call the appropriate custom Populate action to populate the ActionForm for the secondary window with the returned data from the session state and then forward to the JSP. The following is an example of the struts-config mapping for this type of action:
<!-- display_message_details.do: Triggered by selecting the Modify, Copy or View buttons. Updates the session state in preparation for the business flow call to retrieve the detail, invokes the business flow call to get the detail, and then populates the screen with the detail needed for the copy, modify or view action. --> <action path="/display_message_details" type="com.dstsystems.concorde.presentation.admin.commonModules.bf.web.frontController.U pdateSessionStateAction" name="messageActionForm" scope="session" validate="false" input="/close_modal.jsp? returnValue=1"> <forward name="success" path="/invoke_retrieve_message_details.do? flowName=getCustomerCommunicationMessage"/> </action> <!-- invoke_retrieve_message_details.do: Gets the message details --> <action path="/invoke_retrieve_message_details" type="com.dstsystems.concorde.presentation.admin.commonModules.bf.web.frontController.Invo keRetrieveDetailBusinessFlowAction" name="messageActionForm" scope="session" validate="false" input="/close_modal.jsp? returnValue=1"> <forward name="success" path="/populate_message.do"/> </action> <!-- populate_message.do: Prepare to show the secondary window containing the message details. --> <action path="/populate_message"

type="com.dstsystems.concorde.presentation.admin.ccg.web.frontController.PopulateMessageAc tion" name="messageActionForm" scope="session" validate="false" input="/close_modal.jsp? returnValue=1"> <forward name="success" path="/ccg/message.jsp"/> </action>

6.4.3.

Save Entity Functionality

This sequence of action mappings would be invoked when the Save or OK buttons are pressed to cause the data to be saved. The following example is for the OK button from a secondary window.
<!-- save_message.do: Triggered by selecting the OK button on the message secondary window. Update the session state with the modified values and validate the DTO, then call business flow to save the message and return to the main window, updating it's state. -->

9/3/2010

Page 5 of 6

<action path="/save_message" type="com.dstsystems.concorde.presentation.admin.ccg.web.frontController.UpdateMessageActi on" name="messageActionForm" scope="session" validate="true" input="/ccg/message.jsp"> <forward name="save" path="/invoke_save_message.do? flowName=saveCustomerCommunicationMessage" /> <forward name="noSave" path="/close_modal.jsp?returnValue=0" /> </action> <!-- invoke_save_message.do: Calls the business flow to save the message. --> <action path="/invoke_save_message"

type="com.dstsystems.concorde.presentation.admin.commonModules.bf.web.frontController.Invo keSaveBusinessFlowAction" name="messageActionForm" scope="session" validate="false" input="/ccg/message.jsp"> <forward name="success" path="/close_modal.jsp?returnValue=0" /> <forward name="ghostUpdate" path="/invoke_retrieve_message_details.do" /> </action> <!-- invoke_retrieve_message_details.do: Gets the message details --> <action path="/invoke_retrieve_message_details" type="com.dstsystems.concorde.presentation.admin.commonModules.bf.web.frontController.Invo keRetrieveDetailBusinessFlowAction" name="messageActionForm" scope="session" validate="false" input="/close_modal.jsp? returnValue=1"> <forward name="success" path="/populate_message.do"/> </action> <!-- populate_message.do: Prepare to show the secondary window containing the message details. --> <action path="/populate_message"

type="com.dstsystems.concorde.presentation.admin.ccg.web.frontController.PopulateMessageAc tion" name="messageActionForm" scope="session" validate="false" input="/close_modal.jsp? returnValue=1"> <forward name="success" path="/ccg/message.jsp"/> </action>

9/3/2010

Page 6 of 6

Sign up to vote on this title
UsefulNot useful