bea.com | products | dev2dev | support | askBEA

Download Docs | Site Map | Glossary
Search

Development Guide

Setting Up Portal Navigation

Portal navigation is achieved through the use of Webflow, a mechanism designed to help you build Web applications and maintain a separation between presentation logic and underlying business processes. When the visitor causes an event, such as clicking Next on a page, Webflow determines what the visitor will see next. At appropriate times during a visitor's interaction, the Webflow may also invoke Pipelines, predefined, specialized components used to validate data or to execute back-end business processes.

Because the Webflow's centralized XML configuration files specify the order in which pages are displayed to your Web site's visitors, use of the Webflow mechanism may reduce the amount of work necessary to create and modify the flow of your Web site.

This section contains information on the following subjects:

- Building a Webflow

- Creating a Pipeline and Adding it to a Webflow

- Synchronizing the Webflow to the Application

- Creating a New Input Processor

- Extending Webflow by Creating Extension Presentation and Processor Nodes

Building a Webflow

This section shows you how to build a basic Webflow by adding the necessary nodes to the Webflow and connecting those nodes to each other with transitions.

To build a Webflow, you need to complete the following steps:

- Step 1. Create the Webflow

- Step 2. Add Nodes to the Webflow Canvas

- Step 3. Identify the Begin Node

- Step 4. Create Transitions Between Nodes

Completing these steps will provide you with a rudimentary Webflow. Subsequent information in this section will complete the Webflow-building process by showing you how to:

- Create and add a Pipeline to the Webflow (see Creating a Pipeline and Adding it to a Webflow)

- Synchronize the Webflow to the application (see Synchronizing the Webflow to the Application)

Note: While the procedures outlined here and in subsequent parts of this section imply a specific sequence for creating Webflows and Pipelines, this is done only to facilitate the document and is not required. You can follow whatever sequence is most accommodating to your development needs. For example, you might want to create Pipelines for a Webflow before actually creating the Webflow. Do note that you cannot synchronize a Webflow to an application until the Webflow exists.

Understanding Webflow Components

Before attempting to build and implement a Webflow, you should understand some of the Webflow components you will be using in the ensuing procedures.

Nodes and Transitions

Nodes are the graphical representation of the functionality of a state in the Webflow. Depending on the node type, there are a number of predefined events that may occur (such as a visitor clicking a link on a Web page). When a particular event happens, the Webflow decides which subsequent node to invoke to continue the flow. This process is referred to as a transition, and is illustrated in Figure 9-1.

Figure 9-1 Generic Webflow Transition

Note that, as shown in Figure 9-1, nodes can be referred to as origin or destination nodes, depending on their location in a transition.

Types of Nodes

There are two main types of nodes: presentation nodes and processor nodes. Each of the presentation and processor nodes can be used as origin or destination nodes within the Webflow.

Presentation Nodes

Presentation nodes represent states in which the Webflow presents or displays something to a person interacting with the Web application. The form of the presentation can be:

- HTML

- JavaServer Page (JSP)

- Java servlets

You can also create extension (custom) presentation nodes for use in the Webflow. For more information about extension presentation nodes, see How to Create an Extension Presentation Node.

Processor Nodes

Processor nodes represent states in which the Webflow invokes more specialized components to handle such activities as form validation or the back-end business logic that drives the site's presentation. The processor nodes available for use are described in Table 9-1.

Table 9-1 Webflow Processor Node Types

Processor Node Type | Description
--- | ---
Input Processors | Input Processors are predefined, specialized Java classes that carry out more complex tasks when invoked by the Webflow mechanism. Input Processors are typically used to validate HTML form data, or to provide conditional branching within a Web page. For example, an Input Processor may contain code that verifies whether a date has been entered in the correct format, as opposed to embedding that code within the same JSP that displays the form fields. Input Processors contain logic that is specific to the Web application, and are therefore loaded by the Web application's container.
Pipelines | A Pipeline is also a type of processor node that may be invoked by the Webflow. Pipelines initiate the execution of specific tasks related to your business process, and can be transactional or nontransactional. For example, if a visitor attempts to move to another page on your Web site but you want to persist the visitor's information to a database first, you could use a Pipeline. Pipelines contain business logic that may apply to multiple Web applications within a larger enterprise application, and are therefore loaded by the Enterprise Java Bean (EJB) container. All Pipelines are collections of individual Pipeline Components, which can be implemented as Java objects or stateless session Enterprise JavaBeans (EJBs). Pipeline Components are the parts of a Pipeline that actually perform the tasks associated with the underlying business logic. When these tasks are complex, Pipeline Components may also make calls to external services (other business objects).
Extension Processor Nodes | Extension (custom) processor nodes for use in the Webflow. For more information about extension processor nodes, see Extending Webflow by Creating Extension Presentation and Processor Nodes.

Wildcard Nodes

If the Webflow cannot locate a specific presentation or processor node to complete a transition, the Webflow will search for a wildcard presentation or processor node to use as the origin node. Therefore, wildcard presentation nodes and wildcard processor nodes implement default behavior for your Web application. Put another way, wildcard nodes allow you to abstract common functionality and to locate that functionality in a single place in your Webflow. Use Wildcard nodes only when you haven't explicitly defined destination nodes in the Webflow. You may have one wildcard presentation node and one wildcard processor node per namespace.

