Introduction to pattern authoring in WebSphere Message Broker V7

WebSphere Message Broker V7 Fix Pack 1 introduces pattern authoring, which lets you create your own patterns for sharing and reuse within Message Broker.

Share:

Brian Stewart (bri@uk.ibm.com), Staff Software Engineer, WebSphere Message Broker Test Team, EMC

Photo of Brian StewartBrian Stewart is a software engineer with 12 years experience in software development at the IBM Software Lab in Hursley, United Kingdom. Since joining the lab as a graduate in 1998, he has worked with the CICS and WebSphere product families on distributed and z/OS platforms. He has worked on WebSphere Message Broker for the past six years, most recently specializing in pattern authoring, high availability of multi-instance brokers, Message Broker Explorer, and JDBC XA. You can contact Brian at bri@uk.ibm.com.



06 October 2010

Introduction

A pattern is a reusable solution that encapsulates a tested approach to solving a common architecture, design, or deployment task in a particular context. Patterns typically emerge from common usage and the application of a particular product or technology.

IBM® WebSphere® Message Broker V7 (hereafter called Message Broker) introduced a number of built-in patterns that covered a set of commonly encountered message flow scenarios, two of which were explored in the article Introduction to patterns in WebSphere Message Broker V7. Message Broker Fix Pack 1 extends the pattern functionality by introducing pattern authoring, which lets you create user-defined patterns for Message Broker that can be tailored to the specific requirements of your organization.

Pattern authoring overview

A pattern author creates user-defined patterns to meet business or technical requirements, and a pattern user can configures these user-defined patterns, which are available in the Patterns Explorer, alongside the built-in patterns. To create a user-defined pattern, you must provide an implementation of a solution that reflects good practices in your organization. This implementation is known as an exemplar, which is a project that contributes most of its content to a pattern. An exemplar contains message flows and other resources, such as source code, Java™ classes for JavaCompute nodes, ESQL modules, message maps, a test client, XML files, and style sheet files. Exemplars are used to create pattern plug-ins.

An exemplar is converted into pattern plug-ins by configuring a pattern authoring project. You can use the Pattern Authoring Editor to configure a pattern and create the pattern plug-ins that will implement the pattern. You can then distribute the pattern plug-ins so that your pattern is displayed in the Patterns Explorer view of the Message Broker Toolkit, enabling other people to use your pattern.

Prerequisites

This article assumes a basic familiarity with Message Broker. You will need the Message Broker V7 Fix Pack 1 Toolkit installed on your machine. If you choose to deploy the resources generated by your user-defined pattern, then you will also need to have the Message Broker runtime installed. This article walks you through pattern authoring on the Windows® platform.

What you will learn

In this article you will explore a complete end-to-end pattern authoring scenario within a typical organization, involving two roles -- a pattern author and a pattern user. Each section below identifies which role the steps are applicable to. After the end-to-end scenario for each role, there are sections covering some of the more advanced functions available in pattern authoring, and a section covering the new Solar Pattern Authoring sample.

As the pattern author, for the purpose of this article, you will create a simple message flow and define some target properties in it. It will then be used as the basis for an exemplar that implements it and reflects good practices within the organization. You will create a pattern authoring project and use the Pattern Authoring Editor to configure the user interface and pattern parameters available in the user-defined pattern. You will then create the pattern plug-ins and test them, and finally package and distribute the new pattern plug-ins to the pattern user.

As the pattern user, for the purpose of this article, you will install the pattern plug-ins into the Message Broker toolkit, so that the user-defined pattern appears in the Patterns Explorer view. Then you will create a new instance of the user-defined pattern and customize the pattern parameters. You will then generate and test a pattern instance project containing all the resources required by the user-defined pattern.

Pattern author: Creating a message flow

In this section you will create a message flow that will form the basis of the exemplar. An exemplar is a project that contributes most of its content to a user-defined pattern.

The message flow uses an MQInput node to receive an input message from an MQ queue which is then passed to a Compute node. The ESQL of the Compute node inspects the value of a user defined property (UDP) defined in the message flow to determine which of two MQOutput nodes to route the message to. The output message is then delivered to the corresponding MQ queue.

Create the message flow:

  1. Start the Message Broker toolkit and switch to the Broker Application Development perspective.
  2. Click File => New => Message Flow Project. Enter a name of MyMessageFlowProject for the message flow project and click Finish.
  3. In the Projects section of the Broker Development view, right-click the message flow project => New => Message Flow. Enter a name of MyMessageFlow for the message flow and click Finish.
  4. In the message flow editor node palette, expand the WebSphere MQ category, and drag an MQInput node and two MQOutput nodes onto the message flow canvas.
  5. Expand the Transformation category, and drag a Compute node onto the message flow canvas.
  6. In the message flow editor, wire the Out terminal of the ‘MQ Input’ node to the In terminal of the Compute node.
  7. Wire the Out terminal of the Compute node to the In terminal of the MQ Output node.
  8. Wire the Out1 terminal of the Compute node to the In terminal of the MQ Output1 node.
  9. Right-click the MQ Input node => Properties. Enter a Queue name of IN.
  10. Right-click the MQ Output node => Properties. Enter a Queue name of OUT.
  11. Right-click the MQ Output1 node => Properties. Enter a Queue name of OUT1.
  12. Press Ctrl +S to save the message flow. The message flow is shown in Figure 1.
