Advanced Pattern Authoring with WebSphere Message Broker


Published on

  • Be the first to comment

No Downloads
Total views
On SlideShare
From Embeds
Number of Embeds
Embeds 0
No embeds

No notes for slide

Advanced Pattern Authoring with WebSphere Message Broker

  1. 1. Ant Phillips Message BrokerAdvanced Pattern Authoring © 2012 IBM Corporation
  2. 2. Round Tripping © 2012 IBM Corporation
  3. 3. 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 customisations3 © 2012 IBM Corporation
  4. 4. 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-generated4 © 2012 IBM Corporation
  5. 5. Pattern Refinement © 2012 IBM Corporation
  6. 6. 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 projects6 © 2012 IBM Corporation
  7. 7. 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 © 2012 IBM Corporation
  8. 8. 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 projects8 © 2012 IBM Corporation
  9. 9. 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 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 © 2012 IBM Corporation
  10. 10. 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 editor10 © 2012 IBM Corporation
  11. 11. 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!11 © 2012 IBM Corporation
  12. 12. Java Example12 © 2012 IBM Corporation
  13. 13. 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 immediately13 © 2012 IBM Corporation
  14. 14. 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 GenericNode14 © 2012 IBM Corporation
  15. 15. 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 © 2012 IBM Corporation
  16. 16. Creating Connections Between Nodes Nodes can be connected using terminals (in the Node class) Dynamic terminals and GenericNode terminals also supported16 © 2012 IBM Corporation
  17. 17. 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 tables17 © 2012 IBM Corporation
  18. 18. Complex Properties Example18 © 2012 IBM Corporation
  19. 19. 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.219 © 2012 IBM Corporation
  20. 20. PHP Templates Output from PHP template is written straight to a pattern instance file20 © 2012 IBM Corporation
  21. 21. 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 view21 © 2012 IBM Corporation
  22. 22. PHP Example (main.php)22 © 2012 IBM Corporation
  23. 23. 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 string23 © 2012 IBM Corporation
  24. 24. 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 © 2012 IBM Corporation
  25. 25. Standard PHP Functions  The full list of supported PHP extensions and functions are listed here:  Extensive help on PHP is available on –Individual functions can be located directly, for example:  The language reference for PHP is here: –  There are a few language differences between the Message Broker PHP and the Open Source PHP implementation – they are listed here: – © 2012 IBM Corporation
  26. 26. Debug © 2012 IBM Corporation
  27. 27. 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:27 © 2012 IBM Corporation
  28. 28. 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-launch28 © 2012 IBM Corporation
  29. 29. Exception Handing Exceptions from PHP and Java code are caught and displayed29 © 2012 IBM Corporation
  30. 30. Java and PHP Interoperability © 2012 IBM Corporation
  31. 31. 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 This PHP script is manipulating the message flow using the Java API! 3131 © 2012 IBM Corporation
  32. 32. 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 them32 © 2012 IBM Corporation
  33. 33. Table Parameters © 2012 IBM Corporation
  34. 34. 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 pattern34 Pattern Building in WebSphere Message Broker © 2012 IBM Corporation
  35. 35. 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 parameters35 Pattern Building in WebSphere Message Broker © 2012 IBM Corporation
  36. 36. 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 PatternParameterRow36 Pattern Building in WebSphere Message Broker © 2012 IBM Corporation
  37. 37. Enumerated Types © 2012 IBM Corporation
  38. 38. 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 required38 © 2012 IBM Corporation
  39. 39. Advanced Field Editors © 2012 IBM Corporation
  40. 40. 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!40 Pattern Building in WebSphere Message Broker © 2012 IBM Corporation
  41. 41. File and Folder SelectionTwo 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 tools41 Pattern Building in WebSphere Message Broker © 2012 IBM Corporation
  42. 42. User-Defined Editors © 2012 IBM Corporation
  43. 43. 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 discovery43 Pattern Building in WebSphere Message Broker © 2012 IBM Corporation
  44. 44. User-Defined Editors 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!44 Pattern Building in WebSphere Message Broker © 2012 IBM Corporation
  45. 45. Creating User-Defined Editors © 2012 IBM Corporation
  46. 46. Creating User-Defined Editors - IntroductionYou 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!46 Pattern Building in WebSphere Message Broker © 2012 IBM Corporation
  47. 47. 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  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 site47 Pattern Building in WebSphere Message Broker © 2012 IBM Corporation
  48. 48. Creating User-Defined Editors - CompositeCreate an SWT Composite using the standard WindowBuilder wizard:48 Pattern Building in WebSphere Message Broker © 2012 IBM Corporation
  49. 49. 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 controls49 Pattern Building in WebSphere Message Broker © 2012 IBM Corporation
  50. 50. 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!50 Pattern Building in WebSphere Message Broker © 2012 IBM Corporation
  51. 51. Creating User-Defined Editors – Main Class 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 editor51 Pattern Building in WebSphere Message Broker © 2012 IBM Corporation
  52. 52. Creating User-Defined Editors – Main ClassAdd 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!52 Pattern Building in WebSphere Message Broker © 2012 IBM Corporation
  53. 53. 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!53 Pattern Building in WebSphere Message Broker © 2012 IBM Corporation
  54. 54. Packaging User-Defined Editors © 2012 IBM Corporation
  55. 55. 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!55 Pattern Building in WebSphere Message Broker © 2012 IBM Corporation
  56. 56. Using User-Defined Editors © 2012 IBM Corporation
  57. 57. 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 editor57 Pattern Building in WebSphere Message Broker © 2012 IBM Corporation
  58. 58. Using User-Defined Editors 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 format58 Pattern Building in WebSphere Message Broker © 2012 IBM Corporation
  59. 59. 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 interface59 Pattern Building in WebSphere Message Broker © 2012 IBM Corporation
  60. 60. Fine Grained Control © 2012 IBM Corporation
  61. 61. 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 generated61 © 2012 IBM Corporation
  62. 62. 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 enabled62 © 2012 IBM Corporation
  63. 63. 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 patterns63 Pattern Building in WebSphere Message Broker © 2012 IBM Corporation
  64. 64. 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 parameters64 Pattern Building in WebSphere Message Broker © 2012 IBM Corporation
  65. 65. 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 XPath65 Pattern Building in WebSphere Message Broker © 2012 IBM Corporation