Monday, October 17, 2016

Message transformation in Oracle Service Bus using XSLT and XQuery

You can only feel the main power of Oracle Service Bus by leveraging its message transformation capability. Today we will have a look at this capability and how to configure an XML-to-XML mapping based on XSLT or XQuery. Let's upgrade the example described within the previous entry.


The Replace action


As was mentioned in the previous entry, we should transform any incoming XML messages described by the following schema (source-message.xsd) to the format appropriated for the processing (target-message.xsd):



In order to change the body of a message is delivered toward a Business Service, the content of variable body must be replaced. The Replace action is leveraged here. The action can be used for replacing an entire XML node assigned to the variable as well as a part.

The Replace action should be drag and dropped into the developed message flow, within the Request Action pipeline, in the Dynamic Routing block.



The properties of the Replace action is configured on the Replace tab placed inside the Properties view. The XPath parameter, which is an XPath expression, is being used for selection the replaced node. The In Variable parameter is a variable to be replaced, the XPath parameter's expression will be applied to the variable. The Expression parameter contains a new value for the replaced variable. Radiobattons Replace entire node and Replace node content set the area the Replace action will be applied to: entire XML node or only its content.



It is noteworthy if Replace entire node is chosen, the node will be removed from the variable, otherwise the node will become empty.

Once the link next to the XPath parameter has been clicked, the editor window will appear. The window is comprised of two areas: Expression is used to input an expression and its parameters and the right side with the following tabs: Variable Structures, Namespace Definitions, XQuery Functions. The tabs facilitate the filling of the edited expression's parameters. The parameter (a variable as example) can be dragged from an appropriate tab.



Once the link next to the Expression parameter has been clicked, the expression editor window will appear. The Expression tab is used to input an XML expression which will be a new value for the variable. The expression can contains invokations of some XQuery functions, the function names must be wrapped in braces.



Using XQuery transformations


Instead on plain XML expressions, XQuery- and XSLT-mappings can be used for message transformation. Oracle Enteprise Pack for Eclipse contains a usefull graphic editor for XQuery mappings.

An XQuery mapping should be placed into an xq file. The file can be created by a click on the New -> XQuery Transformation item of the Project Explorer context menu.



The New XQuery Transformation master appears. The first step of the master facilitates to choose the destination and name of the created file.



The source format must be specified in the second step of the master. XML data types, as well as non-XML types and simple formats (strings, numbers, etc.) are available.



And the target format must be specified in the last step of the master. The target format is the type message will be transformed to. As well as for the source format, XML data types, as well as non-XML types and simple formats (strings, numbers, etc.) are available.



Once the master has completed its work, the file will be created, and the XQuery Transformation perspective will appear. The perspective provides a number of views that facilitate mapping development:

  • Target Expression - displays XQuery expressions
  • Constraints - is used for transformation constraints definition
  • Expression Variables - shows available variables
  • Expression Functions - shows available XQuery functions. The functions are broken down into several sections: OSB Functions, String Functions, Number Functions, etc. There is even the execute-sql function for retrieving some data for the transformation from a database.



The appropriate elements and attributes of the source format should be connected toward the appropriate nodes and attributes of the target one.



The created xq-file (TransformToMessage.xq) must be assigned as a value for the Expression property of the Replace node, so the XQuery/XSLT Expression Editor master should be opened, and the file must be chosen at the XQuery Resources tab using the Browse button.



Once the file has been chosen, the Bind Variables field will appear. The field is used as a place, where the source parameters must be bound to real variables. In the demonstrated example, the body variable is used as the source.



Using XSLT transformations


If an XSLT transformation will be leveraged instead of an XQuery one, an appropriate mapping file must be created. Oracle Enterprise Pack for Eclipse contains no graphic editor for XSLT files, but the editor is include in JDeveloper. Let's use this editor. A new XSLT mapping can be created by the File -> New menu item. The New Galery window appears and the XSL Map element of the XML category from the All Technologies tab must be chosen.



The Create XSL Map File window facilitates to specify the name of the file, the directory the file will be placed into (CountryRouter/Transformations/), source message format (sendMessage) and the target message format (message).



The appropriate elements and attributes of the source format should be connected toward the appropriate nodes and attributes of the target one. The palette of functions, which are available in XSLT transformations, is placed in the right part of the mapping editor.



The accomplished XSLT-file (ToMessageTransform.xsl) must be assigned as a value for the Expression property of the Replace node, so the XQuery/XSLT Expression Editor master should be opened, and the file must be chosen at the XQuery Resources tab using the Browse button. The source parameters must be bound to the variables by the same way as demonstrated above for XQuery transformations.



Transformation testing


After the Replace action is configured by one of the above ways, the project should be deployed on an OSB server. The Proxy Service can be tested inside the OSB console, the Proxy Service is available in the ProxyServices catalog of the CountryRouter project. To test the service, please click on the Launch Test Console button placed near the CountryProxyService2 resource.



In the appeared window, the request parameters must be assigned to the appropriate values. The test is starting by the Execute button.



The result will appear, and we can see the request has been successful handled. ENG was yield as a result.



The content of the last message received by the SomeServiceEng service is outlined into Enterprise Manager. As the following picture shows, the format of the message is the defined when the service was created. So, the transformation works fine!



Oracle Service Bus provides the transformation and dynamic routing capabilities along with a set of more complex ones. For example, there is the SplitJoin component that can be leveraged for creation composite services. A composite service is a service one invocation of which generates a number of invocations of multiple services. This behaviour allows to create such complex Enterprise Application Integration patterns as Aggregator. But this is a topic of another article.

Would you like to give a 'Like'? Please follow me on Twitter!