Figure 1. The message flow created by the pattern author.
A message flow showing an MQInput node wired to a Compute node wired to two MQOutput nodes

Add a UDP to the message flow. This will store the value that determines which output terminal the Compute node will route the incoming message to:

  1. Click the User Defined Property tab of the message flow.
  2. Right-click Basic => Add Property.
  3. Enter ‘OutTerminal’ as the name of the UDP.
  4. Change the Type of the UDP to Integer using the drop down list.
  5. Enter 0 as the Default Value of the UDP.
  6. Click the Graph tab of the message flow.
  7. Press Ctrl +S to save the message flow.

Create the ESQL for the Compute node. This routes the incoming message to the output terminal specified by the value of the UDP OutTerminal:

  1. Double click the Compute node in the message flow to open the file MyMessageFlow.esql in the ESQL editor.
  2. Edit the ESQL as shown in Listing 1 below. This can be copied and pasted if you prefer.
  3. Press Ctrl +S to save the file MyMessageFlow.esql.
Listing 1. Code listing for MyMessageFlow.esql
CREATE COMPUTE MODULE MyMessageFlow_Compute
    -- Define the variable to hold the value of the UDP 'OutTerminal'.
    -- Give a default value of 0, in case no UDP with that name was defined.
    DECLARE OutTerminal EXTERNAL INTEGER 0;

    CREATE FUNCTION Main() RETURNS BOOLEAN
    BEGIN
        CALL CopyMessageHeaders();
        CALL CopyEntireMessage();
        -- When OutTerminal = 0, message propagated to Out terminal.
        -- When OutTerminal = 1, message propagated to Out1 terminal.
        PROPAGATE TO TERMINAL OutTerminal;
        
        RETURN TRUE;
    END;

    CREATE PROCEDURE CopyMessageHeaders() BEGIN
        DECLARE I INTEGER 1;
        DECLARE J INTEGER;
        SET J = CARDINALITY(InputRoot.*[]);
        WHILE I < J DO
            SET OutputRoot.*[I] = InputRoot.*[I];
            SET I = I + 1;
        END WHILE;
    END;

    CREATE PROCEDURE CopyEntireMessage() BEGIN
        SET OutputRoot = InputRoot;
    END;
END MODULE;

Pattern author: Defining the target properties for the message flow

In this section you will define the target properties for the message flow. A target property is a message flow property (node, promoted node or UDP) that can be configured by a pattern. The target properties defined in this article will consist of the input queue name, an output queue name and the UDP created earlier.

Define the target property for the input queue of the ‘MQ Input’ node:

  1. In the message flow editor, right-click the MQInput node => Pattern => Select Target Properties. The Select Target Properties window opens.
  2. Expand the Basic category by clicking the + twisty, then select Queue name. This property will be used in the user-defined pattern.
  3. Close the Select Target Properties window. An icon appears above a node when one or more target properties have been defined for it, as shown in Figure 2. You can click on this icon to open the Select Target Properties window for that node if necessary.
Figure 2. A node with one or more target properties defined.
A node with an icon displayed above it to indicate that one or more target properties are defined

Define the target property for the output queue of the ‘MQ Output’ node:

  1. Right-click the MQOutput node => Pattern => Select Target Properties. The Select Target Properties window opens.
  2. Expand the Basic category by clicking the + twisty, then select Queue name. This property will be used in the user-defined pattern.
  3. Close the Select Target Properties window. An icon appears above the MQOutput node to show that a target property has been defined for it.

Define the target property for the UDP ‘OutTerminal’:

  1. Right-click the message flow canvas => Pattern => Select Target Properties. The Select Target Properties window opens.
  2. Expand the Basic category by clicking the + twisty, then select OutTerminal. This property will be used in the user-defined pattern.
  3. Close the Select Target Properties window. An icon appears at the top left former of the message flow canvas to show that a target property has been defined for a UDP, or a promoted node property.
  4. Press Ctrl +S to save the message flow.

Pattern author: Creating the pattern authoring project

In this section you will create a pattern authoring project that will be used to convert the exemplar into pattern plug-ins.

  1. Click File => New => Pattern Authoring Project. The New Pattern Authoring Project wizard opens.
  2. Enter a name of MyPattern for the user-defined pattern, and MyPatternProject for the pattern authoring project. Click Next.
  3. Select the project reference for the message flow project created earlier.
  4. Click Finish.

Your pattern folder is displayed in the Projects section of the Broker Development view and the user-defined pattern opens in the Pattern Authoring editor.

Pattern author: Selecting the source files for the user-defined pattern

In this section you will select the source files to include in your user-defined pattern.

  1. In the Pattern Authoring editor, click the Source Files tab of the MyPattern pattern.
  2. In the Select Source Files section, select the source files in the referenced projects that you want to include in your pattern. Ensure that files shown in Figure 3 are selected. The .project file should always be selected for each project.
  3. Press Ctrl +S to save the user-defined pattern.
Figure 3. The selection of source files for the user-defined pattern.
The source files selected for MyMessageFlowProject are: .project, MyMessaageFlow.esql and MyMessageFlow.msgflow

Pattern author: Defining the user interface and configuring pattern parameters used in the user-defined pattern

