Introduction to patterns in WebSphere Message Broker V7

WebSphere Message Broker V7 introduces patterns to message flow development. A pattern is a reusable solution that encapsulates a tested approach to solving a common architecture, design, or deployment task in a particular context.

Ant Phillips, Software Developer, IBM

Photo: Ant PhillipsAnt Phillips is a Software Developer in IBM's Java Technology Centre in Hursley, United Kingdom. His current focus is on WebSphere sMash, a simple environment for creating dynamic Web applications. Before joining IBM, Ant was the technical lead at an innovative startup based in Newbury, UK. In previous lives, Ant worked for Sony® and Microsoft® and thoroughly enjoyed visiting Tokyo, Seattle, and several places in between. In his spare time, he plays as much sport as his wife and two children let him get away with.



06 October 2009

Also available in Chinese Japanese Spanish

Introduction

A pattern captures a commonly recurring solution to a problem, addressing the goals and objectives that you want to achieve. The specification of a pattern describes the problem being addressed, why the problem is important, and any constraints on the solution. Patterns typically emerge from common usage and the application of a particular product or technology. A pattern can be used to generate customized solutions to a recurring problem in an efficient way.

IBM® WebSphere® Message Broker V7 provides patterns that:

  • Give you guidance in implementing solutions
  • Increase development efficiency because resources are generated from a set of predefined templates.
  • Improve quality through asset reuse and common implementation of functions such as error handling and logging.

Patterns overview

The first step in using patterns is to select the right one. The Message Broker Toolkit has a new view called the Patterns Explorer, which provides a catalog of patterns and provides detailed help. The help guides you towards a suitable pattern to solve a particular problem. For example, you might want to implement a Web service front end where the requests are written to a WebSphere MQ queue. The Patterns Explorer guides you to a category of patterns called Service Facade.

Each pattern has values known as pattern parameters. The pattern parameters that you configure depend on the particular pattern and on the options that you enable for that pattern. An example of a pattern parameter is a queue name from where messages are read. The patterns provide defaults for nearly all pattern parameters and help is provided to explain them.

After you have configured the pattern parameters, you generate a pattern instance project, which is a Message Broker project that contains a pattern instance configuration file. This configuration file stores the pattern parameters that you configured. Generation also creates one or more additional Message Broker projects that typically contain message flows and other Message Broker artifacts that implement the pattern.

You can open the pattern instance configuration file at any time to see the values of the pattern parameters. Once a pattern configuration file has been reopened, you can regenerate the Message Broker projects. Regeneration deletes the generated Message Broker projects and recreates them from scratch. It is important to remember that the projects are completely deleted and recreated from scratch, so you lose any changes you have made to the projects.

The final step is to create a Broker Archive (BAR) file for the generated projects. You can then deploy the BAR file and test the flows. You may also need to create additional resources such as WebSphere MQ queues. The pattern instance project contains an HTML summary file as well as the pattern instance configuration file. The summary file has a section that explains any additional tasks that may be required, such as creating queues.

Some of the pattern parameters make fundamental changes to the generated artifacts. For example, if you choose to enable logging and error handling, then the generated projects contain additional message flows and ESQL scripts. In this example, you will also need to create additional WebSphere MQ queues where the error and log message flows will write their messages.

Before you begin

This article assumes a basic familiarity with WebSphere Message Broker. You will need to have Message Broker V7 installed on your machine, including the Message Broker runtime and Toolkit, and the Message Broker Explorer (MBX). The article will show you how to set up the necessary WebSphere MQ queue manager and Message Broker execution group.

In this article, you will use the new Brokers view in the Message Broker Toolkit to create and configure a broker.

You will explore the patterns available in Message Broker V7. In particular you will focus on the Service Facade to WebSphere MQ: one-way with acknowledgement pattern, which creates a Web service facade in which request messages are written to a WebSphere MQ queue. You will deploy an instance of this pattern to the broker and exercise the pattern instance using the Message Broker Test Client.

You will also deploy an instance of the Service Facade to WebSphere MQ: request-response pattern, which also writes Web service requests to a WebSphere MQ queue. Unlike the one-way pattern, this pattern waits for a WebSphere MQ response message before replying to the Web service request. To exercise this pattern you will need to download rfhutil, a well-known support pack tool from IBM.

