Advanced Pattern Authoring with WebSphere Message Broker

Ant Phillips
antphill@uk.ibm.com

WebSphere Message Broker
Advanced Pattern Authoring

© 2012 IBM Corporation

Round Tripping


Customising Pattern Instances

 The message flow below shows a familiar pattern authoring approach:

 Subflows clarify where pattern users should add their customisations
– Defines a design contract between the generated flows and the pattern user
– This contract ensures the pattern user does not break the generated flows
– Pattern users can extend their pattern instances in many different directions!
• Message maps, PHP scripts, Java, XSLT, message definitions and much more

 However, everything is deleted when a pattern instance is re-generated!
– Re-generation is a common task as a pattern user explores a pattern
A clean separation is required between the generated artifacts and the pattern user’s customisations

3 © 2012 IBM Corporation

Customising Pattern Instances

 Recommended approach is put the subflows in a separate project:
– This project contains the subflows for the pattern user to modify
– One or more projects which contain the pattern instance generated flows

 The project is marked as customisable in the Pattern Authoring editor:

 Customisation projects are never deleted nor
overwritten when a pattern instance is re-generated


Pattern Refinement


Refresh!

 Pattern authoring supports property changes out-of-the-box
– Node, user-defined properties (UDPs) and promoted node properties

 Property variability is the most common type of variability that a pattern
might need to express - there are many others:
– Generate application text files such as ESQL scripts
– Make structural changes to Message Flows
– Create administration files such as MQSC scripts

 It is impossible to try and predict all the possible extensions that a pattern
author might wish to implement
 In Message Broker we provide two ways to extend pattern authoring
– Java code that is invoked when pattern instances are generated
– PHP templates that generate text files in pattern instance projects


Where Does Your PHP and Java Code Go?
 Pattern refinements are packaged in one or more separate plug-ins
– Packaged and distributed with the generated pattern plug-ins
– Clean separation between code written by the pattern author and the plug-ins generated
by the Pattern Authoring editor
– Makes it very easy to re-use Java and PHP between patterns
– Straightforward to version, patch and upgrade the plug-ins
– All the plug-ins can still be packaged in a single ZIP file for distribution

 New pattern authoring wizard make it a breeze to create plug-ins!


Pattern Instance Generation

 The following sequence of actions generates pattern instance projects:
1. The pattern authoring runtime creates the pattern instance projects
2. All non message flow files are copied into the pattern instance projects
3. The message flows are loaded into memory from the pattern plug-ins
4. All target properties are configured in the message flows
5. PHP and Java targets are invoked in top-to-bottom order
6. The message flows are saved into the pattern instance projects


Rolling Your Own Plug-in?

 It must be a plug-in not just a Java project!
 Your plug-in must export the Java classes that are to be invoked
 You will need a reference to com.ibm.broker.config.appdev
 There is a reference from the pattern plug-ins to your plug-in
– The pattern authoring generator adds this to the plug-in manifest

 If it contains PHP templates then it must be a directory plug-in
– PHP scripts can only be loaded direct from the file system and not from a JAR

 The plug-in must be installed before pattern instances can be created
– So think about how you want to distribute your code!


Java and PHP code
 Easy to attach Java and PHP code to a pattern – the code is invoked in
top down order as shown in the Pattern Authoring editor


Java Code

 Java classes implement GeneratePatternInstanceTransform
 The pattern authoring runtime invokes onGeneratePatternInstance
 The method is passed a reference to a PatternInstanceManager
– Provides access to pattern parameters, pattern instance name and workspace location
– Most important of all, the Java class can manipulate message flows!


Java Example


Manipulating Message Flows

 Retrieve a message flow using the patternInstanceManager
 Pass the (exemplar) project name and the relative path to the file
 The message flows are loaded into memory from the pattern plug-ins
– The flows are automatically saved into the pattern instance projects at the end

 Your changes act on the message flow immediately


Message Flow API

 The MessageFlow API contains all the nodes, connections and artefacts
present in the message flow

 The Message Flow API includes properties, nodes and connections
– This is not an exhaustive list!

 User Defined Nodes are represented as GenericNode


Message Flow API

 Helper methods throughout the Message Flow API
– For example, finding a node by its label using getNodeByName

 Node properties are strongly typed wherever possible
 Enumerations are provided for properties
– Implemented as type-safe classes

 JavaDoc provided for properties (easily viewed in the Java editor)


Creating Connections Between Nodes
 Nodes can be connected using terminals (in the Node class)

 Dynamic terminals and GenericNode terminals also supported


Complex Properties

 Complex properties are manipulated using objects (tables and rows)
 Property values on rows are strongly typed
 Rows can be added and removed from tables


Complex Properties Example


PHP

 PHP is a general purpose dynamic scripting language
 Easy to use with a gentle learning curve
 Efficient syntax and library have evolved in open source
– Community driven to get more done in less time
– Impressive results with little code
– Extensive library support
– Language well suited to rapid prototyping
 More than 3 million developers worldwide
 4th most populate language after Java, C and Visual Basic
 Message Broker PHP Compute Node since v6.1.0.4