An example of a Wildcard node might be when you want a link called Help (which is present on every page) to always point to a JSP containing help information. To do so, you could use a wildcard presentation origin. Further, you might always want exceptions returned from processor nodes to transition to JSP containing detailed information about the error. You could handle both of these situation with a wildcard processor node.

Note: A slight impact on performance might occur if the Webflow must search for a wildcard node, as more processing is involved.

Types of Transitions

There are two types of transitions: event and exception.

- An event transition represents the processing logic between two nodes when an event occurs on one of them and that event is successful.

- An exception transition represents the processing logic that occurs when activity on a processor node fails and an some sort of exception must be thrown. These transitions usually direct the transaction.

For more information on the events that cause transitions, see Types of Events.

Types of Events

Each node in a Webflow responds to events, which cause transitions (that is, movement from an origin node to a destination node). However, the types of events a node responds to depends on whether the node is a presentation node or a processor node.

Presentation nodes respond to the following events:

- Links

- Buttons

In other words, when a visitor to the Web site clicks a link or a button, the Webflow responds to that event. A response might be to transition to another presentation node (such as a JSP) or to a processor node (such as an Input Processor to validate visitor-provided form data).

Processor nodes respond to the following events:

- Exceptions

- Return objects

Exceptions occur when an Input Processor or Pipeline does not execute properly, and indicates an error state. Otherwise, these processor nodes return an object that the Webflow can use to continue processing.

Note: Webflow used in portal applications may respond to more events than those described above.

Encoding Webflow URLs

New context parameters ENCODE_URLS, ESCAPE_URLS, ENCODE_STATIC_URLS, and ESCAPE_STATIC_URLS have been added for 70sp5 that control the default setting for URL escaping and encoding in webflow URLs. See WebflowJSPHelper Javadoc for more information regarding escaping and encoding of URLs.

ENCODE_URLS is the default setting indicating whether webflow URLs should be encoded. Allowable param-values are true and false. If not set the default, default is true to ensure backward compatibility.

<context-param>

<param-name>ENCODE_URLS</param-name>

<param-value>false</param-value>

</context-param>

ESCAPE_URLS is the default setting indicating whether webflow URLs should be escaped. Allowable param-values are NO_URL_ESCAPE, ESCAPE_URL, CALCULATE_ESCAPE. If not set the default, default is URL_ESCAPE to ensure backward compatibility.

<context-param>

<param-name>ESCAPE_URLS</param-name>

<param-value>CALCULATE_ESCAPE</param-value>

</context-param>

The above 2 defaults are for the following tags and also for the WebflowJSPHelper createWebflowURL methods that do not have escape or encode as a parameter:

>     <wf:createWebflowURL/>

>     <wf:form/>

>     <wf:validatedForm/>

>     <portal:createWebflowURL/>

>     <portal:form/>

>     <portal:validatedForm/>

>     <portal:createPortalPageChangeURL/>

>     <portlet:createWebflowURL/>

>     <portlet:form/>

>     <portlet:validatedForm/>

>     <portlet:createPortletEditURL/>

>     <portlet:createPortletUneditURL/>

>     <portlet:createPortletMinimizeURL/>

>     <portlet:createPortletUnminimizeURL/>

>     <portlet:createPortletMaximizeURL/>

>     <portlet:createPortletUnmaximizeURL/>

>     <portlet:createPortletFloatURL/>

ENCODE_STATIC_URLS it the default setting indicating whether static URLs should be encoded. Allowable param-values are true and false. If not set the default, default is true to ensure backward compatibility.

>         <context-param>

>            <param-name>ENCODE_STATIC_URLS</param-name>

>            <param-value>false</param-value>

>         </context-param>

ESCAPE_STATIC_URLS is the default setting indicating whether static URLs should be escaped. Allowable param-values are NO_URL_ESCAPE, ESCAPE_URL, CALCULATE_ESCAPE. If not set the default, default is URL_ESCAPE to ensure backward compatibility.

>         <context-param>

>            <param-name>ESCAPE_STATIC_URLS</param-name>

>            <param-value>CALCULATE_ESCAPE</param-value>

>         </context-param>

The above 2 defaults are for the <wf:createResourceURL/> tag and the WeblfowJSPHelper createStaticResource methods that do not have escape or encode as a parameter.

URLs need to be encoded if you wish to maintain session state and the browser does not accept cookies. URLs will only need to be encoded if the browser does not accept cookies.

URLs must be escaped if they will contain any characters (with some exceptions - see below) that would be encoded using java.net.URLEncoder.encode(). Note however that even when escaping is on the entire URL is not encoded rather the URL will be tokenized using the characters ':', '/', '?', '=', and '&' then the substrings between the tokens are encoded using java.net.URLEncoder.encode(). The tokenizing is necessary so that the URL will still be recognized by the Webflow engine.

