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.
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:
- Start the Message Broker Toolkit and switch to the Message Broker Application Development perspective.
- In the Brokers view, right-click on Brokers and select New => Local Broker.
- 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.
- Click Finish to create the broker. The broker is displayed in the Brokers view:
Figure 1. The local broker displayed in the Brokers view
- 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.
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 Message Broker patterns are displayed in the Patterns Explorer view. There are several ways to navigate to the Patterns Explorer view:
- Click on the Patterns Explorer tab.
- Click New in the Pattern Instances section of the Broker Development view.
- Click Start from patterns in the Quick Starts section of the Broker Development view:
Figure 3. 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.
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
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:
- At the bottom of the Pattern Configuration editor, click on Specification.
- Scroll down to Related tasks and click on Resources to get you started with the pattern.
- Click on Import the sample resources into your workspace.
- Click through the wizard and a new message set project is created in your workspace. It contains a WSDL file called OrderService.wsdl.
- Switch back to the Configuration tab in the editor and click Browse.
- Select OrderService.wsdl from the list of available WSDL files.
- 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 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
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:
- Switch over to MBX.
- Under the PATTERNSQMGR queue manager, right-click on Queues and select New => Local Queue.
ERRORfor the queue name and click OK.
- Repeat for the second queue called
PROVIDER. You should now have two local queues:
Figure 7. 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:
- Right click on OneWay_Flows and select New => Message Broker Archive.
- Configure the BAR file Project and Name, and click Finish.
- In the BAR file editor; select the message flow and message sets:
Figure 8. Choose the resources for a Message Broker Archive
- Build and save the BAR file. Your message flow is ready to be deployed!
- 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
Message Broker Test Client
To exercise to the Web service, use the Message Broker Test Client:
- Click File => New and select Message Broker Test Client from the Message Broker category.
- 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.
- 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.
- In the Resources dialog, select Request.msgflow and click OK.
- 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
- 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
- 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
- You can see a text version of the request by selecting Edit as text from the dropdown.
- 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
- 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
- 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
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
- 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
- Right-click the message and select Properties => Data. The properties window displays the Web service request that you sent using the Test Client.
- 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.
- Right click on the MQ request-response pattern in the Patterns Explorer and select Create New Instance.
RequestResponsefor the pattern instance name.
- In the Pattern Configuration Editor, click Browse on the Service WSDL and select OrderService.wsdl.
- Select Content and value for the validation parameters. This instructs the generated message flows to validate all Web service requests and responses.
- Open up the Logging section and set Logging required.
- Click Generate to create the pattern instance and generated message flows.
Figure 18. 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
- Create the extra queues (RESPONSE, STORE, and LOG) in MBX:
Figure 19. Additional queues required by the request-response pattern
- 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
Exercise the generated flows
Now exercise the generated message flows.
- Create another Message Broker Test Client file.
- 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.
- In the Resources dialog select Request.msgflow and click OK.
- Click on Deployment and choose the option to deploy the BAR file manually. You must also select your BAR file by clicking on Browse:
- 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.
- 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
- 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
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:
- Start rfhutil and enter
PATTERNSQMGRfor the Queue Manager.
PROVIDERfor the Queue Name.
- Click on Read Q to read the message from the PROVIDER queue.
- 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 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.
- Click on Ids => Save Msg Id to store the PROVIDER message identifier.
- 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>
- On the Main page, click Open File and open the file you just created.
- Click Ids => Restore Msg Id to restore the PROVIDER message identifier.
- Click on the MQMD tab and check that the message identifier has been restored:
Figure 24. The RESPONSE message identifier
- On the Main tab and change the Queue Name to
- Click Write Q and switch back to the Test Client Events view:
Figure 25. 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.
- Click on Received HTTP Reply message and you will see the following reply message:
Figure 26. 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.
In this exercise, you:
- Learned about patterns in Message Broker and the Pattern Explorer.
- Created a local broker through the new Brokers view.
- Created an instance of the Service Facade to WebSphere MQ: one-way with acknowledgement pattern.
- Deployed and exercised the pattern using the Message Broker Test Client.
- Created an instance of the Service Facade to WebSphere MQ: request-response pattern.
- Deployed and exercised the pattern using the Message Broker Test Client and rfhutil.
- Created and monitored queues using the Message Broker Explorer (MBX).
- ESB and connectivity patterns
Learn more about ESB and connectivity patterns at the developerWorks patterns wiki.
- WebSphere Message Broker developer resources page
Technical resources to help you use WebSphere Message Broker for connectivity, universal data transformation, and enterprise-level integration of disparate services, applications, and platforms to power your SOA.
- WebSphere Message Broker product page
Product descriptions, product news, training information, support information, and more.
- WebSphere Message Broker information center
A single Web portal to all WebSphere Message Broker V6 documentation, with conceptual, task, and reference information on installing, configuring, and using your WebSphere Message Broker environment.
- WebSphere Message Broker documentation library
WebSphere Message Broker specifications and manuals.
- WebSphere Message Broker forum
Get answers to your technical questions and share your expertise with other WebSphere Message Broker users.
- WebSphere Message Broker support page
A searchable database of support problems and their solutions, plus downloads, fixes, problem tracking, and more.
- Redbook: Patterns: SOA Design Using WebSphere Message Broker and WebSphere ESB
Patterns for e-business are a group of proven, reusable assets that can be used to increase the speed of developing and deploying e-business applications. This Redbook shows you how to use WebSphere ESB together with WebSphere Message Broker to implement an ESB within an SOA. Includes scenario to demonstrate design, development, and deployment.
- developerWorks WebSphere zone
Technical information and resources for developers who use WebSphere products. developerWorks WebSphere provides product downloads, how-to information, support resources, and a free technical library of more than 2000 technical articles, tutorials, best practices, IBM Redbooks, and online product manuals.
- WebSphere SOA solutions developer resources page
Technical resources for WebSphere SOA solutions.
- developerWorks SOA and Web services zone
Technical resources for evaluating, planning, designing, and implementing solutions that involve SOA and Web services.
- developerWorks WebSphere application connectivity zone
Access to WebSphere application connectivity (formerly WebSphere business integration) how-to articles, downloads, tutorials, education, product info, and more.
- developerWorks WebSphere business process management zone
Access to WebSphere BPM how-to articles, downloads, tutorials, education, product info, and other resources to help you model, assemble, deploy, and manage business processes.
- WebSphere business process management products page
For both business and technical users, a handy overview of all business process management products.
- WebSphere forums
Product-specific forums where you can get answers to your technical questions and share your expertise with other WebSphere users.
- developerWorks blogs
Join a conversation with developerWorks users and authors, and IBM editors and developers.
- developerWorks podcasts
Listen to interesting and offbeat interviews and discussions with software innovators.
- developerWorks on Twitter Check out recent Twitter messages and URLs.
- Most popular WebSphere trial downloads
No-charge trial downloads for key WebSphere products.
- WebSphere on-demand demos
Download, watch, and learn what WebSphere products and WebSphere-related technologies can do for your company.
- Trial downloads for IBM software products
No-charge trial downloads for selected IBM® DB2®, Lotus®, Rational®, Tivoli®, and WebSphere® products.
- WebSphere-related events
Conferences, trade shows, Webcasts, and other events around the world of interest to WebSphere developers.
- developerWorks technical events and Webcasts
Free technical sessions by IBM experts that can accelerate your learning curve and help you succeed in your most difficult software projects. Sessions range from one-hour Webcasts to half-day and full-day live sessions in cities worldwide.
- WebSphere-related books from IBM Press
Convenient online ordering through Barnes & Noble.
Dig deeper into WebSphere on developerWorks
Get samples, articles, product docs, and community resources to help build, deploy, and manage your cloud apps.
Experiment with new directions in software development.
Software development in the cloud. Register today to create a project.
Evaluate IBM software and solutions, and transform challenges into opportunities.