Finally, you will create and monitor WebSphere MQ queues through the Message Broker Explorer (MBX).

Creating a local broker

Your first task is to create a broker and execution group to test the patterns. Message Broker V7 no longer has a Message Broker Administration perspective in the Toolkit. All administrative functions are performed in the Message Broker Explorer (MBX). To complement MBX, the Toolkit has a new view called the Brokers view, which is for application development. It can create, start, and stop brokers, and deploy BAR files.

In this section you will create a local broker through the Brokers view:

  1. Start the Message Broker Toolkit and switch to the Message Broker Application Development perspective.
  2. In the Brokers view, right-click on Brokers and select New => Local Broker.
  3. Enter a name for the broker and the broker queue manager. On Microsoft® Windows®, you also need to enter a username and password, which are used to configure a Windows service to run the broker.
  4. Click Finish to create the broker. The broker is displayed in the Brokers view:
    Figure 1. The local broker displayed in the Brokers view
    The local broker
  5. Start MBX. The local broker is visible in the Navigator.

Congratulations! You have successfully created a local broker ready to test patterns. In the next section you will create an instance of a pattern and deploy it to the local broker.

Exploring patterns

The Broker Development view displays projects in the current workspace, as shown in Figure 2 below. The view is split into three sections:

  • The top section displays the current working set name, or <all resources> if there is no active working set.
  • The middle section displays pattern instance projects, which are Message Broker projects that contain the configuration information after a pattern is generated. You will see how this works shortly.
  • The bottom section displays standard Message Broker projects such as message flow projects and Java projects. If the workspace does not contain any standard projects, then the bottom section displays the Quick Starts.
    Figure 2. The Broker Development view
    The Broker Development view

The Message Broker patterns are displayed in the Patterns Explorer view. There are several ways to navigate to the Patterns Explorer view:

  1. Click on the Patterns Explorer tab.
  2. Click New in the Pattern Instances section of the Broker Development view.
  3. Click Start from patterns in the Quick Starts section of the Broker Development view:
    Figure 3. Navigate to the Patterns Explorer view
    Navigate to the Patterns Explorer view

Browse the pattern specifications

In the Patterns Explorer, click on the Patterns label at the top of the tree. Introductory information about patterns is displayed. Under the Patterns label are the top-level pattern categories, such as Application Integration and File Processing. The next level down has more specific categories. For example, under File Processing is a category called Record Distribution. Finally, the leaf labels in the Patterns Explorer contain patterns that can be instantiated. The icons are different for the leaf patterns to indicate they can be instantiated.

Click on the MQ one-way with acknowledgment pattern. The pattern specification is displayed in the Message Broker Toolkit, with the pattern's full name: Service Facade to WebSphere MQ: one-way with acknowledgment, plus information about the pattern, including when to use the pattern, why you might want to use the pattern, and any constraints it has.

The Patterns Explorer is a great starting point when you have a problem that needs to be solved. The hierarchical layout of the Patterns Explorer lets you navigate from high-level pattern categories (abstract patterns) down to concrete patterns that you can instantiate.

Creating a pattern instance

To create an instance of the Service Facade to WebSphere MQ: one-way with acknowledgment pattern, click on Create New Instance at the bottom of the pattern specification. Enter OneWay as the name for the pattern instance and click OK.

The Pattern Configuration Editor is displayed, where you can configure the pattern instance. Pattern parameters are grouped into related sections such as Service Information, Logging, and Error Handling. Open each section using the twisty. Figure 4 below shows that one pattern parameter -- Service WSDL -- needs to be filled out. The green ticks against the other pattern parameter sections indicate that the other pattern parameters all have valid default values.

Figure 4. Configure the pattern instance parameters
Configure the pattern instance parameters

The pattern you are instantiating creates a Web service facade to a WebSphere MQ queue. Web service requests arriving at the generated message flow will be put onto a queue, which is a common problem to be solved using Message Broker. Web services are described using Web services Description Language (WSDL), and you will need a WSDL file to instantiate the pattern. To get you started quickly with patterns, the Patterns Explorer provides a sample WSDL file:

  1. At the bottom of the Pattern Configuration editor, click on Specification.
  2. Scroll down to Related tasks and click on Resources to get you started with the pattern.
  3. Click on Import the sample resources into your workspace.
  4. Click through the wizard and a new message set project is created in your workspace. It contains a WSDL file called OrderService.wsdl.
  5. Switch back to the Configuration tab in the editor and click Browse.
  6. Select OrderService.wsdl from the list of available WSDL files.
  7. Your final step is to generate the pattern instance by clicking Generate.