Note that escaping is relatively costly and should be avoided if possible but is required if the URL might have any characters other then those ignored by java.net.URLEncoder.encode(), that is any characters other than 'a' through 'z', 'A' through 'Z, '0' through '9', '-', '_', '.', or '*' with the exception of the tokenizing characters mentioned above. If the content of the URL will not be determined until runtime and might contain "illegal" characters you should either have escaping on or use the calculate feature. Calculate should be used with care. For sites that have a small number of URLs that will need escaping using calculate rather then always escaping will result in a performance improvement. But, since calculate first checks the URL then encodes if needed, sites where most URLs need escaping will have poorer performance using calculate rather then escaping all URLs.

Webflow Tools and Buttons

You create Webflows by using the Webflow Editor, as depicted in Figure 9-4. Most activity in which you engage will require selecting either a tool button or a command button. Table 9-2 describes the tool buttons available and Table 9-3 describes the command buttons.

Table 9-2 Webflow Editor Tools

Tool | Function | Description
--- | --- | ---
| Selection Tool | Allows you to select and move nodes, event transitions, and exception transitions. Also allows you to add elbows to transitions. This is the default tool for the Webflow Editor. Note: This tool will stay selected until you select another one.
| Event Tool | Allows you to add an event transition between two nodes, or a self-referring event transition. Note: This tool will stay selected until you select another one.
| Exception Tool | Allows you to add an exception transition between two nodes, or a self-referring exception transition. Note: This tool will stay selected until you select another one.
| Presentation Node | Allows you to add a new Presentation Node to the Editor canvas.
| Wildcard Presentation Node | Allows you to add a new Wildcard Presentation Node to the Editor canvas.
| Input Processor Node | Allows you to add a new Input Processor Node to the Editor canvas.
| Pipeline Node | Allows you to add a new Pipeline Node to the Editor canvas.
| Wildcard Processor Node | Allows you to add a new Wildcard Processor Node to the Editor canvas.
| Extension (Custom) Processor Node | Allows you to add a new Extension (Custom) Processor Node to the Editor canvas. Note: The Extension (Custom) Processor Node tool is disabled until the Webflow Editor detects a new node in the webflow-extensions.wfx file.
| Proxy Node | Allows you to add a Proxy Node to the Editor canvas. You should create a Proxy Node any time you want to refer to a node that is defined in another namespace.

Table 9-3 Webflow Command Buttons

Tool | Function | Description | Keyboard Shortcut
--- | --- | --- | ---
| Print button | Allows you to print the entire Webflow namespace or Pipeline to a printer. | Ctrl+P
| Delete button | Deletes the selected Webflow component. The Delete button is disabled until a Webflow component is selected. | Delete
| Zoomed Overview button | Allows you to view the entire Webflow namespace or Pipeline at a glance. | Ctrl+Z
| Validate the Selected Node button | Allows you to run the Webflow validation feature on the selected node. The Validate the Selected Node button is disabled until a Webflow component is selected. | Ctrl + V
| Validate All button | Allows you to run the Webflow Editor's validation feature on the entire Webflow namespace, or the Pipeline Editor's validation feature on the entire Pipeline. | Alt + V
| Set Up Configuration Error Page Name button | Allows you to specify the name and path to the configuration error page. Note: Only available in the Webflow Editor. | --
| Pipeline Component Editor button | Opens the Pipeline Component Editor, which allows you to manage Pipeline Components. Note: Only available in the Pipeline Editor. | --

Step 1. Create the Webflow

To create a Webflow, use this procedure.

Note: This procedure assumes the following:

- You have either opened an existing project or have created a new one.

- The E-Business Control Center is running.

- The Site Infrastructure tab is selected.

1. Click the New icon to open the drop-down menu and select Webflow/Pipeline, as shown in Figure 9-2.

   Figure 9-2 E-Business Control Center with New Drop-Down Menu Open

   The New Webflow/Pipeline dialog box appears.

   Figure 9-3 New Webflow/Pipeline Dialog Box

2. Ensure that New Webflow is selected, then open the Webapp: drop-down menu and select the Web application for which you are creating the webflow (this value might already be selected). Selecting a Web application is important because Webflows are scoped to a Web application.

3. Type in a Namespace name in the Namespace edit box. A namespace is used to scope a Webflow so that multiple Webflows can be used in a single Web application without conflicting. Note that each Web application can have multiple namespaces.

4. Click OK.

   The Webflow Editor appears in the right-hand pane of the E-Business Control Center. Figure 9-4 shows an example.

   Figure 9-4 Webflow Editor

Step 2. Add Nodes to the Webflow Canvas

A Webflow is composed of two types of nodes: presentation nodes and processor nodes. Each of the presentation and processor nodes can be used as origin or destination nodes within the Webflow. For more information on Webflow nodes, see Understanding Webflow Components.

Add the first node to the Webflow Editor canvas by doing the following:

1. Select the appropriate tool and click the pointer (cross-hairs) anywhere on the canvas. Table 9-2 describes each of the tools in the Webflow Editor palette.

   The node appears on the canvas where you click; for example, if you want the first node to be a Presentation node (that is, a JSP, HTML file, or other presentation file), you would select the Presentation Node tool and then click over the canvas to place the node there.

   Figure 9-5 Placement of a Presentation Node

   Note: The Presentation Tool stays selected. This enables you to add as many Presentation nodes as necessary without reselecting the tool for each node. Also, you needn't worry about where on the canvas you place node. You can move it wherever you want by selecting the node and dragging it to the preferred location.

   When you place a node on the canvas, the node's property editor, shown in Figure 9-6, opens in a pane below the canvas. You can also open the property editor for a node by clicking the node itself.

   Figure 9-6 Presentation Node Property Editor

