Configure SOAP over JMS message types
We can configure the SOAP over Java Message Service (JMS) request or response messages to use either BytesMessage or TextMessage objects.
A web service must be implemented as an enterprise bean for accessibility through the JMS transport.
For the web services that use the emerging industry standard SOAP over JMS protocol, we can configure the SOAP over JMS requests and responses to specify whether the messages are transmitted within JMS BytesMessage (javax.jms.BytesMessage) or TextMessage (javax.jms.TextMessage) objects. The default message type is BytesMessage.
If the JMS message is a BytesMessage, the body of the JMS message is binary data.
If the JMS message is a TextMessage, the body of the JMS message is string data. For example, consider configuring text messages if to implement an audit or logging facility that requires JMS messages that are human readable.
When using SOAP over JMS as a transport for web services request and response messages, it is important to understand the following performance considerations when deciding whether to use BytesMessage or TextMessage objects:
- Memory usage -
The payload within a TextMessage is string-based and because the individual characters are based on the UTF-16 character encoding, the payload within a TextMessage is likely to occupy twice as many bytes as an equivalent BytesMessage. For request and response messages with small payloads, this difference in memory usage between TextMessages and BytesMessages might not be important, but for large payloads, the difference in memory usage might become more important to consider for the business environment.
- Binary attachments -
When a JMS TextMessage is used to transport request and response messages, any binary attachments that are included along with the SOAP message body must be base64-encoded because the underlying message payload is string-based. When binary attachments are base64-encoded, additional processing time and memory are required to perform the transformation on that data. As a result, it is possible that the base64-encoded binary attachment might be up to one-third larger than the original unencoded version of the attachment. In this case, if this larger encoded attachment part is then transported in a string-based message payload, the memory usage required to transport the binary attachment part might be almost three times the memory size of the original unencoded binary attachment within a BytesMessage.
- Specify the JMS message type for JAX-WS applications.
We can configure the JMS message type to specify BYTES or TEXT in the following ways when using JAX-WS applications. The JAX-WS Web services engine searches for the messageType property in the order of this list and uses the first setting that it finds.
- Set the messageType property in the JMS endpoint location URL string; for example:
jms:jndi:jms/MyQueue&....&messageType=TEXT
See the JMS endpoint URL syntax information for details on how to set this property using this method.
- Set the com.ibm.websphere.webservices.transport.jms.messageType custom property in the JMS transport policy binding in the administrative console. See the JMS transport bindings information for details on how to set this property using the administrative console.
- Set the com.ibm.websphere.webservices.transport.jms.messageType property programmatically on the RequestContext object of the JAX-WS BindingProvider.
- Set the com.ibm.websphere.webservices.transport.jms.messageType global system property in the JVM process under which the application server is running. See the Java virtual machine custom properties information for details on how to set this property using this method.
- Specify the JMS message type for JAX-RPC applications.
We can configure the JMS message type to specify BYTES or TEXT in the following ways when using JAX-RPC applications. The JAX-RPC Web services engine searches for the messageType property in the order of this list and uses the first setting that it finds.
- Set the messageType property in the JMS endpoint location URL string; for example:
jms:jndi:jms/MyQueue&....&messageType=TEXT
See the JMS endpoint URL syntax information for details on how to set this property using this method.
- Set the com.ibm.websphere.webservices.transport.jms.messageType property programmatically on the Stub or Call object of the client application..
- Set the com.ibm.websphere.webservices.transport.jms.messageType custom property in the client binding file, META-INF/ibm-webservicesclient-bnd.xmi.
- Set the com.ibm.websphere.webservices.transport.jms.messageType global system property in the JVM process under which the application server is running. See the Java virtual machine custom properties information for details on how to set this property using this method.
Results
You have configured a web service client to use either TextMessage or BytesMessage objects when using the SOAP over JMS protocol to transmit request and response messages.
Related tasks
Implement web services applications with JAX-WS Implement web services applications with JAX-RPC Implement static JAX-WS web services clients Implement JAX-RPC web services clients Configure endpoint URL information for JMS bindings
SOAP over JMS protocol JMS endpoint URL syntax Java virtual machine custom properties JMS transport bindings Web services specifications and APIs