WmPublic. Receives a large message stream from a queue or topic on the webMethods Broker.

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.

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 webMethods Integration Server Administrator’s Guide.