2. In the property editor, type the following information, as necessary:

   Table 9-4 Property Editors

   Property | Description
   --- | ---
   name | The name of the node. This value will appear in the node on the canvas. This value will auto-fill when you fill out the page-name field described below.
   type | The type of file the node references. For a presentation node, valid types are: portal jsp html/htm servlet
   page-relative-path | The relative path to the file the node references.
   page-name | The filename that the node references. The value entered here will be used to fill in the name property, although without the file extension (which is populated automatically, based upon what was selected for type); for example, if you enter pres01 here and select jsp as the type, when you tab out of this field, .jsp will be appended to the page-name and the name value will change to pres01.

   When completed, the Property Editor might look like the sample shown in Figure 9-7

   Figure 9-7 Sample Completed Property Editor for a Presentation Node

3. Continue adding nodes to the canvas until you've added all the nodes necessary for the webflow.

Step 3. Identify the Begin Node

The begin node is used as the starting point for the visitor's interaction with the application. It is designated as the initial entry point or state of the Webflow, which automatically transitions to a presentation or processor node. The begin node is generally a presentation node in the form of a JSP.

If a URL does not specify an origin, namespace, or event, the Webflow mechanism looks for a begin node in the default namespace. Although the begin node is optional, BEA recommends that you have at least one defined in your default namespace.

To identify a node as the begin node, use this procedure:

1. Right-click the node you want to assign as the Begin Node.

   The node's Context menu appears, as shown in Figure 9-8.

   Figure 9-8 Presentation Node Context Menu

2. Select Set the begin node.

   The node is marked by a green stripe to the right of the node name, as shown in Figure 9-9.

   Figure 9-9 Appearance of the Begin Node

Note: A webflow can have only one begin node.

Step 4. Create Transitions Between Nodes

With all the nodes placed on the canvas, connect them by creating transitions between them. Create these transitions by using the Event Tool and the Exception Tool, as shown in Table 9-2. The Exception Tool is red and the Event Tool is black.

Adding an Event Transition

To add an Event transition, do the following:

1. Click the Event Tool to activate it.

2. Place the pointer on the edge of the node from which transition will begin.

   If the connection is permissible, a small orange square will appear on the edge of the node.

3. Drag the pointer to the node that marks the end of the transition.

   A grey connection port will appear on the node at the transition origin site and, If the connection is permissible, an arrowhead will appear where the transition ends, as shown in Figure 9-10.

   Figure 9-10 Node-to-Node Event Transition

   If the connection is not allowed (for example if you are trying create an exception link on a presentation node), a red square filled with a red X will appear on the node's edge, as shown in Figure 9-11.

   Figure 9-11 Invalid Connection Indicator

4. Continue adding Event transitions as necessary to connect all nodes designed to respond to events.

Adding an Exception Transition

Use the Exception Tool to connect any nodes that might require exception handling to the node that will do that handling. For example, an input processor might accept data that needs to be validated before it can be passed. If that data contains an error, it might need to throw an exception. The Exception Tool lets you process the exception and display any results or other information. Note that the transition link between the node appears in red.

To add an Event transition, do the following:

1. Click the Event Tool to activate it.

2. Place the pointer on the edge of the node from which transition will begin.

   If the connection is permissible, a small orange square will appear on the edge of the node.

3. Drag the pointer to the node that marks the end of the transition.

   A grey connection port will appear on the node at the transition origin site and, If the connection is permissible, an arrowhead will appear where the transition ends.

   If the connection is not allowed (for example if you are trying create an exception link on a presentation node), a red square filled with a red X will appear on the node's edge, as shown in Figure 9-11.

4. Continue adding Exception transitions as necessary to connect all nodes designed to respond to exceptions.

With all nodes in place and connected by the proper transitions, the webflow might appear as the one shown in Figure 9-12.

Figure 9-12 Sample Webflow Layout

Using the Transition Tools

In addition to adding a transition (as described in Adding an Event Transition and Adding an Exception Transition), you can also move an existing transition's connection port, add elbows to transitions, and delete a transition.

Moving a Connection Port Connection ports accepting transitions are called input connection ports; connection ports where transitions originate are called output connection ports. In some cases, it may be helpful to move the node's connection port. To reposition the connection port on a node, follow these steps:

1. Select the Transition tool or the Selection tool.

2. Click and hold the mouse button on the connection port, then drag the connection port to the desired location on the node.

3. Release the mouse button to place the connection port in the new location.

The connection port associated with a self-referring transition can only be moved along the same node edge.

Moving a Transition to Another Node You can move the end point of a transition (indicated by an arrowhead) from one node to another (assuming that the connection is allowable). Do the following:

1. Select the Transition tool or the Selection tool.

2. Select the end point (arrowhead) you want to move.

3. Holding down the left mouse button, drag the arrowhead to the node to which you want to connect it.