– Java implementation, fully compliant with PHP version 5.2


PHP Templates

 Output from PHP template is written straight to a pattern instance file


PHP Scripts

 The PHP script invokes other PHP templates to output files
– Script acts as a controller and runs other templates as required

 Typically used when custom logic is required with pattern parameters
 Output from the controller script is sent to the Console view


PHP Example (main.php)


PHP Example (example.esql.php)

This uses the PHP echo function to write
the text into the output file - the embedded
PHP code is accessing pattern parameters
through the _MB super global

This section of ESQL script is conditionally output
depending on the value of the errorAction
pattern parameter - the surrounding PHP uses a
HEREDOC to output the code as a literal string


PHP Super Globals
 PHP provides a large number of predefined variables to any script which it
runs – Message Broker has an additional super global called _MB
 _MB in pattern authoring is populated with the pattern parameters, the
pattern instance name and the PatternInstanceManager:


Standard PHP Functions

 The full list of supported PHP extensions and functions are listed here:
http://publib.boulder.ibm.com/infocenter/wmbhelp/v7r0m0/topic/com.ibm.etools.mft.doc/ac69026_.htm

 Extensive help on PHP is available on http://php.net
–Individual functions can be located directly, for example: http://php.net/phpinfo

 The language reference for PHP is here:
–http://www.php.net/manual/en/langref.php

 There are a few language differences between the Message Broker PHP
and the Open Source PHP implementation – they are listed here:
–http://publib.boulder.ibm.com/infocenter/wmbhelp/v7r0m0/index.jsp


Debug


Debugging Your Pattern Refinements
 Java pattern refinements can be debugged in the Java debugger
 The launch configuration is automatically created the first time you test a
pattern from the Pattern Authoring editor:

 Any console output from your PHP or Java appears in the Console view:


Editing PHP On-The-Fly

 You do not need to re-launch a workbench to test your PHP changes
 Simply save the file in the main workbench and click Generate again
 This edit and test efficiency is a major productivity boost
 If you change anything else in the pattern then you need to re-launch


Exception Handing
 Exceptions from PHP and Java code are caught and displayed


Java and PHP
Interoperability


PHP and Java Integration

 It is straightforward to invoke Java code from your PHP scripts:

 The Message Broker PHP runtime has a feature rich Java bridge
http://www.projectzero.org/sMash/1.1.x/docs/zero.devguide.doc/zero.php/ZeroAdvancedPHPJavaBridge.html

 This PHP script is manipulating the message flow using the Java API!

31


So Which Language Should I Use?

 Because of the Java bridge in the PHP runtime, many pattern authoring
tasks can be done in either language
 So here are some general recommendations – your mileage may vary!
 Use PHP for text files that need to be marked up with conditional logic
 Use Java to manipulate message flows as you get an excellent
debugger and code completion in the Java editor
– Unless you have PHP skills and prefer the productivity of scripting languages!

 If you have existing assets or libraries that you want to call, pick the
language that best aligns with them


Table Parameters


Table Parameters

 Tables support row oriented data entered by the pattern user
– The data type of the rows in a table is restricted to strings at the moment
– No field validation of data is possible either (for example between columns)

 No automatic mapping to complex properties is available
– Process the rows of information using the Message Flow API

 Tables appear frequently in the built-in Message Broker patterns
– For example, to control message routing in the file processing pattern

34 Pattern Building in WebSphere Message Broker © 2012 IBM Corporation

Table Parameters
 Table editor added to the selection of editors available for parameters:

 Tables are defined by the pattern author in the table editor
– Columns can be mandatory or optional, and may also have width specified
– Help text for the columns in defined in HTML just like pattern parameters


Accessing Table Parameters

 Two Java APIs isTableParameter and getParameterTable
available in the PatternInstanceManager interface
 getParameterTable returns a PatternParameterTable instance
 PatternParameterTable provides access to the row count and the
individual rows
 Rows are accessed through an instance of PatternParameterRow


Enumerated Types


Enumerated Types

 Target properties are strongly typed
– String, integer, boolean and enumerations and the most common types
– An enumeration is a list of permissible values for a given property:

 The Pattern Authoring editor has full support for enumerations
– An enumerated type is automatically created when a target property is added
– The enumerated type includes the display names and property values
– The list of values presented to the pattern user can be reduced if required


Advanced Field Editors


Field Editors
 Advanced field editors provide richer user interface experience
– Built in validation also ensures data is entered correctly by the pattern user

 Queue name and project name editors make common cases simple!


File and Folder Selection

Two use cases stand out above all others for the file selection editor:
As a way to augment existing files to implement micro patterns
– For example, to add error handling logic to existing Message Flows

To store metadata for mass migration and generation of message flows
– The file might be XML data and used to programmatically generate message flows
– Sometimes it is appropriate for pattern users to enter data in third party tools


