Message class formats in the Messaging Toolkit

When the message_class attribute value is bytes:

• The XMSSink operator constructs an XMS BytesMessage. The JMSSink operator constructs a JMS BytesMessage. The BytesMessage is a stream of binary data that contains values that are taken from the input stream. The values are serialized into the message in the order that is specified in the <native_schema> element and they use the data types from that element.
• Note: The XMSSink operator can handle String and blob attributes that do not have lengths that are specified in the <native_schema> element. The operator serializes such attributes directly into the BytesMessage, and uses the actual length of the attribute at run time. For example, if the blob has three entries, then it uses up 3 bytes in the BytesMessage. If the <native_schema> element contains a length for a String or blob attribute, then the XMSSink operator pads or truncates the run time attribute value to make it fit this length. Blob attributes are padded with nulls and String attributes are padded with spaces.
• The JMSSink operator raises a runtime error if the <native_schema> element does not specify the length for all String and blob attributes or if a negative length other than -2 or -4 is specified. If the length is positive, the operator pads or truncates the run time attributes to make it fit this length. Blob attributes are padded with null values and String attributes are padded with spaces. For String attributes, length is measured in number of bytes.
• The XMSSource operator expects an XMS BytesMessage. The JMSSource operator expects a JMS BytesMessage. The BytesMessage contains the values of the elements that are listed in the <native_schema>. The values of the elements must occur in the order that is specified in the <native_schema> element. The data types must match the types that are specified in the schema. If the data in the message is insufficient, the operator discards the entire message and logs a run time error.
  • Note: The <native_schema> element must specify the length of all the String and blob attributes, unless the attribute is the final attribute in the <native_schema> element.
    • If the attribute is the final attribute in the <native_schema> element and a length is not specified, the operators assume that the attribute takes all the bytes that remain in the XMS message.
    • For an XMSSource operator, if the attribute is not the final attribute in the <native_schema> element and a length is not specified, a compile-time error occurs. For a JMSSource operator, if the attribute is not the final attribute in the <native_schema> element and a length is not specified, a run-time error occurs.
    • For an XMSSource operator, if the length of the <attribute> element is -2, -4 or -8, the operator assumes that the data that appears in the XMS message starts with a signed 2, 4, or 8-byte length field. This length field is an integer that is encoded in the same way as any other integer attribute in the message. If the length value is incomplete, negative, or absent from the message, or there are insufficient bytes remaining in the XMS message, the operator discards the entire message and logs a run-time error.
    • For a JMSSource operator, if the length of the <attribute> element is -2 or -4, the operator assume that the data that appears in the JMS message starts with a signed 2 or 4-byte length field. This length field is an integer that is encoded in the same way as any other integer attribute in the message. If the length value is incomplete, negative, or absent from the message, or there are insufficient bytes remaining in the JMS message, the operator discards the entire message and logs a run-time error.
    • If the length of the <attribute> element is non-negative, then the operators attempt to read exactly that number of bytes from the BytesMessage. If there are insufficient bytes remaining in the XMS or JMS message, the operators discard the entire message and logs a run time error.
    • For an XMSSource operator, if the length attribute value is not a supported value, a compile-time error occurs. For a JMSSource operator, if the length attribute value is not a supported value, a run-time error occurs.

When the message_class attribute value is empty:

• The XMSSink operator construct an empty XMS message. The JMSSink operator construct an empty JMS message. For example, you can use an empty XMS message to verify that your IBM Streams application can connect to the WebSphere MQ server and that the message reaches its destination. Note: This message_class value cannot be used with a <native_schema> element.
• The XMSSource operator expects an empty XMS message. It emits a tuple with attribute values that are assigned by the SPL program. This behavior is not supported if a <native_schema> element is defined or if there are any unassigned attributes. The JMSSource operator expects an empty JMS message.

When the message_class attribute value is map:

• The XMSSink operator produces an XMS MapMessage. The JMSSink operator produces a JMS MapMessage. The MapMessage is a collection of name, type and value triplets. The triplets contain elements whose names and types are taken from the <native_schema> element. Their values are taken from the operator input stream.
• The XMSSource operator expects an XMS MapMessage that contains elements whose names and types appear in the <native_schema> element. The JMSSource operator expects a JMS MapMessage that contains elements whose names and types appear in the <native_schema> element.
  • If the schema contains an attribute which is not present in the MapMessage, the operator discards the entire message and logs a run time error.
  • If the MapMessage contains an attribute whose type does not match the data type in the <native_schema>, the operators attempt to convert it using the standard XMS or JMS conversion rules. If this conversion fails, the entire message is discarded and an error message is logged.
  • If the MapMessage contains an attribute with a null value, the corresponding output stream attribute is set to the default value for its type.
  • If the MapMessage contains attributes that are not listed in the <native_schema>, the attributes are ignored.