Generated projects and files

Two projects are created in your workspace, as shown in Figure 5 below. The first project is a pattern instance project called OneWay, which contains an XML file containing the pattern parameters you configured in the Pattern Configuration editor:

Figure 5. The generated projects for the pattern instance
The generated projects for the pattern instance

The pattern instance project also contains a summary file called OneWay_summary.html, which contains a description of the pattern instance project. The summary file also contains any tasks to be performed before the pattern instance can be successfully deployed:

Figure 6. The summary file for the pattern instance
The summary file for the pattern instance

Below the pattern instance project is a second project called OneWay_Flows, which contains Message Broker artifacts such as message flows and ESQL scripts. These artifacts implement the pattern, and they are ready to be deployed to a broker. But first, take a closer look at the summary file. The Tasks to Complete section tells you that you need to create two WebSphere MQ queues called ERROR and PROVIDER. These queue names are pattern parameters, so you could have changed them in the Pattern Configuration editor.

Create the queues

Before you deploy the message flows, you will create the queues required by the pattern:

  1. Switch over to MBX.
  2. Under the PATTERNSQMGR queue manager, right-click on Queues and select New => Local Queue.
  3. Enter ERROR for the queue name and click OK.
  4. Repeat for the second queue called PROVIDER. You should now have two local queues:
    Figure 7. The ERROR and PROVIDER queues
    The ERROR and PROVIDER queues

Deploying the generated message flow

The next step is to deploy the generated message flow. You will need a BAR file:

  1. Right click on OneWay_Flows and select New => Message Broker Archive.
  2. Configure the BAR file Project and Name, and click Finish.
  3. In the BAR file editor; select the message flow and message sets:
    Figure 8. Choose the resources for a Message Broker Archive
    Choose the resources for a Message Broker Archive
  4. Build and save the BAR file. Your message flow is ready to be deployed!
  5. Drag and drop the BAR file onto the execution group in the Brokers view. The BAR file is deployed to the execution group that you created earlier:
    Figure 9. The generated message flow deployed to the local broker
    The generated message flow deployed to the local broker

Message Broker Test Client

To exercise to the Web service, use the Message Broker Test Client:

  1. Click File => New and select Message Broker Test Client from the Message Broker category.
  2. Configure the Project and Name for the Message Broker Test Client and click OK. A new Message Broker Test Client file is created and an editor is opened.
  3. You need to configure the message flow to test. Switch to the Configure tab at the bottom of the editor and click Message Flows and then Add.
  4. In the Resources dialog, select Request.msgflow and click OK.
  5. Click on Deployment and choose the option to deploy the BAR file manually. You must also select your BAR file by clicking on Browse:
    Figure 10. Choose to manually deploy the Message Broker Archive
    Choose to manually deploy the Message Broker Archive
  6. Your final task is to configure the WebSphere MQ settings. Click on MQ Settings and make sure to deselect Stop when the first MQ message is received. Select Browse message from MQ output queue. These options specify how the Test Client will react when it sees messages arrive on the ERROR and PROVIDER queues. You are testing the flows through a Web service request and response, so you only want the Test Client to monitor the queues.
    Figure 11. Configure the WebSphere MQ settings
    Configure the WebSphere MQ settings
  7. Switch back to the Events tab. You should see that a Web service request has been configured, as shown in Figure 12 below. The Test Client has done this by looking at the flow you configured for testing. The Test Client has analyzed the WSDL file configured in the message flow and constructed a suitable Web service request to send to the flow! Very helpful! The details in the Web service request represent a purchase order that you are sending to initiate an order request:
    Figure 12. The purchase order Web service request
    The purchase order Web service request
  8. You can see a text version of the request by selecting Edit as text from the dropdown.
  9. Go ahead and send the Web service request to the message flow. Click Start on the Test Client toolbar and then click Finish when the Deployment Location dialog opens. The following sequence of events should be displayed:
    Figure 13. The events in the Message Broker Test Client
    The events in the Message Broker Test Client
  10. Click on the Received HTTP Reply message. The reply message sent back by the message flow is displayed. You can see that the purchase order has been accepted:
    Figure 14. The reply message from the message flow
    The reply message from the message flow
  11. Now click on the MQ Queue Monitor PROVIDER event. The Test Client shows a message placed on the PROVIDER queue by the message flow, as shown in Figure 15 below. The message flow has accepted the Web service request and placed the request message on the PROVIDER queue. In a real deployment you would have an application that monitors the PROVIDER queue and actions the purchase order requests as they arrive.
    Figure 15. The message written to the PROVIDER queue
    The message written to the PROVIDER queue

