Namespace com.ibm.streamsx.jms

IBMStreams com.ibm.streamsx.jms Toolkit > com.ibm.streamsx.jms 2.0.0 > com.ibm.streamsx.jms

Conversions between JMS messages and tuples in IBM InfoSphere Streams

When you send data to or receive data from WebSphere MQ or an Apache Active MQ queue or topic by using JMSSink or JMSSource operators, IBM InfoSphere Streams must convert tuples to JMS messages, or vice-versa.

The mapping between JMS messages and the InfoSphere Streams tuples is controlled by the <native_schema&ft; element and the message_class attribute of the <destination> element. The message_class determines the type of mapping that is performed and also specifies the type of JMS message that is output by the JMSSink operator or expected by the JMSSource operator. The <native_schema> element determines the attributes that are present in an output JMS message or are expected in an input JMS message. The general principles for the conversion of data between InfoSphere Streams tuples and JMS messages are as follows:

  • There is a one-to-one mapping between JMS messages and InfoSphere Streams tuples. The JMSSource operator produces one tuple for each JMS message that it receives. The JMSSink operator produces one JMS message for each tuple that it receives unless a runtime error occurs in which case the message might be discarded.
  • The InfoSphere Streams tuples that are received by the JMSSink operator or are produced by the JMSSource operator conform to the InfoSphere Streams schema.
  • JMS messages that are output by the JMSSink operator conform to the constraints defined by the <native_schema> element.
  • The JMSSource operator accepts and processes any incoming messages that conform to the constraints defined by the <native_schema> element.
Where possible, mismatches between the InfoSphere Streams schema and the information in the <native_schema> element, which would prevent successful mapping, are detected at run time. For example:
  • If the <native_schema> element includes an attribute that is not present in the input stream for the JMSSink operator, the operator generates an error at run time. However, if there is an output stream attribute that is not present in the <native_schema> element, the output stream attribute gets the default value.
  • If there is a mismatch between the date type of the attribute that is specified in the <native_schema> element and the data type of the attribute in the input or output stream for the operators, an error occurs at run time.
  • If there are attributes in the input stream for the JMSSink operator that are not specified in the <native_schema> element, they are ignored.
  • If there are attributes in the <native_schema> element that are not present in the output stream for the JMSSource operator, the values for those attributes are not copied into the output stream.
  • The JMSSink operator might encounter values that have rstring, ustring, or blob data types that are longer than the length that is specified in the <native_schema> element. These values are truncated to fit the JMS message and a message is generated. For rstring or ustring types, the length is measured in bytes for the message class bytes and in characters for the map, stream, xml, wbe, and wbe22 message classes. For bytes message class, the truncation is in number of bytes and can lead to garbled values, which can result in a message that is not valid. The JMSSink operator might encounter values that have rstring, ustring or blob data types and are shorter than the required length, as specified in the <native_schema> element. The String is padded with spaces and the blob is padded with null values to make it have the correct length. For rstring or ustring attribute values, length is measured in bytes for bytes message class and in characters for map, stream, xml, wbe, and wbe22 message classes. The String is padded with spaces and the blob is padded with null values only when the message class is bytes.

Operators