In this section you will define the user interface and configure the pattern parameters to control how pattern users will view and edit the pattern parameters in the Pattern Instance editor.

Group the similar pattern parameters for the queue names together:

  1. In the Pattern Authoring editor, click the Pattern Parameters tab of the MyPattern pattern. The three target properties that you defined earlier are displayed in the Groups and Parameters box. Each target property is assigned to a default parameter and default group, which are named according to the target property and node name respectively. For example, the target property for the input queue of the MQ Input node appears as MyMessageFlowProject.MyMessageFlow.MQ_Input.queueName. This target property is associated by default with a parameter called Queue name, which in turn is associated by default with a group called MQ_Input. The target property can instead be associated with a different parameter by dragging and dropping it onto the new parameter. Similarly, a parameter can be associated with a different group by dragging and dropping it onto the new group. The parameter and group names can also be renamed. All of this editing can be done in the Pattern Parameters tab of the Pattern Authoring Editor.
  2. Drag the Queue name parameter under MQ_Output group and drop it onto the MQ_Input group. The Queue name parameter for the MQ Output node appears above the Queue name parameter for the MQ_Input node.
  3. Click the Queue name parameter for the MQ_Output node, then click Down button on the right, to move this parameter below the Queue name parameter for the MQ_Input node.
  4. Click the empty MQ_Output group and then click Delete.

Rename the pattern parameters and groups and enter simple help text for the parameters and more meaningful descriptions for the groups:

  1. Double-click on the MQ_Input group. The Edit Group window is displayed.
  2. Enter a display name of Queue names.
  3. Enter a description of The queue names for the MQ nodes.
  4. Click OK.
  5. Double click on the Queue name parameter for the MQ_Input node. The Edit Parameter window is displayed.
  6. Enter a display name of MQ Input node.
  7. Enter some help text for the parameter such as <p>This parameter specifies the input queue name for the MQ Input node.</p>.
  8. Click OK.
  9. Double click on the Queue name parameter for the MQ_Output node. The Edit Parameter window is displayed.
  10. Enter a display name of MQ Output node.
  11. Enter some help text for the parameter such as <p>This parameter specifies the output queue name for the MQ Output node.</p>.
  12. Click OK.
  13. Double-click on the UserDefinedProperty group. The Edit Group window is displayed.
  14. Enter a display name of UDP.
  15. Enter a description of The UDP that determines which output terminal the Compute node routes incoming messages to.
  16. Click OK.
  17. Double click on the Out terminal parameter. The Edit Parameter window is displayed.
  18. Enter a display name of OutTerminal.
  19. Enter some help text for the parameter such as <p>This parameter specifies which output terminal the Compute node routes incoming messages to. A value of 0 routes to the MQ Output node, a value of 1 routes to the MQ Output1 node.</p>.
  20. Click OK.
  21. The pattern groups and parameters are shown in Figure 4.
Figure 4. The pattern groups and parameters for the user-defined pattern.
The pattern groups and parameters showing two queue name parameters in one group, and one UDP parameter in another group

The following examples cover some basic configurations for pattern parameters -- more advanced features when extending a user-defined pattern, such as the use of enumerated types and transformation of pattern parameters using XPath, are covered in later sections of this article.

Define watermarks for the queue name pattern parameters:

  1. In the Pattern Authoring editor, click the Pattern Parameters tab of the MyPattern pattern.
  2. Double-click on the MQ Input node parameter. The Edit Parameters window is displayed.
  3. Enter a watermark of Please enter the name of the input queue.
  4. Click OK.
  5. Double-click on the MQ Output node parameter. The Edit Parameters window is displayed.
  6. Enter a watermark of Please enter the name of the output queue.
  7. Click OK.

Define a default value for the OutTerminal parameter:

  1. Double-click on the OutTerminal parameter. The Edit Parameters window is displayed.
  2. Click on the Editor tab.
  3. Enter a default value of 0.
  4. Click OK.
  5. Press Ctrl +S to save the user-defined pattern.

Pattern author: Creating a new category and assigning the user-defined pattern to it

In this section you will create a new category and assign your user-defined pattern to it. These will appear in Patterns Explorer view when the pattern user installs the pattern plug-ins.

Create a new pattern category:

  1. In the Pattern Authoring editor, click the Categories tab of the MyPattern pattern.
  2. Click Add Category. The Add Category window opens.
  3. Enter MyPatternCategory as the category name.
  4. Click OK.
  5. Click Yes to save the user-defined pattern.

Assign the user-defined pattern to the new category:

  1. Drag the MyPattern pattern on to the MyPatternCategory category.
  2. Press Ctrl +S to save the user-defined pattern.

Pattern author: Editing the pattern and category specifications to document the user-defined pattern

In this section you will edit the pattern specification and category specification to document your user-defined pattern.

When you create a pattern authoring project a default HTML pattern specification (overview.htm) is created as part of the project, in a folder called Pattern Specification. The pattern author can modify this HTML file, and add extra HTML files, images and style sheets if required.

Similarly, when you create a category a default HTML category specification (overview.htm) is created within a folder structure of Category Specification/<category name> within the pattern authoring project. Again, the pattern author can modify this HTML file, and add extra HTML files, images and style sheets if required.