Congratulations! You have successfully deployed and exercised the Web service facade to a WebSphere MQ queue pattern!

Exploring the queues in MBX

Figure 16. Queue depths after the test run has finished
Queue depths after the test run has finished
  1. Switch to MBX, right-click on the PROVIDER queue, and select Browse Messages. A list of messages on the queue is displayed in the Message browser dialog:
    Figure 17. Choose a message to display from the PROVIDER queue
    Choose a message to display from the PROVIDER queue
  2. Right-click the message and select Properties => Data. The properties window displays the Web service request that you sent using the Test Client.
  3. You can also clear the messages from the PROVIDER queue. Right-click on the queue name and select Clear Messages. Select Queue will be cleared using MQGET API calls and then click Clear. Clearing queues avoids confusion when testing and debugging flows.

Deleting the pattern instance project

Before you start the next section of this article, clear up your resources. Right-click on the execution group and select Delete => All Flows and Resources. In the Broker Development view, right-click on the pattern instance project and select Delete. In the delete dialog, delete the pattern instance project and the message flow project.

Creating a Web service request-response pattern

The Service Facade to WebSphere MQ: one-way with acknowledgement pattern that you deployed took the Web service request and wrote it to a WebSphere MQ queue. In this section you will use a more sophisticated pattern called Service Facade to WebSphere MQ: request-response. This pattern also writes the Web service request to a WebSphere MQ queue. The difference is that this pattern waits for a response message on a response queue before sending the Web service reply.

  1. Right click on the MQ request-response pattern in the Patterns Explorer and select Create New Instance.
  2. Enter RequestResponse for the pattern instance name.
  3. In the Pattern Configuration Editor, click Browse on the Service WSDL and select OrderService.wsdl.
  4. Select Content and value for the validation parameters. This instructs the generated message flows to validate all Web service requests and responses.
  5. Open up the Logging section and set Logging required.
  6. Click Generate to create the pattern instance and generated message flows.
    Figure 18. Configure the pattern instance parameters
    Configure the pattern instance parameters

    The summary file for the pattern instance shows the additional queues you need to create -- RESPONSE, STORE, ERROR, LOG and PROVIDER.

Deploy the generated message flows

  1. Create the extra queues (RESPONSE, STORE, and LOG) in MBX:
    Figure 19. Additional queues required by the request-response pattern
    Additional queues required by the request-response pattern
  2. Create a BAR file that includes the generated message flows and deploy to the local broker:
    Figure 20. The pattern instance deployed to the broker
    The pattern instance deployed to the broker

Exercise the generated flows

Now exercise the generated message flows.

  1. Create another Message Broker Test Client file.
  2. You need to configure the message flow to test. Switch to the Configure tab at the bottom of the editor. Click on Message Flows and then click Add.
  3. In the Resources dialog select Request.msgflow and click OK.
  4. Click on Deployment and choose the option to deploy the BAR file manually. You must also select your BAR file by clicking on Browse:
  5. Click on MQ Settings and make sure to deselect Stop when the first MQ message is received. Also select Browse message from MQ output queue. These options specify how the Test Client will react when it sees messages arrive on your ERROR and PROVIDER queues. You are testing the flows through a Web service request and response, so you only want the Test Client to monitor the queues.
  6. Click Start. You will see a similar sequence of events as before. This time however, no reply message is received, because the message flows are waiting for a reply message to arrive on a WebSphere MQ queue before sending the Web service response:
    Figure 21. Exercising the pattern instance with a Message Broker Test Client
    Exercising the pattern instance with a Message Broker Test Client
  7. Switch to MBX and look at the queue activity. You can see that a message has been sent to the PROVIDER, STORE, and LOG queues:
    Figure 22. Queue activity after the Web service request was sent
    Queue activity after the Web service request was sent