4. Release the mouse button.

Creating, Moving, and Deleting Elbows in Transition Lines You can also reposition transition lines on an Editor's canvas by moving, creating or deleting elbows. Elbows allow you to bend portions of the transition line, as shown in Figure 9-13, to enhance the appearance of the flow.

Figure 9-13 Elbows in Transitions

To create a new elbow, follow these steps:

1. Single-click a transition to view the existing elbows, which appear as black squares.

2. Click and hold the mouse button anywhere on the transition line (except on an existing elbow) and drag the mouse to add the new elbow. The selected elbow appears as an orange square.

3. Release the mouse button to create the elbow in that location.

To move an elbow in an existing transition, follow these steps:

1. Single-click a transition to view any existing elbows, which appear as black squares.

2. Click and hold the mouse button on the elbow as you drag it to the desired position. The selected elbow appears as an orange square.

3. Release the mouse button to place the elbow in the new location.

To delete an existing elbow, follow these steps:

1. Single-click a transition to view the existing elbows, which appear as black squares.

2. Click the elbow you want to delete to select it. The selected elbow appears as an orange square.

3. Click the Delete button on the Editor's toolbar, or press the Delete key.

Creating a Pipeline and Adding it to a Webflow

Figure 9-14 is a detailed look at a Webflow. In this example, you will see that two nodes are labeled PL01 and PL02. These nodes are called Pipelines.

Figure 9-14 Webflow Example: Detail Showing Pipeline Nodes

A Pipeline is a type of processor node that is typically used in a Webflow to execute back-end business logic. Each Pipeline is comprised of a number of Pipeline Components that perform specific tasks. BEA provides a number of Pipeline Components that are packaged with the WebLogic Portal product suite that you may want to reuse in your own Pipelines. However, you may also want to create your own Pipeline Components to execute your organization's specific business processes.

This section will show you how to create a pipeline by following these steps:

- Step 1: Create a New Pipeline Component

- Step 2: Add the New Pipeline Component to the Webflow

Understanding the Pipeline Editor

As with Webflows, you create a Pipeline and add functionality to it by using the Pipeline Editor in the E-Business Control Center, as shown in Figure 9-15 (see also Figure 9-18).

Figure 9-15 E-Business Control Center with Pipeline Editor Displayed

The Pipeline Editor has a set of display and behavior buttons and a set of command buttons along its top border and a set of tool buttons along its left border. Table 9-5 describes the tool buttons, Table 9-6 describes the display, and behavior buttons and Figure 9-7 describes the command buttons.

Table 9-5 Pipeline Editor Tools

Tool | Function | Description
--- | --- | ---
| Selection Tool | Allows you to select and move Pipeline Components, event transitions and exception transitions. This is the default tool for the Pipeline Editor. Note: This tool will stay selected until you select another one.
| Event Tool | Allows you to add an event transition between two nodes. Note: This tool will stay selected until you select another one.
| Exception Tool | Allows you to add an exception transition between two nodes, or a self-referring exception transition. Note: This tool will stay selected until you select another one.
| Begin Node | Allows you to designate one of the Pipeline Components already on the Editor canvas as the Begin Node for the current Pipeline.
| Pipeline Component | Allows you to add new Pipeline Components to the Editor canvas.

Table 9-6 Pipeline Display and Behavior Buttons

Tool | Function | Description
--- | --- | ---
| Show/Hide Grid button | Allows you to show or hide a grid background in the Editor canvas.
| Snap to Grid button | Allows you to control whether or not Webflow components are automatically placed to the nearest grid point on the Editor canvas when you release the mouse button.
| Link Optimization button | Allows you to control whether or not the connectors on each node will be automatically moved around the perimeter of the node as the node is moved on the Editor canvas.
| Show/Hide Exceptions button | Allows you to show or hide exception transitions in the Editor canvas.
| Make This Pipeline Transactional button | Allows you to specify whether the Pipeline should be transactional. Note: Only available in the Pipeline Editor.
| Include Pipeline Session in Transaction button | Allows you to specify whether the Pipeline Session should be included in the transaction. Enabled only if the Pipeline Transaction button is on. Note: Only available in the Pipeline Editor.

The Pipeline Editor uses the same command buttons the Webflow Editor use (see Table 9-3), with the addition of the the button described in Table 9-7.

Table 9-7 Pipeline Command Buttons

Tool | Function | Description
--- | --- | ---
| Pipeline Component Editor button | Opens the Pipeline Component Editor, which allows you to manage Pipeline Components. Note: Only available in the Pipeline Editor.

Understanding what these buttons do and how to use them will make creating Pipelines a quick and easy process.

Step 1: Create a New Pipeline Component

This section contains the steps needed to create the Pipeline Component used by the Webflow.

Note: This procedure assumes the following:

- You have either opened an existing project or have created a new one.

- The E-Business Control Center is running.

- The Site Infrastructure tab is selected.

1. In the left pane of the Explorer, click Webflow/Pipelines. A list of Webflows and Pipelines appears in the Explorer's right pane.

2. In the Webflows/Pipelines list, expand the Pipeline Namespaces folder.