Edit the pattern specification:

  1. Open the Projects section of the Broker Development view.
  2. Expand MyPatternProject, and expand the Pattern Specification folder.
  3. Right-click overview.htm and select Open With => HTML Editor. The default user-defined pattern specification is shown in the HTML editor.
  4. Edit the content of the pattern specification in the HTML editor.
  5. Press Ctrl +S to save the pattern specification.
  6. To view the updated pattern specification, click the Categories tab of the Pattern Authoring editor.

Edit the category specification:

  1. Open the Projects section of the Broker Development view.
  2. Expand MyPatternProject, then expand the Category Specification folder and then expand the MyPatternCategory folder.
  3. Right-click overview.htm and select Open With => HTML Editor. The default user-defined pattern specification is shown in the HTML editor.
  4. Edit the content of the category specification in the HTML editor.
  5. Press Ctrl +S to save the category specification.
  6. To view the updated category specification, click the Categories tab of the Pattern Authoring editor.

Pattern author: Creating the pattern plug-ins for the user-defined pattern

In this section you will create the pattern plug-ins for your user-defined pattern that can then be tested and distributed to the pattern user.

  1. In the Pattern Authoring editor, click the Create pattern tab of the MyPattern pattern.
  2. Edit the Plug-in Information fields as shown in Figure 5. The Pattern name displayed is the name you entered for the pattern when you created the pattern authoring project. Edit values in the Plug-in ID and Version fields according to the naming and version numbering conventions within your organization. See the Resources section for links on naming and version numbering conventions for Eclipse plug-ins. Edit the Provider field for the name of your organization. Edit the Description field to describe the pattern.
    Figure 5. Plug-in information for the user-defined pattern
    The plug-in information showing pattern name, plug-in ID, version, provider and description
  3. Click Create Pattern Plug-ins. The plug-ins for your user-defined pattern are created and displayed in the Projects section of the Broker Development view as shown in Figure 6.
    Figure 6. The pattern plug-ins are highlighted in red.
    The highlighted plug-ins are my.company.MyPatternProject and my.company.MyPatternProject.doc

Pattern author: Testing the user-defined pattern

In this section you will test the user-defined pattern before it is distributed to the pattern user. You will launch a new workbench with the user-defined pattern installed, view it in the Patterns Explorer view, create a new instance of it, customize the pattern parameters, generate a new pattern instance and then inspect the generated resources.

Launching a workbench from the pattern authoring editor gives a quick and easy way of testing the user-defined pattern without the need to package and distribute the pattern plug-ins and then install them into a Message Broker toolkit. Instead, the workbench launches with the pattern plug-ins already installed, so the pattern author can begin testing the user-defined pattern right away.

  1. In the Pattern Authoring editor, click the Create pattern tab of the ‘MyPattern’ pattern.
  2. Click Launch Workbench. A new Message Broker Toolkit opens with a workspace of your choice.
  3. Click the Patterns Explorer tab in the Broker Development view. The new pattern MyPattern is displayed under the new category MyPatternCategory in the Patterns Explorer view.
  4. Click MyPatternCategory. The category specification you edited above appears.
  5. Click MyPattern. The pattern specification you edited above appears.
  6. Click Create New Instance. The New Pattern Instance window appears.
  7. Enter a name of MyPatternInstance and click OK. The Pattern Instance editor opens.
  8. Expand Queue names and UDP for the Pattern Parameters section. The Pattern Instance editor shows a warning that one or more mandatory parameters are not set (the queue names). A default value of 0 is set for the OutTerminal parameter, as shown in Figure 7.
    Figure 7. The Pattern Instance editor.
    The pattern instance editor showing two mandatory values still to be set for queue names, and a default value of 0 for the UDP
  9. Expand ‘Queue names’ and ‘UDP’ for the Pattern Parameters Details section. The help text for the parameters that you entered above appears, as shown in Figure 8.
    Figure 8. Help text for the queue name pattern parameters.
    Help text displayed for the queue name pattern parameters
  10. Enter a queue name of MYPATTERN.IN.QUEUE for the MQ Input node.
  11. Enter a queue name of MYPATTERN.OUT.QUEUE for the MQ Output node. The warning about a mandatory parameter with no value set disappears.
  12. Enter a value of 1 for the OutTerminal (replacing the default value of 0).
  13. Click Generate to generate a new pattern instance. Focus is automatically moved to the Broker Development view, which lists the new resources that have been generated in the MyPatternInstance working set. All other resources that exist in the current workspace are filtered out in this view.
  14. Expand MyPatternInstance_MyMessageFlowProject, then expand Flows, then expand the default broker schema, and double-click on MyMessageFlow to open it in the message flow editor.
  15. Right-click on the MQ Input node => Properties. The Queue name property has been set to ‘MYPATTERN.IN.QUEUE’. In the original message flow you created above this was set to ‘IN’.
  16. Right-click on the MQ Output node => Properties. The Queue name property has been set to ‘MYPATTERN.OUT.QUEUE’. In the original message flow you created above this was set to ‘OUT’.
  17. Click the User Defined Properties tab of the message flow editor.
  18. Click OutTerminal. The Default Value has been set to ‘1’. In the original message flow you created above this was set to ‘0’.

You can now go on and test your generated message flow further if you wish by deploying it to a broker and sending a test message through the message flow. Note that resources such as MQ queues are not created automatically when a pattern instance is generated or deployed. They should be created manually in the usual way.

