Message class formats in the JMS toolkit

When the message_class attribute value is bytes:

• 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.
• 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 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.
    • 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 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 JMS message, the operators discard the entire message and logs a run time error.
    • 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 JMSSink operator construct an empty JMS message. For example, you can use an empty 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 JMSSource operator expects an empty JMS message.

When the message_class attribute value is map:

• 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 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 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 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 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 operator constructs a JMS TextMessage and the output schema for JMSSink must contain a single String attribute.
• The JMSSource operator expects a JMS TextMessage and the input schema for JMSSource must contain a single String attribute.

When the message_class attribute value is wbe:

• 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 JMSSource operator does not support the use of the wbe message_class attribute value. If the operator encounters a message of class wbe, the operator discards the message.

When the message_class attribute value is wbe22:

• 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 JMSSource operator does not support the use of the wbe22 message_class attribute value. If the operator encounters a message of class wbe22, the operator discards the message.

When the message_class attribute value is xml:

• The JMSSink operator constructs a JMS message that contains a generic XML message.
• The JMSSource operators do not support the use of the xml message_class attribute value. If the operator encounters 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>