User-Defined Editors



 Pattern authoring provides an extensive set of pattern parameter editors
 Built-in editors support a range of data types such as strings and integers
 Validating editors also provided such as the message queue name editor

 Patterns are emerging which require a richer set of parameter editors
 Supports scenarios where your pattern user does extended exploration and discovery


 Pattern authors can define their own editors to use in their patterns:

 User-defined editors are defined and implemented in Java code
 Java code is packaged just like existing code in a pattern authoring project

 User-defined editors collaborate with the Pattern Instance editor
 User-defined editors support watermarking, XPath enablement, mandatory
configuration, validation, and change notifications to other editors!


Creating User-Defined Editors


Creating User-Defined Editors - Introduction

You create two Java classes that together implement a user-defined editor:
The first class implements the user interface using SWT controls
 This user interface class extends the SWT Composite class

The second class extends the BasePatternPropertyEditor class
 This class interfaces with the Pattern Instance editor

Wizards are provided that make it very easy to create these classes!


Creating User-Defined Editors - Composite

 Recommended to install WindowBuilder into your Message Broker toolkit
 WindowBuilder is an open source user interface design tool for Eclipse
 Download WindowBuilder from http://code.google.com/javadevtools/wbpro/
 Very easy to install the plug-ins using Help -> Install New Software
 Message Broker is now based on Eclipse Helios so use the 3.6 update site


Creating User-Defined Editors - Composite

Create an SWT Composite using the standard WindowBuilder wizard:


Creating User-Defined Editors – User Interface
 Design your SWT composite using the WindowBuilder editor
 The palette of SWT controls makes it easy to visually create your user interface
 Set up handlers (methods) to receive event notifications from your SWT controls


Creating User-Defined Editors – Main Class
 New wizard makes it easy to create a user-defined editor main class
 User-defined editors extend the BasePatternPropertyEditor class
 There are several methods (explained next) you override to complete your editor

 Your implementation class must be exported from your Java project
 Double click the MANIFEST.MF and check the exported packages on the Runtime tab!


 The configureEditor method is called first to set up your editor
 A PatternPropertySite is provided as your interface to the Pattern Instance editor
 The configuration values from the pattern authoring editor are also provided

 In your main editor class create an instance of your Composite class
 Do this when your createControls method is invoked by the Pattern Instance editor



Add extra methods to your main class to complete your implementation:
 isValid returns null or a string describing the validation error
 setValue is called early on to pass the initial value to your editor
 getValue is called when the editor is being saved into a configuration file
 setEnabled to enable and disable your user interface controls

Your editor is always saved before a pattern instance is generated
 Return your editor value as a string (or return null for no current value)

You must call valueChanged on your site when your value changes
 This ensures change notifications are sent to any editors listening to your editor!


Creating User-Defined Editors – Debugging
 All exceptions thrown by user-defined editors are caught and displayed
 Provides fail fast feedback to the pattern author on where the code issue is
 Beware of setValue being called with a null value when your editor is instantiated!


Packaging User-Defined Editors


Creating a User-Defined Editor – Packaging

 Additional projects can now be packaged into patternzip archives
 Convenient way to add Java projects containing user-defined editors
 Also provides an easy way to package third party JAR files in your patterns!


Using User-Defined Editors



 Select your user-defined editor when you configure a pattern parameter
 Provide a default value to pass an initial value to the user-defined editor



 Choose the project and class name that contains the user-defined editor
 Additional editor specific configuration values can be passed along
 Select the pattern parameters that will send you change notifications
 Allows chaining of dependent pattern parameters like message set, type and format


User-Defined Editors - Summary

 User-defined editors support rich pattern user interface experiences
 Very simple - get a fully functional editor working in less than an hour!
 WindowBuilder provides an excellent design environment for your user interface


Fine Grained Control


Transformation
 The Pattern Authoring editor uses XPath as its expression language
– XPath is a general purpose expression language!

 XPath expressions can transform pattern parameter values:
– Pattern authors can configure an XPath expression for a pattern parameter
– Expressions are evaluated when the pattern instance is generated


Enablement

 Enablement uses an XPath expression to control when a pattern
parameter is enabled in the Pattern Instance editor

 The enablement expression is evaluated every time a pattern parameter
referenced in the XPath expression changes value
 If the result of the evaluation is true then the editor is enabled


Hiding Groups

 Groups can be conditionally hidden in the Pattern Instance editor
 Follows same design principle as enabling and disabling parameters
 Removes visual clutter from screen for more complex patterns


Project Enablement

 Projects can be enabled in the Pattern Authoring editor:

 The XPath expression is evaluated when a pattern instance is generated
 If the result of the evaluation is true then the project is created
– Allows project creation to be linked to pattern parameters


Project Naming

 Control available over generated project names

 The pattern instance name prefix is optional for each project
 Pattern parameters can also now be used to name generated projects
– Hidden parameters can be used so that complex names can be specified in XPath


Advanced Pattern Authoring with WebSphere Message Broker

More Related Content

What's hot

Viewers also liked

Similar to Advanced Pattern Authoring with WebSphere Message Broker

More from Ant Phillips

Recently uploaded

Advanced Pattern Authoring with WebSphere Message Broker