If you want to change your user-defined pattern, ensure that you go back and change the pattern authoring project and then re-create the pattern plug-ins and test them again - do not make your changes by editing the generated resources.

When you are done testing the pattern plug-ins, close the launched workbench.

Pattern author: Packaging and distributing the pattern plug-ins to the pattern user

In this section you will package and distribute the pattern plug-ins to the pattern user.

  1. Close the launched workbench session you used for testing the pattern plug-ins if it is still open.
  2. Go back to the original Message Broker toolkit session and click File => Export. The Export window opens.
  3. Expand General. Select Archive File. Click Next.
  4. In the left window, select the two pattern plug-ins to export as shown in Figure 9.
  5. Enter a file name for the archive file as shown in Figure 9. If you like, you can click Browse, select a folder for the archive file, and enter a file name for the archive file in the File name field, then click Save.
    Figure 9. Choosing the pattern plug-ins for export to an archive file.
    The export wizard showing the pattern plug-ins to be exported to a specified archive file
  6. Click Finish. The archive file is created. If the target directory does not exist you are asked if you would like to create it.
  7. You can now distribute the archive file directly to the pattern user.
  8. (Optional) You may decide to distribute your pattern plug-ins using an Eclipse update site. See the Resources section for a link.

Pattern user: Installing the pattern plug-ins distributed by the pattern author

In this section you will install the pattern plug-ins that you received from the pattern author. This article covers the best practice method of doing this using Eclipse link files that point to the directories in which you maintain your plug-in files.

  1. Create a directory called ‘eclipse’ in your chosen location on your file system, for example: C:\MyPlugins\eclipse
  2. Within the eclipse directory, create two directories named features and plugins, for example: C:\MyPlugins\eclipse\features
    C:\MyPlugins\eclipse\plugins
  3. Extract the .zip archive file provided by the pattern author into the plugins sub-folder, for example: C:\MyPlugins\eclipse\plugins
  4. Under the Toolkit directory, C:\Program Files\IBM\WMBT700, create a new links directory, for example: C:\Program Files\IBM\WMBT700\links
  5. Under the new links directory, create a text file of any name with a .link extension. This will be the Eclipse link file. For example: C:\Program Files\IBM\WMBT700\links\MyPlugins.link
  6. Type the following text into the Eclipse link file, which identifies the path to the directory that contains the eclipse directory (note the forward slashes even on Windows): path=C:/MyPlugins
  7. Restart the Message Broker toolkit session for the changes to take effect.

An alternative way to install the pattern plug-ins is to simply extract the .zip archive file provided by the pattern author directly into the Toolkit 'plugins' directory, for example: C:\Program Files\IBM\WMBT700\plugins, and then restart the Message Broker toolkit session. However, if you choose this option you may find it difficult to manage your plug-ins files safely if you later remove or replace them. Also, your system administrator might want to control security and access on computers that are used by more than one user, and might not set permissions for users to write to the primary installation directories.

Pattern user: Viewing the user-defined pattern and creating a new instance

In this section you will view the user-defined pattern in the Patterns Explorer and then create a new instance of it.

  1. Click the Patterns Explorer tab in the Broker Development view. The user-defined pattern MyPattern is displayed under the category MyPatternCategory in the Patterns Explorer view.
  2. Click MyPatternCategory. The category specification is displayed.
  3. Click MyPattern. The pattern specification is displayed.
  4. Click Create New Instance. The New Pattern Instance window appears.
  5. Enter a name of MyPatternInstance and click OK. The Pattern Instance editor opens.

Pattern user: Customizing the pattern parameters and generating the resources

In this section you will customize the pattern parameters and generate the resources from the user-defined pattern.

  1. Enter a name of MyPatternInstance and click OK. The Pattern Instance editor opens.
  2. Expand Queue names and UDP for the Pattern Parameters section. The Pattern Instance editor shows a warning that one or more mandatory parameters are not set (the queue names). A default value of 0 is set for the OutTerminal parameter, as shown in Figure 7 above.
  3. Expand Queue names and UDP for the Pattern Parameters Details section. The help text for the parameters appears, as shown in Figure 8 above.
  4. Enter a queue name of MYPATTERN.IN.QUEUE for the MQ Input node.
  5. Enter a queue name of MYPATTERN.OUT.QUEUE for the MQ Output node. The warning about a mandatory parameter with no value set disappears.
  6. Enter a value of 1 for the OutTerminal (replacing the default value of 0).
  7. Click Generate to generate a new pattern instance. Focus is automatically moved to the Broker Development view, which lists the new resources that have been generated in the MyPatternInstance working set. All other resources that exist in the current workspace are filtered out in this view.

Pattern user: Testing the generated resources

In this section you will inspect the resources that were generated from the user-defined pattern.

  1. Expand MyPatternInstance_MyMessageFlowProject, then expand Flows, then expand the default broker schema, and double-click on MyMessageFlow to open it in the message flow editor.
  2. Right-click on the MQ Input node => Properties. The Queue name property has been set to MYPATTERN.IN.QUEUE. In the original message flow you created above this was set to ‘IN’.
  3. Right-click on the MQ Output node => Properties. The Queue name property has been set to MYPATTERN.OUT.QUEUE. In the original message flow you created above this was set to ‘OUT’.
  4. Click the User Defined Properties tab of the message flow editor.
  5. Click OutTerminal. The Default Value has been set to ‘1’. In the original message flow you created above this was set to ‘0’.