3. Open the namespace that will host the Pipeline. With pipelines, a namespace is used to scope a pipeline so that multiple pipelines can be used in a single enterprise application without conflicting.

4. Click the New icon above the Project name to open the New menu, as shown in Figure 9-16.

   Figure 9-16 New Menu for Selected Pipeline Namespace

5. Select Webflow/Pipeline.

   The New Webflow/Pipeline window opens, as shown in Figure 9-17.

   Figure 9-17 New Webflow/Pipeline Window

6. Create the new Pipeline by doing the following:

   1. Select the New Pipeline radio button.

   2. In the Namespace list box, select the namespace that will host the Pipeline; for example, bookmark.

   3. In the Pipeline Name field, enter the name you want to call the Pipeline; for example validate Bookmark.

   4. Click OK button.

   The Pipeline Editor appears, as shown in Figure 9-18.

   Figure 9-18 Pipeline Editor [Pipeline: validateData]

   Note that when the Pipeline Editor opens, the Abort Exception node is automatically placed on the canvas. This node is used for exception handling and causes the Webflow to abort when an exception can't be resolved by normal processing.

7. Create the first Pipeline component by doing the following:

   1. Click and hold the Abort Exception Node and drag it down near the bottom of the canvas.

   2. Select the Pipeline Component Node tool (see Table 9-7).

   3. Place the crosshairs on the Pipeline Editor canvas somewhere above the Abort Exception Node, where you want to place the new Pipeline Component. Click to place the new Pipeline Component node on the Editor canvas.

   4. Click the Pipeline Component Editor button (see Table 9-7). The Pipeline Component Editor window opens, as shown in Figure 9-19.

   Figure 9-19 Pipeline Component Editor

   5. In the Pipeline Component Editor window, click New. The Pipeline Component Creator window opens, as shown in Figure 9-20.

      Figure 9-20 Pipeline Component Creator

   6. In Name, enter the name you want to call the Pipeline component; for example, validateBookmark.

   7. Select Class as the Type.

      The Type value is important because Pipeline components can be either a regular Java class or a session EJB. Selecting Class implements a regular Java class while selecting JNDI implements a session EJB

   8. In Class name, enter the full package name of the class that the Pipeline component will reference; for example:

      examples.wlcs.sampleapp.order.pipeline.ValidateBookmarkClass

      The completed dialog box might look like the example in Figure 9-21.

      Figure 9-21 Completed Pipeline Component Creator Dialog Box

   9. Click OK to close the Pipeline Component Creator window.

   10. In the Pipeline Component Editor window, click Close.

       The new Pipeline component appears in the Pipeline components list on the Pipeline Component Editor.

   11. Select the new Pipeline node.

   12. In the Properties Editor, located below the canvas, select the Pipeline name you entered in step f from the component*/Value pop-up list, as shown in Figure 9-22.

       Figure 9-22 Properties Editor—Component Selection

       The new component name appear in the component*/value cell.

8. In this example, we want any exception to cause you to exit the Pipeline. Therefore, the node must be connected to the Abort Exception node. Connect the new Pipeline component to the Abort Exception node, as follows:

   1. Click the Exception tool.

   2. Position the transition by moving the mouse to bottom edge of the validateBookmark node. A solid orange square indicates an acceptable connection location, and the cursor changes to indicate a transition addition.

   3. Hold and drag the mouse to the Abort Exception node. Release the mouse to connect the transition to the Abort Exception node (Figure 9-23).

   Figure 9-23 validateBookmark - Abort Exception Connection

   4. Select the Exception event. The event line turns orange.

   5. In the Properties Editor, select the second column (Figure 9-24), and enter the package name to the exception class, as follows:

      com.bea.p13n.appflow.exception.PipelineException

      Figure 9-24 Properties Editor—Exception Value

9. Make the validateBookmark node a Begin Node, as follows:

   1. Click the Begin Node Tool (see Begin Node).

   A message appears explaining that you are about to create a Begin node, as shown in Figure 9-25.

   Figure 9-25 Begin Node Message Box

   2. Select OK in the message window.

   3. validateBookmark become the Begin node, as indicated by the green bar on its right edge, as shown in Figure 9-26.

   Figure 9-26 validateBookmark as Begin Node

10. Save the new Pipeline by selecting File -\> Save from the E-Business Control Center Main toolbar.

Step 2: Add the New Pipeline Component to the Webflow

Now, you need to add the new pipeline component to a Webflow. To do so, use the following procedure.

1. In the right pane of the Explorer, open the Web application to which you want to add the Pipeline. In that Web application, double-click the Webflow to which you want to add the Pipeline.

   The Webflow editor opens, as shown in Figure 9-27.

   Figure 9-27 Webflow Editor showing completed Webflow

2. Select the event between the bea.portal.framework... and bookmarkEditIP nodes and press Delete.

3. Add the validateBookmark Pipeline to the Webflow, as follows:

   1. Click the Pipeline Node tool (see Table 9-5) and place the pointer between bea.portal.framework... and bookmarkEditIP nodes. Click once to add the new Pipeline Node onto the Editor canvas in that location.

   2. In the Properties Editor, below the canvas, select the second column of the pipeline-name* row, and then select validateBookmark from the drop-down list, as shown in Figure 9-28.

   Figure 9-28 Properties Editor—Component Selection

