Developing Basic JPDs

In this section, you start building a basic JPD for the Room Service functionality of the Wonderland Casino application.

Using Workshop to Create JPDs

To create a JPD through Workshop, you first need to create a new process application, which is deployed as an EAR file (see Figure 11.2).

Figure 11.2. Creating a new process application.

When you create a new process application, a Web project containing the processes directory is created by default. The processes directory contains a basic process or a JPD. A Schemas directory is also created. For the XML documents placed in this directory, the WebLogic Framework creates XML Beans automatically.

When you double-click a JPD file, the process is displayed on the desktop. The Palette lists the different process nodes that can be used with a JPD. Table 11.1 explains the functionality these nodes provide. Receiving nodes ”namely, Client Request and Control Receive ”are blocking nodes because the process stops at that node until it receives a message.

Table 11.1. Nodes You Can Include in a JPD

NODE	EXPLANATION
Client Request	Provides a way for a client to make a request to a business process.
Client Response	Provides a way for a business process to send messages to clients .
Control Send	Provides a way for a business process to send messages to resources via controls.
Control Send with Return	Provides synchronous communication between a business process and resources via controls.
Control Receive	Provides a way for a business process to receive asynchronous messages from resources via controls. The process waits at these nodes until it receives a message.
Perform	Any Java code could be written in these nodes for executing some logic. No input parameter can be passed, and this node doesn't have any return value.
Decision	This is similar to a Java if - else statement.
Switch	Similar to a Java switch statement.
While Do	Similar to a Java while - do statement.
Do While	Similar to a Java do - while statement.
For Each	Similar to a Java for statement.
Parallel	The point in a business process at which a number of activities takes place in parallel. When activities on one of the branches are completed, activities on all other branches terminate.
Event Choice	Represents a point at which a business process waits to receive one of a possible number of events. Flow of the execution proceeds along the branch that receives the event first.
Finish	Marks the end of the process.

There are five ways of starting a JPD in Workshop. Double-click the Starting Event node, as shown in Figure 11.3 to select an event for starting the process. Figure 11.4 shows the five different ways you can start a process.

Figure 11.3. Double-clicking the Starting Event Node.

Figure 11.4. Selecting a starting event for a process.

These are the five ways to start a process:

• Invoked via a Client Request ” This is an asynchronous method of starting a process. The process receives a document from a client that is passed through a JMS queue.

• Invoked Synchronously via a Client Request with Return ” This method involves a synchronous call between the client and process. The client is blocked until the client receives the document from the process.

• Subscribe to a Message Broker Channel and Start via an Event ” The process starts after receiving a document from a message channel based on an event trigger.

• Subscribe Synchronously to a Message Broker Channel and Start via an Event ” The process starts after receiving a synchronous message from a message channel.

• Invoked via One of Several Client Requests or Subscriptions (Event Choice) ” The process can receive a document from multiple sources. These sources could be one or more direct client calls or subscriptions to message channels. The first source to generate a document starts the process.

Message channels are discussed later in this chapter in the section, "Using Message Brokers."

Create a new process to be started by a Client Request. As soon as you choose this option, the Client Request node is displayed in the JPD. Double-click this node to specify the properties. Figure 11.5 shows the Client Request dialog box.

Figure 11.5. The Client Request node.

Select the Order node under the RoomService_Schema.xsd file, which is imported in the Schemas directory (see Figure 11.6). This Schema has an order number, a room number, and an item. Click OK to add this node, and then click the Receive Data tab, where you create a variable or select an existing variable to store the value from the input document for use in the process. To do this, use the Variable Assignment radio button.

Figure 11.6. General settings for the Client Request method of starting a process.

Instead of using a variable directly, however, use transformation to store the room number in a string variable. To do this, select the Transformation radio button instead of Variable Assignment to display a window for selecting the variable. For this process, use two variables: a string variable to store the room number and an XML type for the entire input document. After selecting the variables , click the Create Transformation button. These options are shown in Figure 11.7.

Figure 11.7. Receive data for the Client Request method.

When you click the Create Transformation button, you see a visual mapping of the source to the variables (see Figure 11.8). Map the room number to the string variable by dragging the GuestRoom element from the Source Schema section to the Target Schema section.

Figure 11.8. Viewing mapping in the Transformation tool.

Two files are created when you use the Transformation tool: a data transformation file ( .dtf ) containing a method with the code generated for the transformation, and an XQ file to store the XQuery. These two files are stored in the same directory as the JPD file.

SHOP TALK : INTEGRATING HETEROGENEOUS DATA SOURCES WITH XQUERY

I have used XQuery to integrate different types of data sources: relational database management systems (RDBMSs), Web services, adapters, and XML. XQuery is a useful technology for creating an enterprise-wide join. For example, I used it with a portal application when I needed to create a portlet for getting information from these different data sources. I didn't have to use different APIs, such as JDBC or J2CA; instead, I just used XQuery.

After you have the information from the Client Request node, you can check whether the room number comes up as occupied or vacant. If it comes up as occupied, you can print the room number and the item as the response. To do this, you need to add a Decision node below the Client Request node where you can implement the condition. True is always straight down in the Decision node; false is along the other branch of the node.

To add a Decision node, drag it from the Palette and drop it under the Client Request node on the yellow circle icon in the desktop area.

Right-click the node, choose Rename, and enter Checkroom for the new name . To specify the logic, double-click the node to open a dialog box with two options, shown in Figure 11.9. Use the Schema option to select a variable with a Schema, and use XQuery to specify the condition based on this Schema. Use the Method option to create a method that returns a Boolean value.