You can now go on and test your generated message flow further if you wish by deploying it to a broker and sending a test message through the message flow. Note that resources such as MQ queues are not created automatically when a pattern instance is generated or deployed. They should be created manually in the usual way.

Pattern user: Uninstalling the pattern plug-ins

In this section you will learn how to uninstall pattern plug-ins for user-defined patterns that you have previously installed. Uninstalling pattern plug-ins removes the associated user-defined pattern from the Patterns Explorer view. The steps to uninstall pattern plug-ins depend on the method used to install them. Each user-defined pattern has more than one plug-in directory; to uninstall plug-ins you must know the directory names of the plug-ins to ensure that the correct user-defined pattern is removed.

To remove pattern plug-ins installed using an Eclipse link file:

  1. Close the Message Broker toolkit.
  2. Delete the pattern plug-ins from the plugins directory that is pointed to by your Eclipse link file, for example:
    C:\MyPlugins\eclipse\plugins\my.company.MyPatternProject
    C:\MyPlugins\eclipse\plugins\my.company.MyPatternProject.doc
  3. For completeness, if you do not intend to install more pattern plug-ins in the future, you may also wish to delete the other files and directories that were created too, for example:
    C:\Program Files\IBM\WMBT700\links\MyPlugins.link
    C:\Program Files\IBM\WMBT700\links
    C:\MyPlugins\eclipse\plugins
    C:\MyPlugins\eclipse\features
    C:\MyPlugins\eclipse
  4. Start the Message Broker toolkit and click the Patterns Explorer tab in the Broker Development view. The user-defined pattern no longer appears in the Patterns Explorer.

To remove pattern plug-ins installed by extracting the archive file directly into the Toolkit plugins directory:

  1. Close the Message Broker toolkit.
  2. Delete the pattern plug-ins from the Toolkit plugins directory, for example:
    C:\Program Files\IBM\WMBT700\plugins\my.company.MyPatternProject
    C:\Program Files\IBM\WMBT700\plugins\my.company.MyPatternProject.doc
  3. Start the Message Broker toolkit and click the Patterns Explorer tab in the Broker Development view. The user-defined pattern no longer appears in the Patterns Explorer.

Pattern author advanced topic: Extending the user-defined pattern to use an enumerated type for a pattern parameter

In this section you will extend the user-defined pattern you created above by defining an enumerated type that will be used by the OutTerminal pattern parameter when the pattern user chooses a value for the output terminal that the Compute node in the message flow will route the incoming message to. You will then re-create the pattern plug-ins.

An enumerated type is a set of values that a pattern parameter accepts. In this case, there will be a choice of two values: MQ Output or MQ Output1, which under the covers will represent a 0 (and in turn the Out terminal that flows to node MQ Output) or a 1 (and in turn the Out1 terminal that flows to the node MQ Output1) respectively. The use of an enumerated type here gives the pattern user a more informed choice of which node the Compute node will route the incoming message to.

Define the enumerated type that can be used by any of the pattern parameters:

  1. In the Pattern Authoring editor, click the Pattern Parameters tab of the MyPattern pattern.
  2. Click Enumerated Types. The Configure Enumerated Types window opens.
  3. Click Add under the Enumerated type field. The Enter New Enumeration window opens.
  4. Enter Output node as the name for the enumeration in the Enter a name for the enumeration field. Click OK. The new enumeration is displayed in the table of values, and a display name and default value are entered in the top row of the table.
  5. Click Add next to the table of values to add another row to the table. A new display name and value are added to the table.
  6. Double-click the first display name in the table to edit it. Delete Display Name1 and enter MQ Output. Press Enter.
  7. Double-click the first value in the table to edit it. Delete value_1 and enter 0. Press Enter.
  8. Double-click the second display name in the table to edit it. Delete Display Name2 and enter MQ Output1. Press Enter.
  9. Double-click the second value in the table to edit it. Delete value_2 and enter 1. Press Enter.
  10. The configuration for the enumerated type is shown in Figure 10.
    Figure 10. The enumerated type Output node.
    The enumerated type Output node showing that the value of MQ Output is 0, and for MQ Output1 is 1
  11. Click OK. The Configure Enumerated Types window closes.
  12. Press Ctrl +S to save the user-defined pattern.

Edit the pattern parameter OutTerminal to use the enumerated type you defined:

  1. In the Pattern Authoring editor, click the Pattern Parameters tab of the MyPattern pattern.
  2. Double-click the OutTerminal pattern parameter. The Edit Parameter window opens.
  3. Click on the Editor tab. In this tab you can choose what editor is used for the parameter.
  4. In the Parameter editor field, click on the drop down list and select Drop Down Selection.
  5. In the Enumerated type field, ensure that Output node is selected.
  6. In the Default value field, select which output node (MQ Output or MQ Output1) the Compute node will route the incoming message to, as shown in Figure 11.
    Figure 11. The Edit Parameter wizard showing the OutTerminal pattern parameter.
    The Edit Parameter wizard showing that enumerated type 'Output node' uses a Drop Down Selection, and has a default valueof MQ Output
  7. Click OK. The Edit Parameter window closes.
  8. Press Ctrl +S to save the user-defined pattern.