4. Connect the validateBookmark Pipeline node to the other Pipeline nodes, as follows:

   1. With the Event tool (see Table 9-5) connect the validateBookmark node to the bea.portal.framework... node, click the Event you just created, and then in the Properties Editor —> Properties tab, change the name of the event to "success" and then press Enter.

   Note: The word "success" is case sensitive. Be sure to use a lowercase "s".

   2. With the Event tool, connect the validateBookmark node to the bookmarkEditIP node.

   3. Click the Event you just created, then in the Properties Editor's Properties tab, change the name of the event to "success" (if necessary), and press Enter.

   Figure 9-29 shows the Webflow Editor canvas after this process is completed. (The nodes have been moved to make the drawing easier to see.)

   Figure 9-29 Event Transitions

5. To save the changes, select File -\> Save from the E-Business Control Center Main toolbar.

Synchronizing the Webflow to the Application

The Webflow that you just created must be synchronized to the Web application in order for it to work. Data synchronization loads the Webflow's and Pipeline's XML definition into the database and the master data repository, which is an in-memory data store.

Warning: All application data is synchronized at once. If you and other developers concurrently synchronize data to a single enterprise application, it is possible to overwrite each others' work or create sets of changes that are incompatible and difficult to debug. To prevent this possibility, synchronize to separate instances of your application.

To synchronize the new pipeline component and the modified Webflow, use the following procedure:

1. Start WebLogic Server and open the E-Business Control Center.

2. Go to Tools -\> Synchronize.

   After a few seconds, the Synchronize progress meter appears (Figure 9-30).

   Figure 9-30 Synchronize Progress Meter

   This meter will indicate to you that synchronization is in progress. When the process is complete, the progress meter will so indicate and Stop changes to Close.

3. Click Close.

The Webflow is synchronized to the application.

Creating a New Input Processor

As discussed earlier in this section, Input Processors are predefined, specialized Java classes that carry out more complex tasks when invoked by the Webflow mechanism. They are typically used to validate HTML form data or to provide conditional branching within a Web page. BEA has developed a number of Input Processors that are packaged with the WebLogic Portal. While you may want to reuse these processors in your own applications, you might also want to create your own for use in your applications' Webflows.

Creating an Input Processor with the InputProcessor Interface

To create a new Input Processor, you must implement the com.bea.p13n.appflow.webflow.InputProcessor interface by providing the details of the process() method, as shown in Listing 9-1.

Listing 9-1 Implementing Process() for the InputProcessor Interface

>     public java.lang.Object process(javax.servlet.http.HttpServletRequest req,
>                                     java.lang.Object requestContext)
>                               throws ProcessingException

This interface processes the HttpServletRequest or the PipelineSession present in the HttpSession. The return object can be anything, but it must have a meaningful implementation of toString(). The webflow executor will call toString() on the returned object to generate the event for the processor.

Parameters | req - the HttpServletRequest object requestContext - the Object that uniquely identifies the request
Returns | An Object, which has implemented a meaningful form of toString().
Throws | ProcessingException or one of its sub-classes

Naming an Input Processor

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. This naming convention should help you keep track of Input Processors more easily.

Executing Business Logic with Input Processors

