Integration Server 10.3 | Built-In Services Reference Guide | JMS Folder | Summary of Elements in This Folder | pub.jms.wmjms:receiveStream
 
pub.jms.wmjms:receiveStream
WmPublic. Deprecated - There is no replacement service.
Receives a large message stream from a queue or topic on the webMethods Broker.
Input Parameters
consumer
Object A message consumer object that the service uses to receive the large message stream. Create the message consumer object using the pub.jms:createConsumer service.
timeout
java.lang.Long Optional. Time to wait (in milliseconds) for the first part of the message stream. If you do not specify a timeout value, the consumer does not wait.
Output Parameters
stream
Object A com.webmethods.jms.impl.WmJMSInputStream received by the consumer.
If the timeout value elapses before a message is received, stream will be null.
Usage Notes
webMethods Broker is deprecated, resulting in the deprecation of the pub.jms.wmjms:receiveStream service. There is no replacement service.
When using webMethods Broker as the JMS provider, the webMethods message streaming feature allows you to stream large amounts of data or a large file from a message producer to a message consumer.
Important:
You can only send and receive large messages from Integration Server when working with the webMethods Broker. For more information about how the webMethods message streaming feature works on the webMethods Broker, see the webMethods Broker Messaging Programmer’s Guide.
Large message streams cannot be sent or received as part of a transaction. If the JMS connection alias used by the consumer has a transaction type of LOCAL_TRANSACTION or XA_TRANSACTION, Integration Server throws an exception, specifically com.wm.app.b2b.server.jms.JMSSubsystemException, when it executes the pub.jms.wmjms:receiveStream service.
The consumer that you use to receive the message determines the destination from which this services receives messages and the JMS connection alias used to receive the messages. You can create a message consumer object using the pub.jms:createConsumer service.
The timeout value specifies how long the message consumer waits for the initial part of the message stream. If a message is not returned when the time out period elapses, the pub.jms.wmjms:receiveStream returns a null value.
The read timeout is the maximum length of time the consumer waits between receiving subsequent pieces of the message stream. After the read timeout elapses, the consumer calls InputStream.read() to read the next byte of the stream. If the next byte of the stream is not available, Integration Server throws a WmReadTimeoutException. The read timeout only applies after the consumer receives the first part of the message stream. The watt.server.jms.wmjms.lms.readTimeout property determines the read timeout value. The default is 30000 milliseconds.
Make sure to code your service to handle a WmReadTimeoutException. When an WmReadTimeoutException occurs, it suggests that Integration Server did not receive the entire message stream. When this occurs, you need to close the stream, which will acknowledge it to the webMethods Broker. You can close the stream from a Java service by calling Input.Stream.close. You can also close the stream using the pub.io:close service.
If the connection between the Integration Server and webMethods Broker fails during execution of the pub.jms.wmjms:receiveStream service, Integration Server throws a WmConnectionException. When this occurs, Integration Server rolls the message back to the webMethods Broker automatically. The message can be received when the connection to the webMethods Broker is re-established.
You can code your service to implement recoverability logic. This means that the next time the message stream is received, the service re-processes the message stream from the point at which processing stopped. To resume processing from the correct point, the service needs to keep track of the message ID and byte position. For more details, com.webmethods.jms.impl.WmJMSInputStream.
After the pub.jms.wmjms:receiveStream receives and processes the last part of the message stream, you need to close the stream. InputStream.read() returns "-1" when the end of the stream is reached. You can close the stream from a Java service by calling Input.Stream.close. You can also close the stream using the pub.io:close service. Closing the stream explicitly acknowledges the message to the provider.
The consumer used to receive large message streams from the webMethods Broker can specify an acknowledgmentMode of AUTO_ACKNOWLEDGE or CLIENT_ACKNOWLEDGE. webMethods Broker does not permit the use of the acknowledgmentMode is DUPS_OK_ACKNOWLEDGE for the webMethods message streaming feature.
You might want to use the scheduler capabilities within Integration Server to schedule a service that receives and then process large messages from webMethods Broker For more information about scheduling services, see Scheduling a User Task.