To re-create the pattern plug-ins:

  1. In the Pattern Authoring editor, click the Create Pattern tab of the MyPattern pattern.
  2. Edit the Version field and increment the version number as shown in Figure 12.
    Figure 12. Plug-in information for the user-defined pattern - V.1.0.0.1.
    The plug-in information showing pattern name, plug-in ID, version, provider and description
  3. Click Create Pattern Plug-ins, and click OK to confirm deletion of the existing pattern plug-ins in your workspace. The new plug-ins for your user-defined pattern are created and displayed in the Projects section of the Broker Development view as shown in Figure 6 above.

To test the change to the user-defined pattern:

  1. In the Pattern Authoring editor, click the Create pattern tab of the MyPattern pattern.
  2. Click Launch Workbench. A new Message Broker Toolkit opens with a workspace of your choice.
  3. Click the Patterns Explorer tab in the Broker Development view. The new pattern MyPattern is displayed under the new category MyPatternCategory in the Patterns Explorer view.
  4. Click MyPattern. The pattern specification appears.
  5. Click Create New Instance. The New Pattern Instance window appears.
  6. Enter a name of MyPatternInstance2 and click OK. The Pattern Instance editor opens.
  7. Expand Queue names and UDP for the Pattern Parameters section. The Pattern Instance editor shows a warning that one or more mandatory parameters are not set (the queue names). A default value of MQ Output is set for the OutTerminal parameter, and it is a drop-down selection rather than a text editor field, as shown in Figure 13. You can compare it to how it looked before in Figure 7 above.
    Figure 13. Pattern Instance editor showing enumerated type for the OutTerminal pattern parameter.
    The Pattern Instance editor showing enumerated type Output node for the OutTerminal pattern parameter

You can now generate the resources for the pattern as before, and see that the OutTerminal UDP is set to either 0 or 1, depending on whether you chose MQ Output or MQ Output1 respectively. You can test your generated message flow further if you wish by deploying it to a broker and sending a test message through the message flow.

Pattern author advanced topic: Extending the user-defined pattern to transform a pattern parameter

You can transform pattern parameters by using XPath expressions, for example, to calculate a pattern parameter value from the values entered for other pattern parameters. XPath is used here as a general purpose expression language, not for querying an XML tree. For XPath reference information, including information on XPath functions, see W3C XPath 1.0 Specification. The pp:getValue() function is included in addition to those in the XPath 1.0 Specification. This function takes the parameter identifier of a pattern parameter and returns the value of that pattern parameter.

In this section you will extend the user-defined pattern to transform the MQ Input node pattern parameter. When a pattern user enters a value in the pattern configuration window for this parameter, for example INPUT, the value of the parameter will be transformed to MYPATTERN.INPUT.QUEUE. To achieve this, two new pattern parameters will be defined to provide the prefix MYPATTERN. and suffix .QUEUE for the queue names.

Define two new pattern parameters:

  1. In the Pattern Authoring editor, click the Pattern Parameters tab of the ‘MyPattern’ pattern.
  2. Click the ‘Queue names’ group.
  3. Click Add Parameter. The Add Parameter window opens.
  4. Enter a Display name of ‘Prefix’.
  5. Enter some help text for the parameter such as <p>This value will be prefixed to the queue name.</p>.
  6. Enter a watermark of Enter a prefix for the queue name.
  7. Click the Editor tab.
  8. Enter a default value of MYPATTERN.
  9. Click OK. The Add Parameter window closes.
  10. Click Add Parameter. The Add Parameter window opens.
  11. Enter a Display name of Suffix.
  12. Enter some help text for the parameter such as <p>This value will be suffixed to the queue name.</p>.
  13. Enter a watermark of Enter a suffix for the queue name.
  14. Click the Editor tab.
  15. Enter a default value of .QUEUE.
  16. Click OK. The Add Parameter window closes.
  17. Click the ‘Prefix’ parameter.
  18. Click the Up button twice to move Prefix to the top of the parameters, under the Queue names group, as shown in Figure 14.
    Figure 14. The order of pattern parameters in the ‘Queue names’ group is shown.
    The Pattern Parameters tab showing order that parameters will be shown in
  19. Press Ctrl +S to save the user-defined pattern.