Figure 11.9. Using a Decision node.

You can use a Decision node for creating a condition, but for creating the message, you need to add two Perform nodes, one below the Checkroom node to return a valid room order and the other below the false node for an invalid room number. Rename the Perform nodes as isValid and isNotValid .

Finally, add a Client Response node to actually send the data to the client. In the General Settings tab, click Add and add a variable of a String type. Then click the Send Data tab and select message (String) as the variable from the Select Variables to Assign list (see Figure 11.10).

Figure 11.10. Selecting a variable for the Client Response node.

Now that you've finished creating the JPD, shown in Figure 11.11, you can test it by building and deploying the application. To test this JPD, use an XML document with some sample values for the elements; this document has been included in the Web application's support directory on the book's CD.

Figure 11.11. The completed JPD.

Click the + in the Decision node to expand it. You can also select a number of nodes, right-click on them, and choose Group Selected. This organizes the selected nodes into a group and compresses them. To view individual nodes, just click the + sign to expand the group . You can use this option for easy maintainability when you have several nodes in a JPD.

Monitoring JPD Instances

After you start the process, you can monitor instances of it with the WebLogic Integration Administration Console. This Web-based tool is used to configure and monitor the components in WebLogic Integration. There are two ways to start this tool:

• Select Tools, WebLogic Integration, WebLogic Integration Administration Console in Workshop.

• Navigate to the URL http://localhost:7001/wliconsole with a Web browser.

When prompted for a username and password, use the WebLogic administrator's username and password. After logging in, click the Process Instance Monitoring link on the main page to display all the JPDs that currently have running instances (see Figure 11.12).

Figure 11.12. Monitoring JPDs in the Administration Console.

Click the name of the JPD to view all its instances. Notice that an ID is generated for each instance.

There are four options you could use with each instance:

• Suspend ” Temporarily suspends execution of an instance. Use this option if there's a known problem with one of the back-end applications, and you want to suspend the process until the back-end application resumes.

• Resume ” Continues execution of a suspended instance. If you've suspended execution of a process instance until the back-end application is running again, selecting this option resumes execution of the instance.

• Terminate ” Stops execution of an instance. Use this option if the process is hung or goes into an infinite loop.

• Unfreeze ” If resources required for execution of a JPD are unavailable, WebLogic Integration provides a mechanism to freeze the process ”a Boolean attribute in the Property Editor called Freeze on Failure. You can specify a timeout period; after that period has elapsed, the process is terminated . If the process is frozen, you can manually unfreeze it with the Unfreeze option.

To get more details about an instance, click its instance ID. Figure 11.13 shows the details displayed when you click an instance ID. To monitor the instance in a graphical mode, click the Graphical View button. Nodes that are bright are completed nodes, green nodes are blocking nodes, and grayed nodes haven't been executed yet.

Figure 11.13. Monitoring process instances.

FREEZE ON FAILURE

The Freeze on Failure attribute is configured for the entire JPD, not on individual nodes. Also, if an exception handler is configured, it is always triggered, even if the Freeze on Failure attribute is set to true .

Transaction Demarcation in a JPD

There are two ways to demarcate a transaction in a JPD: implicitly and explicitly.

For implicit transactions, blocking nodes in a process define a transaction boundary. The node preceding a receiving node marks the end of a transaction; a new transaction begins at the receiving node. (Just to refresh your memory, Client Request and Control Receive are receiving nodes.)

A Parallel node indicates a transaction boundary. The node immediately preceding the group node marks the end of a transaction. A new transaction begins at the group node, which ends when the group node ends. The node immediately after the group node marks the beginning of yet another new transaction. Parallel nodes can be implemented by using an Event Choice or a Parallel node.

To create explicit transactions, you can select contiguous nodes, right-click on them, and choose Create Transaction. Receiving or Parallel nodes cannot be one of the selected nodes, nor can they exist within an explicit transaction. The reason for this rule is that JPDs are executed as EJBs, which do not support nested transactions. If an explicit transaction is created, the transaction demarcation is displayed in Workshop (see Figure 11.14).

Figure 11.14. An explicit transaction viewed in Workshop.

Exception Handling in a JPD

There are three ways to define an exception handler within a business process:

• Create a global exception handler by creating an exception path for the Start node. This exception handler responds to exceptions not handled in the business process.

• Create a group exception handler by selecting a group of nodes. This exception handler responds to exceptions for one of the nodes in the group.

• Create an exception handler for an individual node that responds to exceptions only for that particular node.

An exception handler for an individual node is executed first. If there is no exception handler for an individual node, the path associated with the group is executed. If there's no group exception handler, the global path is executed.

To create an exception handler, simply right-click the node or group, and choose Add Exception Path. You can define several properties for an exception in the Property Editor:

• name ” The name to be displayed in WebLogic Workshop.

• notes ” A description for the exception.

• afterExecute ” The action to be taken after the exception path is executed, which can be one of the following:

  • Skip ” Skip the node or group that the exception path is associated with.

  • Resume ” Resume execution of the process at the node following the one that threw the exception.

  • Rethrow ” Nodes are executed and the same exception is rethrown, but the handler at the next level up handles the exception.

• retry -count ” The number of times the process engine tries to execute the node or group in the path before the afterExecute path is executed. If this property is set for a group, the retry action starts at the beginning of the group.

• execute in rollback ” If this property is set to true, the exception path is executed when the associated transaction is rolled back.

To stop the process after catching an exception, add a Finish node on the exception path.