I have a customer that has a lot of Broker Clients (in Java and C/C++) that connect directly to the Broker of the IS and publish documents that are subscribed by IS Triggers for processing.
When switching from Broker to UM in Wm9.10, the documents are also migrated. This migration is also a paradigm shift and one that encloses design decisions to accommodate IS pub/sub in Universal Messaging terms. I could not find any specific documentation that discusses this on the point of view of a detached Broker Client.
Q1: Is there any documentation or guide for refactoring code that uses the Broker Client API (to publish/subscribe documents to/from the IS) into one that uses the UM Client API for the same purposes?
first point will be to check the API Documentations for Broker and UM.
You will have to modify the import/include statements in the code as well as to replace certain class usages.
unfortunately it is not as simple as Holger describes. The APIs for publishing/subscribing should be relatively easy to transfer. The challenge is in constructing the right payload format from Java or C++.
Broker is inherently strongly-typed and uses Broker Events to expose those structures to clients. IS also uses this internally and maps between IData (the IS internal format) and Broker Events.
UM is basically typeless and messages may have maps or byte or string payloads. IS pub-sub uses a special payload format based on Google Protocol Buffers (Protobufs for short). This is a very efficient serialization format that UM is aware of. Like Broker Events, it is strongly-typed and in UM we store the Protobuf schemas as attributes on the associated Channel. So all the information is there to allow Java or C++ clients to construct messages in the right format, but you will need to use the Protobuf API (provided by Google) to construct messages. Unfortunately there is no documentation on how to do this.
I suggest you email me privately (my firstname.lastname at softwareag dot com) and I can make sure you get the right support. And hopefully you will be able to share the output with the Tech Community!
Ahem…May I ask an aside question? My understanding is that UM should handle IData encoded documents as well – as long as the producers and the consumers of the messages are IS. Is my understanding correct?
Sure, in this case message filtering can’t be performed on the server (=UM) side, i.e. UM would deliver the messages to all potential consumers (IS), which would then apply the trigger filters and decide whether the message is really to be processed. But it’s just an inefficiency (more messages delivered to IS than necessary) which should not affect the correctness of the operation.
I’m asking because we recently ran into an issue that the Designer wrongly generates process filters (during Build & Upload) if the process is started via an IData encoded document which is associated with a messaging provider of type UM. The filter of the trigger was generated into the UM filter, but UM can’t evaluate it for IData encoded messages.
In my view, this is a bug in Designer. What is your opinion on this?
you are right in that there are two ways to encode messages going across UM between ISes: IData and Protobuf. IData is not (easily) filterable on the server-side, which is why Protobuf is now the default and preferred encoding.
For your BPM process, I would recommend that you switch the encoding of the document to protobuf. This is also documented in the BPM Process Development Help document in the section Setting the Encoding Type for the Universal Messaging Document Types.
we can’t easily switch the encoding of the documents because this is a code base with we also use on a system where we only use Broker. There, IData is the only possible option. Hence we thought, we’d use IData on another system as well where we use UM. Since the only senders and consumers are IS, we’d thought this would work well. Und it would indeed if the Designer would generate triggers correctly.
So the question is: Is it the recommended (but not the only possible) way? Or is it by design that the triggers are generated only for UM variant? Why then is it possible at all to set the encoding to “IData” for doc types associated with the UM mesaging provider?
Firstly, the encoding property is ignored with Broker, so there is no harm in setting it to Protobuf.
BPM Designer indeed only generates trigger filters for Protobuf-encoded documents, as mentioned in the documentation.
We introduced IData encoding for UM in 9.6 and Protobuf encoding in 9.7. IData encoding has valid use-cases that are not possible with Protobuf, such a compatibility with JMS (same payload format as IS documents sent via JMS) and access to header properties (aka Dictionary fields), which can be useful when communicating with other language clients that only need a few name/value pairs.
This is very interesting, I didn’t know that! We’ll try to set the encoding to Protobuf and see how it works with the Broker (under wM 9.6). But to do this, we’ll have to edit the documents with a higher version of Designer since Designer 9.6 does not allow to set the setting. I hope such documents can still be processed by the Broker and IS 9.6.