Advanced Pattern Authoring with WebSphere Message Broker

© 2012 IBM Corporation

Ant [email protected]

WebSphere Message Broker Advanced Pattern Authoring


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

3

A clean separation is required between the generated artifacts and the pattern user’s customisations


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:

4

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

6


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!

7


Pattern Instance Generation

8

The following sequence of actions generates pattern instance projects:1. The pattern authoring runtime creates the pattern instance projects2. All non message flow files are copied into the pattern instance projects3. The message flows are loaded into memory from the pattern plug-ins4. All target properties are configured in the message flows5. PHP and Java targets are invoked in top-to-bottom order6. 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!

9


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

10


Java Code

11

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

12


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

13

Manipulating Message Flows


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

14

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)

15

Message Flow API


Nodes can be connected using terminals (in the Node class)

Dynamic terminals and GenericNode terminals also supported

16

Creating Connections Between Nodes


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

17


Complex Properties Example

18


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

19


PHP Templates

20

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


PHP Scripts

21

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)

22


PHP Example (example.esql.php)

23

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:

24


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

25


Debug


Debugging Your Pattern Refinements

27

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

28

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

29

Exceptions from PHP and Java code are caught and displayed


Java and PHPInteroperability


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

The Message Broker PHP runtime has a feature rich Java bridgehttp://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!

PHP and Java Integration

31

31


So Which Language Should I Use?

32

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


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

36

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

Pattern Building in WebSphere Message Broker


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

38


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



43

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




44

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

46

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

61


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

62


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


Date post:	27-Jan-2015
Category:	Technology
Upload:	ant-phillips
View:	114 times
Download:	3 times

Advanced Pattern Authoring with WebSphere Message Broker

Technology