Using Protocol Buffers as the Encoding Type
If a publishable document type uses Universal Messaging as the messaging provider, you can use protocol buffers as the encoding type. The primary reason to encode published documents as protocol buffers is to leverage the filtering capabilities of Universal Messaging. When protocol buffers is the encoding type, webMethods messaging triggers that subscribe to the publishable document type can create provider filters for the body of the document. Note that the body of the published document contains the _properties headers and the _env field, as well as the document body fields. When a document type uses IData as the encoding type, webMethods messaging triggers that subscribe to the publishable document type can create provider filters for the header of the published document only. By creating provider filters for the body as well as the header of the document, triggers can be more selective about which documents they receive.
When you save a publishable document type for which protocol buffers is the encoding type, Integration Server creates a message descriptor that represents the structure of the document type as a protocol buffer. Integration Server saves the message descriptor along with other metadata in the node.ndf file for the publishable document type. When an instance of the publishable document type is published, Integration Server uses the message descriptor to encode the document as a protocol buffer and then sends the document to Universal Messaging. When a trigger receives the published document, Integration Server uses the message descriptor to decode the document from a protocol buffer.
Note: | The message descriptor is a binary representation of the message structure and is not visible within Designer. |
When creating the message descriptor, Integration Server includes only fields that can be represented in the protocol buffers format. Not all field names, data types, and structures that are valid for a publishable document type can be represented in the protocol buffer message descriptor. When publishing a document, Integration Server places fields that cannot be represented in a protocol buffer message descriptor in an UnknownFieldSet. An UnknownFieldSet is a collection of fields that may be present while encoding or decoding the document but are not present in the message descriptor. Integration Server encodes the UnknownFieldSet as a serialized IData byte array. The UnknownFieldSet, which is included in the published document, is passed through to the subscribers. Universal Messaging cannot use provider filters to filter on the contents of the UnknownFieldSet. However, a webMethods messaging trigger that receives the document will be able to decode the UnknownFieldSet and include its contents in the pipeline.
If you encode documents as protocol buffers to make use of provider filters for the document body, you may want to delegate as much filtering to the Universal Messaging as possible. If so, make sure the fields on whose contents you want Universal Messaging to filter can be represented within a protocol buffer message descriptor. Universal Messaging can only filter on fields that can be represented in the protocol buffer message format.
The following list identifies limitations for representing a fields in a protocol buffer descriptor:
Field names must meet the following criteria to be encoded:
First character must be a letter (a-z or A-Z).
Subsequent characters must be a letter, number, or underscore symbol (_).
If the field name does not meet the preceding criteria, Designer displays the following message when you save the publishable document type: Cannot create field ''fieldName'' in publishable document type ''publishableDocumentTypeName''; this field name is not valid for use with protocol buffer encoding. The Universal Messaging provider will transport the field contents as part or the UnknownFieldSet, which will be visible to Integration Server clients only.
Note: | Integration Server reserves the use of field names that begin with the underscore character for Integration Server usage, for example _env and _properties. |
Fields at the same level that share the same name, such as fields at the top-level of the document type or sibling fields in a Document variable, cannot be encoded with protocol buffers.
Integration Server encodes the identically named fields as part of the IData byte array for the UnknownFieldSet. For information about how
Integration Server decodes the contents of fields with the same name, see
Decoding Protocol Buffers.
If the publishable document type contains duplicate variables, Designer displays the following message when you save the publishable document type: Cannot create field ''fieldName'' in publishable document type ''publishableDocumentTypeName''; field with duplicate names are not permitted with protocol buffer encoding.
Fields must be defined to be data type supported by protocol buffers encoding.
String tables cannot be encoded with protocol buffers and will be defined as byte array within the message descriptor and passed through as a serialized IData object.
Objects and Object Lists defined to be an unknown Java wrapper type cannot be encoded with protocol buffers. Instead, unknown Objects and Object Lists will be defined as byte array within the message descriptor and passed through as a serialized IData object.
Note: | An Object or Object List field is unknown when the Java wrapper type property for the fields is set to UNKNOWN. For more information about assigning a Java wrapper type to a field, see Applying Constraints to a Variable. |
To generate additional logging information in the Sever log when Integration Server creates the protocol buffer descriptor set the logging level for the server log facility 0154 Protocol Buffer Encoding (Universal Messaging) to Debug or Trace. Increased logging can help you to locate problems that occur during protocol buffer encoding.