Execution of business (application) logic should typically not be done within Input Processors. Specifically, Input Processors should not call Enterprise JavaBeans (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, such logic could not be transactional, and would defeat a primary purpose of the Webflow architecture. By separating business logic from the presentation logic, your Web 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 the InputProcessorSupport Class

Alternately, your new Input Processor can extend the com.bea.p13n.appflow. webflow.InputProcessorSupport class, as shown in Listing 9-2. As its name implies, this abstract class allows you to use static helper methods that provide additional support for an Input Processor. If your new Input Processor class must extend some other class, however, you will not be able to take advantage of the InputProcessorSupport class.

Listing 9-2 Extending the InputProcessorSupport class

>     public abstract class InputProcessorSupport
>                              extends java.lang.Object
>                     implements InputProcessor, ValidatedFormConstants

Note: For more information about implementing the InputProcessorSupport class, refer to the Javadoc for com.bea.p13n.appflow.webflow.

When you are using the Webflow Editor to specify the properties for an Input Processor node you placed on the canvas, simply include the class name of your newly created Input Processor in the appropriate field. There are no additional activities you need to perform to make your Input Processor work with the existing Webflow mechanism.

Extending Webflow by Creating Extension Presentation and Processor Nodes

If creating new input processors and pipeline components to add to those BEA provides does not meet your needs, you may also choose to extend the Webflow mechanism by creating classes that can be used as Extension (Custom) Presentation or Processor Nodes. Once you create the classes associated with these nodes, you will need to register the new nodes in the webflow-extensions.wfx file. This section shows you how to perform these tasks.

How to Create an Extension Presentation Node

To create an Extension (Custom) Presentation Node, use this procedure:

1. Create a class that implements the com.bea.p13n.appflow.webflow. PresentationNodeHandler interface. Be sure your class returns a URL to which the WebflowServlet servlet can forward.

2. Register your extension node in the webflow-extensions.wfx file so it can be used in the Webflow and Pipeline Editors. See Making Your Extension Presentation and Processor Nodes Available in the Webflow and Pipeline Editors.

WebLogic Portal uses an Extension (Custom) Presentation Node named portal, which you can view as an example. Portal uses this extension node to indicate to the portal Webflow that the contents of the portlet are to remain unchanged (that is, it indicates that the last URL should be displayed). The portal node's implementation class is LastContentUrlNodeHandler.java.

How to Create an Extension Processor Node

Extension (Custom) Processors are processors that your organization (as opposed to BEA) develops for use in your applications' Webflows. Imagine you want to create an Extension (Custom) Processor that functions at the same level as an Input Processor processor or Pipeline Processor. Extension Processors may be used to perform activities not currently supported by the Webflow. However, the flow in and out of an Extension Processor is still governed by the Webflow mechanism. Extension Processors are represented as nodes in the Webflow Editor, much like the Input Processor and Pipeline Nodes are, but with a slightly different representation for easy identification.

For example, you may want to create an Extension (Custom) Processor that works with the BEA Rules Engine to support different Webflows based on some condition, such as membership in a customer segment. Another, more simple example might be a layout manager processor that automatically includes a header and footer in your JSP when given the page's body content. In fact, we have already created such a processor.

To create an Extension (Custom) Processor Node, use this procedure:

1. Create a class that implements the com.bea.p13n.appflow.webflow. Processor interface to define the Extension Processor. Listing 9-3 shows a typical implementation of the Processor interface.

Listing 9-3 Implementing the Processor Interface

>     public java.lang.Object process(java.lang.String webapp,
>                                     java.lang.String namespace,
>                                     javax.servlet.http.HttpServletRequest request,
>                                     java.lang.Object requestContext)
>                             throws java.lang.Exception

This interface executes the processor indicated by the request. The return object can be anything, but it must have a meaningful implementation of toString(). The webflow executor will call toString() on the returned object to generate the event for the processor.

Parameters | webapp - a String containing the webapp name namespace - a String containing the namespace name name - a String containing the processor name (foo.inputprocessor, bar.pipeline) request - the HttpServletRequest requestContext - the Object object that uniquely identifes the associated request
Returns | the results, as an Object. Can be anything, but must implement toString().
Throws | java.lang.Exception, if an error occurs

1. Register your processor in the webflow-extensions.wfx file so it can be used in the Webflow and Pipeline Editors.

Note: For instructions on how to register your extension node in the webflow-extensions.wfx file, see Making Your Extension Presentation and Processor Nodes Available in the Webflow and Pipeline Editors.

Making Your Extension Presentation and Processor Nodes Available in the Webflow and Pipeline Editors

After you have created an Extension (Custom) Presentation or Processor Node, you must make that node available to other developers on your team by registering the node in the webflow-extensions.wfx file.

Notes: The webflow-extensions.wfx file resides within the <BEA_HOME>/user_projects/myNEWDomain/beaApps/ portalApp-project/default/webflow/ folder (where <BEA_HOME> is where you installed WebLogic Portal; for example:

>     bea/user_projects/myNEWDomain/beaApps/portalApp-project/
>        default/webflow/

Registering an Extension (Custom) Processor Node will cause its corresponding tool on the Webflow Editor palette to become enabled once you restart the E-Business Control Center.

Registering an Extension Presentation Node

To register an Extension Presentation Node in the webflow-extensions.wfx file, follow these steps:

1. Open the webflow-extensions.xml file, which resides in the <BEA_HOME>/user-projects/myNEWDomain/beaApps/portalApp-
   project/application-synch/webapps/<APPLICATION> folder (where <BEA_HOME> is youre BEA parent directory and <APPLICATION> is the specific Web application.

2. Add an <end-node> element to the <end-node-registration> list.

3. Assign your presentation node a name with the Name attribute, and specify the class of the underlying node implementation with the Node-handler attribute.

4. Define the input parameters that the class expects upon invocation, using <node-processor-input> elements. Give each parameter a Name, and if the parameter is optional, assign the Required attribute a value of false.

   Note: This information will be used in the Webflow and Pipeline Editors' Property Editors.

5. Save the webflow-extensions.wfx file, and restart the E-Business Control Center.

Registering an Extension Presentation Node provides an example of registering an Extension Presentation Node in the webflow-extensions.wfx file.

Registering an Extension Processor Node

To register an Extension Processor Node in the webflow-extensions.wfx file, follow these steps:

1. Open the webflow-extensions.xml file, which resides in the <BEA_HOME>/user-projects/myNEWDomain/beaApps/portalApp-
   project/application-synch/webapps/<APPLICATION> folder (where <APPLICATION> is the specific Web application.

2. Add a <process> element to the <process-registration> list.

3. Assign your processor a name with the Name attribute, and specify the class of the underlying processor implementation with the Executor attribute.

4. Define the input parameters that the class expects upon invocation, using <node-processor-input> elements. Give each parameter a name, and if the parameter is optional, assign the Required attribute a value of false.

   Note: This information will be used in the Webflow and Pipeline Editors' Property Editors.

5. Save the webflow-extensions.wfx file, and restart the E-Business Control Center.