Copyright © TIBCO Software Inc. All Rights Reserved
Copyright © TIBCO Software Inc. All Rights Reserved


Chapter 8 Advanced Features : Transformation Plug-in

Transformation Plug-in
The transformation plug-in allows developers to transform inbound and/or outbound messages for any adapter built with the Adapter SDK. It could be used, for example, for performing localized transformations using XSLT.
Usage Scenarios
The application to which the adapter connects understands XML natively. The adapter code retrieves messages and makes use of the MInstance::toXML() methods. The corresponding XSD is available in-memory and on disk if you have exported it. To achieve local transformations to a canonical format, XSLT is the logical choice. These transformations can be applied to all outbound endpoints. Inbound transformations most likely don’t make sense.
Some custom code is required to manipulate messages before sending them to a third-party application. For example, a legacy TIBCO Rendezvous application expects its data in a particular format. The only solution is to write an intervening adapter between packaged adapters and the TIBCO Rendezvous application to do TIBCO Rendezvous transformations, or to use other TIBCO products (for example, TIBCO ActiveMatrix BusinessWorks).
Implementation
The low-level callout behavior is made available by an MTransformationPlugin class that is part of the API (both C++ and Java). See the reference documentation for more information.
The low-level callout is specified in the TIBCO Designer:
1.
2.
Click the Browse button next to the Message Filter field to select the class that implements the transformation plug-in.
The transformation plug-ins are applied only to MSubscriber, MPublisher, MRpcClient, and MRpcServer endpoints.
You can either throw an exception or return FALSE to stop message flow in the transformInbound() or transformOutbound() method.
If the transformOutbound() method throws an exception, it will be propagated back to user.
If the transformInbound() method throws an exception, an advisory will be sent out on the subject, _SDK.ERROR.PLUGIN.PLUGIN_TRANSFORMATION_ERROR.
When using the transformInbound() method in async mode, the message flow does not stop. An advisory message is sent on the above subject.
Example
The following example illustrates how to use the low-level plug-in.
Not all details are present here (for example, the DLL_EXPORT macro details are omitted).

 
// GOES IN THE HEADER FILE
extern “C”
{
DLL_EXPORT MException *
CreateTransformationPlugin( MApp * pMApp
,MTransformationPlugin * & pTPlugin );
DLL_EXPORT void
DestroyTransformationPlugin( MTransformationPlugin * & pTPlugin );
}
 
class CustomPlugin : public MTransformationPlugin
{
CustomPlugin( MApp * pMApp,
   MString const & pluginName,
   MString const & pluginID ) throw (MException);
 
virtual Mboolean
transformOutbound( MComponent const & endpoint, MTree & outboundTree )
                      throw (MException);
 
virtual Mboolean
transformInbound( MComponent const & endpoint, MTree & inboundTree ) throw (MException);
 

 
// GOES INTO THE CPP FILE
CreateTransformationPlugin( MApp * pMApp,
   MTransformationPlugin * & pTPlugin )
{
try {
CustomPlugin * pCP =
new CustomPlugin( pMApp, “MyTransformer”, “Converter v1.0” );
if pCP == NULL
return new MException(…);
catch( MException e ) {
return new MException(…);
}
return NULL;
}
 
void DestroyTransformationPlugin( MTransformationPlugin * pTPlugin )
{
delete pTPlugin;
}
 
 
CustomPlugin::CustomPlugin( MApp * pMApp,
   MString const & pluginName,
   MString const & pluginID ) throw (MException)
:MTransformationPlugin( pMApp, pluginName, pluginID )
{ … }
 
virtual Mboolean
   CustomPlugin::transformOutbound(MComponent const & endpoint, MTree & outboundTree ) throw (MException)
{
return veilMTree( outboundTree );
}
 
virtual Mboolean
CustomPlugin::transformInbound(MComponent const & endpoint, MTree & inboundTree ) throw (MException)
{
return unveilMTree( inboundTree );
}

 

Copyright © TIBCO Software Inc. All Rights Reserved
Copyright © TIBCO Software Inc. All Rights Reserved