Edit the MQ Input node pattern parameter to be transformed:

  1. Double-click the MQ Input node parameter. The Edit Parameter window opens.
  2. Click the Transform tab.
  3. Expand String in the Functions box.
  4. Double-click the concat function. In the Expression field near the bottom of the window, concat() is displayed, and the cursor is placed in-between the parentheses.
  5. Click the Prefix parameter in the Pattern Parameters box. The default value of MYPATTERN is displayed in the Test value field.
  6. Click Use. The pp:getValue(pp4) function is added to the Expression field, where pp4 is the Parameter ID of the Prefix parameter, as displayed in the Pattern Parameters box. The pp:getValue() function takes the parameter identifier of a pattern parameter and returns the value of that pattern parameter. In this case, when resolved, that would be MYPATTERN.
  7. Enter a comma in the Expression field where the cursor has been placed, before the closing parenthesis.
  8. Click the MQ Input node parameter in the Pattern Parameters box.
  9. Enter INPUT in the Test value field (note that no default value appeared because there was no default value set when the pattern parameter was created above).
  10. Click Set. A Test Value of INPUT is displayed on the row for the MQ Input node parameter.
  11. Click Use. The pp:getValue(pp1) function is added to the Expression field, where pp1 is the Parameter ID of the ‘MQ Input node’ parameter.
  12. Enter a comma in the Expression field where the cursor has been placed, before the closing parenthesis.
  13. Click the Suffix parameter in the Pattern Parameters box. The default value of .QUEUE is displayed in the Test value field.
  14. Click Use. The pp:getValue(pp5) function is added to the Expression field, where pp5 is the Parameter ID of the Suffix parameter.
  15. Click Evaluate. The result of the expression (MYPATTERN.INPUT.QUEUE) is displayed in the Result field, as shown in Figure 15, which also shows the Pattern Parameters box.
    Figure 15. The Edit Parameters window showing how the MQ Input node pattern parameter will be transformed.
    The Edit Parameters window showing the expression and the result
  16. Click OK. The Edit Parameter window closes.
  17. Press Ctrl +S to save the user-defined pattern.

To re-create the pattern plug-ins:

  1. In the Pattern Authoring editor, click the Create Pattern tab of the MyPattern pattern.
  2. Edit the Version field and increment the version number to 1.0.0.2.
  3. Click Create Pattern Plug-ins, and click OK to confirm deletion of the existing pattern plug-ins in your workspace. The new plug-ins for your user-defined pattern are created and displayed in the Projects section of the Broker Development view as shown in Figure 6 above.

To test the change to the user-defined pattern:

  1. In the Pattern Authoring editor, click the Create pattern tab of the MyPattern pattern.
  2. Click Launch Workbench. A new Message Broker Toolkit opens with a workspace of your choice.
  3. Click the Patterns Explorer tab in the Broker Development view. The new pattern MyPattern is displayed under the new category MyPatternCategory in the Patterns Explorer view.
  4. Click MyPattern. The pattern specification appears.
  5. Click Create New Instance. The New Pattern Instance window appears.
  6. Enter a name of MyPatternInstance3 and click OK. The Pattern Instance editor opens.
  7. Expand Queue names and UDP for the Pattern Parameters section. The Pattern Instance editor shows a warning that one or more mandatory parameters are not set (the queue names). Notice now the two new Prefix and Suffix pattern parameters with their default values, as shown in Figure 16. You can compare it to how it looked before in Figure 13 above.
    Figure 16. The Pattern Instance editor showing the new Prefix and Suffix pattern parameters.
    The Pattern Instance editor showing the new Prefix and Suffix pattern parameters

You can now generate the resources for the pattern as before, and see that the queue name for the MQ Input node (pattern parameter MQ Input node) has been transformed from the value you entered (for example, INPUT) to the new value (for example, MYPATTERN.INPUT.QUEUE). You can test your generated message flow further if you wish by deploying it to a broker and sending a test message through the message flow.

The Solar Pattern Authoring sample

WebSphere Message Broker V7 Fix Pack 1 includes the new Solar Pattern Authoring sample, which shows you how to create a user-defined pattern. The sample provides a sample message flow project that calculates the sunrise and sunset times in a PHPCompute node. The sample also provides a pattern authoring project that configures a pattern, plus associated documentation. In this section you will learn where to find the sample so that you can follow its documentation and import it into your toolkit workspace.

  1. Start the Message Broker toolkit.
  2. Click Help => Samples and Tutorials => WebSphere Message Broker Toolkit - Message Broker. The Samples Gallery opens.
  3. Expand Application Samples.
  4. Scroll down and look for the Solar Pattern Authoring sample. If it is not present then scroll back to the top and click Retrieve, and follow the prompts to refresh the list of available samples.
  5. Click More information under the heading Solar Pattern Authoring sample. A new window opens displaying the documentation for the sample.

You can follow the documentation for the sample to read more about it, and then import the sample into your toolkit workspace in the normal way.

Conclusion

In this exercise, you learned about pattern authoring and created a user-defined pattern. As the pattern author, you:

  • Created a message flow
  • Defined the target properties for the message flow
  • Created the pattern authoring project
  • Selected the source files for the user-defined pattern
  • Define the user interface and configure pattern parameters used in the user-defined pattern
  • Created a new category and assigned the user-defined pattern to it
  • Edited the pattern and category specifications to document the user-defined pattern
  • Created the pattern plug-ins for the user-defined pattern
  • Tested the user-defined pattern
  • Packaged and distributed the pattern plug-ins to the pattern user

As the pattern user, you:

  • Installed the pattern plug-ins distributed by the pattern author
  • Viewed the user-defined pattern in the Patterns Explorer
  • Created a new instance of the user-defined pattern
  • Customized the pattern parameters of the user-defined pattern
  • Tested the generated resources
  • Uninstalled the pattern plug-ins

You also learned some advanced topics related to pattern authoring:

  • How to extend the user-defined pattern to use an enumerated type for a pattern parameter
  • How to extend the user-defined pattern to transform a pattern parameter
  • Where to find the Solar Pattern Authoring sample and its documentation

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=549676
ArticleTitle=Introduction to pattern authoring in WebSphere Message Broker V7
publish-date=10062010