The PROVIDER message is the Web service request sent from the Test Client (this behavior is unchanged from the previous one-way pattern). The LOG message is created by the generated message flows whenever a message flow completes.

The key concept in this pattern is to understand that the request and response processing are decoupled. The request message flow receives the Web service request, writes it to the PROVIDER queue and completes (after writing a message to the LOG queue). The response message flow waits on the RESPONSE message queue. When a message arrives, it correlates the request and response messages (this magic is performed using the STORE queue) and sends the reply. When the response message flow finishes processing, it also sends a message to the LOG queue.

In a real deployment, an application would process the messages from the PROVIDER queue and send the responses to the RESPONSE queue. To simulate this behavior you will use rfhutil:

  1. Start rfhutil and enter PATTERNSQMGR for the Queue Manager.
  2. Enter PROVIDER for the Queue Name.
  3. Click on Read Q to read the message from the PROVIDER queue.
  4. Click on the Data tab and you will see the Web service request sent by the Test Client:
    Figure 23. The message written to the PROVIDER queue
    The message written to the PROVIDER queue

    The message on the PROVIDER queue contains a message identifier, which is used by the generated message flows to correlate the requests and responses. The message you will send to the RESPONSE queue must have the same message identifier.

  5. Click on Ids => Save Msg Id to store the PROVIDER message identifier.
  6. Copy-and-paste the following XML into a text file and save it to disk:
    Listing 1. Web services response message
    <test:submitPOResponse xmlns:test="http://www.acmeOrders.com/OrderService">
    <orderStatus>OK</orderStatus>
    <orderAmt>999</orderAmt>
    <partNo>1234</partNo>
    <partQuantity>5</partQuantity>
    </test:submitPOResponse>
  7. On the Main page, click Open File and open the file you just created.
  8. Click Ids => Restore Msg Id to restore the PROVIDER message identifier.
  9. Click on the MQMD tab and check that the message identifier has been restored:
    Figure 24. The RESPONSE message identifier
    The RESPONSE message identifier
  10. On the Main tab and change the Queue Name to RESPONSE.
  11. Click Write Q and switch back to the Test Client Events view:
    Figure 25. Reply message event in the Message Broker Test Client
    Reply message event in the Message Broker Test Client

    You should see that a reply message has been received by the test client. If you have taken more than three minutes between sending the Web service request and writing the response message to the RESPONSE queue, then the Test Client may have timed out. In this case you will need to resend the Web service request and repeat the actions in rfhutil.

  12. Click on Received HTTP Reply message and you will see the following reply message:
    Figure 26. The reply message from the pattern instance
    The reply message from the pattern instance

    This message matches the XML message you saved in the file and wrote to the RESPONSE queue. The response message flow read your message from the RESPONSE queue. The flow matched up the request message it sent to the PROVIDER queue. This magic is done using the STORE queue. The response message flow then sent the reply to the Test Client.

Congratulations! You have successfully created, deployed and exercised the Service Facade to WebSphere MQ: request-response pattern. Now that you have successfully worked with two of the Message Broker patterns, why not take some of the others for a test drive? You might also like to dig into the details of the generated flows that implement the Service Facade to WebSphere MQ: request-response pattern.

Conclusion

In this exercise, you:

  1. Learned about patterns in Message Broker and the Pattern Explorer.
  2. Created a local broker through the new Brokers view.
  3. Created an instance of the Service Facade to WebSphere MQ: one-way with acknowledgement pattern.
  4. Deployed and exercised the pattern using the Message Broker Test Client.
  5. Created an instance of the Service Facade to WebSphere MQ: request-response pattern.
  6. Deployed and exercised the pattern using the Message Broker Test Client and rfhutil.
  7. Created and monitored queues using the Message Broker Explorer (MBX).

Resources

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into WebSphere on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=WebSphere
ArticleID=433617
ArticleTitle=Introduction to patterns in WebSphere Message Broker V7
publish-date=10062009