When the message_class attribute value is stream:

• The XMSSink operator constructs an XMS StreamMessage. The JMSSink operator constructs a JMS StreamMessage. The StreamMessage is an ordered list of type and value pairs. The pairs contain values that are taken from the input stream. The values are serialized into the message in the order in which they are specified in the <native_schema> element. The values use the data types from the <native_schema> element.
• The XMSSource operator expects an XMS StreamMessage. The JMSSource operator expects a JMS StreamMessage. The StreamMessage contains the values of the elements that are listed in the <native_schema> element. The values must occur in the order that is specified in the <native_schema> element. The values must also have the data types that are specified in that schema.
  • If the operator encounters an attribute in the StreamMessage that does not have the expected data type, it attempts to convert the attribute to the data type specified by the <native_schema> element. If they conversion fails, the operator discards the entire message and logs a run time error.
  • If the StreamMessage contains more attributes than the <native_schema>, the attributes are ignored and a tuple is emitted.
  • If the StreamMessage does not contain enough attributes, the operator discards the entire message and logs a run-time error.
  • If the StreamMessage contains an attribute with a null value, the corresponding output stream attribute is set to the default value for its type.

When the message_class attribute value is text: When the text message class is specified in the connection document, the native schema must contain a single attribute of a String type. Text messages must be encoded in UTF-8. For support of other encoding, use bytes message class.

• The JMSSink and XMSSink operators construct a JMS TextMessage and the output schema for JMSSink must contain a single String attribute.
• The JMSSource and XMSSource operators expect a JMS TextMessage and the input schema for JMSSource must contain a single String attribute.

When the message_class attribute value is wbe:

• The XMSSink operator constructs an XMS TextMessage. The JMSSink operator constructs a JMS TextMessage. The TextMessage contains an XML document in the WebSphere Business Events (WBE) event packet format.

  The XML document contains a single <connector-bundle> of type Event. The XML namespace is http://wbe.ibm.com/6.2/Event/xxx where xxx is the input stream name. The input port is used as the connector-bundle name attribute and also as a wrapper element that contains the stream attribute values. The XML document contains a field for each attribute that is listed in the <native_schema> element.

  Restriction: The blob data type is not a supported when you use the wbe message class.

• The XMSSource and the JMSSource operators do not support the use of the wbe message_class attribute value. If the operators encounters a message of class wbe, the operators discard the message.

When the message_class attribute value is wbe22:

• The XMSSink operator constructs an XMS TextMessage. The JMSSink operator constructs a JMS TextMessage. The TextMessage contains an XML document in the WebSphere Business Events 2.2 event packet format.

  The XML document contains a single "connector-object" (event). The input stream name is used for both the WBE event-name and event-object name. The document contains a field for each attribute that is listed in the <native_schema> element.

  Restriction: The blob data type is not supported when you use the wbe22 message class.

• The XMSSource and the JMSSource operators do not support the use of the wbe22 message_class attribute value. If the operators encounter a message of class wbe22, the operators discard the message.

When the message_class attribute value is xml:

• The XMSSink operator constructs an XMS message that contains a generic XML message. The JMSSink operator constructs a JMS message that contains a generic XML message.
• The XMSSource and JMSSource operators do not support the use of the xml message_class attribute value. If the operators encounter a message of class xml, it discards the message.

<connector 
xmlns='http://wbe.ibm.com/6.2/Event/StockCashMergerArbitrageStatus_T_SBC' 
name='System S' version='6.2'>
  <connector-bundle 
  name='StockCashMergerArbitrageStatus_T_SBC'
  type='Event'>
  <StockCashMergerArbitrageStatus_T_SBC'>
  <date data-type='string'>01-FEB-2005</date>
  <time data-type='string'>14:45:21.335</time>
  <ratio data-type='real'>0.747079</ratio>
  <alertType data-type='string'>IN</alertType>
  <dayNum data-type='integer'>12815</dayNum>
  <flag data-type='boolean'>true</flag>
  </StockCashMergerArbitrageStatus_T_SBC'>
  </connector-bundle>
</connector>

<connector name='System S' version='2.2'>
  <connector-bundle 
  name='iport$0' 
  type='Event'>
    <connector-object name='iport$0'>
      <field name='uintdata'>100</field>
      <field name='somethingID'>Yes</field>
      <field name='somethingid'>YesToo</field>
    </connector-object>
  </connector-bundle>
</connector>