JMS Folder

Usage Notes

Use this service to acknowledge a message retrieved from the JMS provider if:

• The message was received using the pub.jms:receive service, and
• The message consumer used to retrieve the message has an acknowledgmentMode set to CLIENT_ACKNOWLEDGE or DUPS_OK_ACKNOWLEDGE. For more information about creating a message consumer, see pub.jms:createConsumer.

A message is not considered to be successfully consumed until it is acknowledged.

See Also

• pub.jms:createConsumer
• pub.jms:receive

Usage Notes

Use this specification as the signature for JMS trigger services that will retrieve and process a batch of messages.

If you want to use a JMS trigger to retrieve and process one message at a time, use pub.jms:triggerSpec to declare the signature of the JMS trigger service.

See Also

• pub.jms:triggerSpec
• pub.jms:JMSMessage

Usage Notes

A message consumer is a webMethods object that encapsulates the actual javax.jms.MessageConsumer and javax.jms.Session.

Any message consumers created during the execution of a service will be closed automatically when the top-level service completes. If the consumer closes without acknowledging messages, messages are implicitly recovered back to the JMS provider.

The use of pub.jms:createConsumer in conjunction with pub.jms:receive is an alternative to using JMS triggers. Use the pub.jms:createConsumer service to create a message consumer. Use the pub.jms:receive to actively receive messages from a destination on the JMS provider.

To create a durable subscriber, set the destinationType to TOPIC and specify a durableSubscriberName. If you select TOPIC, but do not specify a durableSubscriberName, Integration Server creates a nondurable subscriber.

A durable subscription allows subscribers to receive all the messages published on a topic, including those published while the subscriber is inactive.

If a durable subscription already exists for the specified durable subscriber on the JMS provider, this service resumes the subscription.

A non-durable subscription allows subscribers to receive messages on their chosen topic, only if the messages are published while the subscriber is active. A non-durable subscription lasts the lifetime of its message consumer.

If the acknowledgment Mode field is set to CLIENT_ACKNOWLEDGE, you must acknowledge messages received by this consumer to the JMS provider using the pub.jms:acknowledge service.

If the message consumer created by this service will be used to receive large message streams from the webMethods Broker, make sure to specify an acknowledgmentMode of AUTO_ACKNOWLEDGE or CLIENT_ACKNOWLEDGE. If the acknowledgmentMode is DUPS_OK_ACKNOWLEDGE, the message consumer cannot be used to receive large message streams.

If you specify a destination that does not exist in the JNDI namespace and the JMS connection alias specified for the connectionAliasName input parameter is configured to create administered objects on demand, Integration Server creates the destination when the service executes. The ability to create administered objects on demand applies only when Universal Messaging is the JMS provider. For more information about creating administered objects on demand, see Creating Administered Objects .

See Also

• pub.jms:acknowledge
• pub.jms:receive
• pub.jms:reply
• pub.jms:send
• pub.jms:sendAndWait

Usage Notes

The pub.jms:documentResolverSpec must be used as the signature for a document resolver service used to determine the processing status of a JMS message received by a JMS trigger. For information about building a document resolver service and enabling exactly once processing for a JMS message, see Using webMethods Integration Server to Build a Client for JMS .

Use pub.publish:documentResolverSpec as the signature for a document resolver service used to determine the status of document received a webMethods messaging trigger.

See Also

• pub.jms:JMSMessage
• pub.publish:documentResolverSpec

See Also

• pub.jms:receive
• pub.jms:send
• pub.jms:sendAndWait

Usage Notes

Use this service to receive a message from the JMS provider on demand. Receiving a message on demand provides more control over when and how Integration Server receives a message; however, it may not be as efficient or practical as using a JMS trigger to listen for and then receive the message.

To listen for messages and receive them when they are available, create a JMS trigger that listens to the destination. For more information about creating a JMS trigger, see the webMethods Service Development Help .

If the timeout period elapses before a message is received, the value of JMSMessage is null.

The message 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.

After you receive a message, you need to invoke a service that processes the message.

If the acknowledgment mode of the consumer is set to CLIENT_ACKNOWLEDGE, use the pub.jms:acknowledge service to acknowledge the message to the JMS provider.

See Also

• pub.jms:acknowledge
• pub.jms:createConsumer

Usage Notes

The pub.jms:reply service creates a JMS message (javax.jms.Message) based on input provided to the service or takes an existing JMS message and sends it to the JMS provider as a reply to a requesting client.

The pub.jms:reply service sends the reply message using the same connection that was used to retrieve the message.

The JMSReplyTo field in the request message is set by the sending client and indicates the destination to which the reply will be sent. The replying Integration Server automatically sets this value when it executes the pub.jms:reply service.

When executing the pub.jms:replyservice, Integration Server automatically sets the value of the JMSCorrelationID field in the JMSReplyMessage. Integration Server uses the value of the wm_tag field, uuid field, or the JMSMessageID field in the requesting JMS message to correlate the request and the response. If the wm_tag field is populated in the request message, Integration Serveruses the wm_tag value as the JMSCorrelationID. If the request message does not specify a wm_tag value and you specify the uuid when sending the request, the replying Integration Serverwill use the uuid as the JMSCorrelationID of the reply message. If the request message does not specify a wm_tag value and you do not specify a uuid, the replying Integration Serveruses the JMSMessageID of the request message as the JMSCorrelationID of the reply message.

When replying to a message received using pub.jms:receive, you need to specify the input parameters consumer and message.

If a transaction has not yet been started, the transaction manager starts a transaction context for an implicit transaction when Integration Server executes a pub.jms:reply service that uses a transacted JMS connection alias. A JMS connection alias is considered to be transacted when it has a transaction type of XA TRANSACTION or LOCAL TRANSACTION.

If you want more control over the actual javax.jms.Message that Integration Server sends to the JMS provider, you can create a Java service that calls the com.wm.app.b2b.server.jms.producer.ProducerFacade class, which will create a javax.jms.Message. See:

• com.wm.app.b2b.server.jms.producer.ProducerFacade.createBytesMessage(String)
• com.wm.app.b2b.server.jms.producer.ProducerFacade.createMapMessage(String)
• com.wm.app.b2b.server.jms.producer.ProducerFacade.createObjectMessage(String)
• com.wm.app.b2b.server.jms.producer.ProducerFacade.createStreamMessage(String)
• com.wm.app.b2b.server.jms.producer.ProducerFacade.createTextMessage(String)

The Java service calling this API must return an Object of type javax.jms.Message, which can then be mapped to the JMSMessage/body/message input parameter of the pub.jms:reply service.

When creating the javax.jms.Message with the com.wm.app.b2b.server.jms.producer.ProducerFacade, you can use the javax.jms.Message setter methods to set the values of the message headers and properties directly. You can also set the value of message headers and properties using the input parameters of the pub.jms:replyservice that you use to send the message. If you set the message headers and properties both ways, the values provided to the pub.jms:replyservice take precedence.

Software AG recommends that you use a pub.jms:reply service to create and send the JMS message. This may provide better performance on average. However, if you want to send a StreamMessage or a MapMessage, you need to use the appropriate com.wm.app.b2b.server.jms.producer.ProducerFacade API.

When using Universal Messaging as the JMS provider, the JMS client can use synchronous or asynchronous publishing. To ensure delivery of a persistent JMS message (deliveryMode is set to PERSISTENT), Integration Server always uses synchronous publishing to send a persistent JMS message to Universal Messaging.

Message priority is not supported when Universal Messaging is the JMS provider. Any value specified in the priority field will be ignored.

See Also

• pub.jms:createConsumer
• pub.jms:receive

Usage Notes

The pub.jms:send service creates a JMS message (javax.jms.Message) based on input provided to the service or takes an existing JMS message and sends it to the JMS provider.

If a transaction has not yet been started, the transaction manager starts a transaction context for an implicit transaction when Integration Server executes a pub.jms:send service that uses a transacted JMS connection alias. A JMS connection alias is considered to be transacted when it has a transaction type of XA TRANSACTION or LOCAL TRANSACTION.

You can add properties to a JMS message when building a flow service that invokes this service. In Designer, use the Pipeline view to add a new variable to JMSMessage/properties document.

If the JMS connection alias specified for connectionAliasName uses the native webMethods API, you need to specify destinationName and destinationType to indicate where the webMethods Broker should send the message.

If you specify a destination that does not exist in the JNDI namespace and the JMS connection alias specified for the connectionAliasName input parameter is configured to create administered objects on demand, Integration Server creates the destination when the service executes. The ability to create administered objects on demand applies only when Universal Messaging is the JMS provider. For more information about creating administered objects on demand, see Creating Administered Objects .

Integration Server creates the output parameter JMSMessage because some of the header fields in a JMS message are populated by the JMS provider after the message is sent. For example, the header field JMSMessageID is not in the JMS message sent by Integration Server, but JMSMessageID is in the header after the JMS provider receives the message.

When sending a JMS message to Universal Messaging, Integration Server sets the JMSMessageID.

Each JMS connection alias can be configured to have its own client side queue. A JMS connection alias has a client side queue if the Maximum CSQ Size property for the alias is set to a value other than 0 (zero). If you want to use the client side queue with the pub.jms:send service, the JMS connection alias specified for connectionAliasName must be configured to have a client side queue. If the JMS connection alias is configured to use a client side queue and useCSQ is set to true, Integration Server places messages in the client side queue if the JMS provider is not available at the time the pub.jms:send service executes. When the JMS provider becomes available, Integration Server sends messages from the client side queue to the JMS provider.

The JMS provider populates the header fields in the JMSMessage output parameter after it successfully receives the sent message from Integration Server. If the JMS provider is not available at the time pub.jms:sendexecutes and useCSQ is set to true, the header fields in the output JMSMessage will not be populated. Instead these fields will be blank or be set to 0 (zero).

If the client side queue is not in use (useCSQ is set to false and/or the JMS connection alias is not configured to use a client side queue, Integration Server throws an ISRuntimeException if the JMS provider is not available when this service executes. Make sure to code your service to handle this situation.

A JMS connection alias can be configured so that Integration Server retries the pub.jms:send service automatically when the service fails because of a transient error. For more information about configuring a JMS connection alias for automatic retry, see Working with JMS Connection Aliases .

When sending a message as part of a transaction the client side queue cannot be used. That is, the useCSQ field should be set to false. If useCSQ is set to true, Integration Server throws a JMSSubsystemException when the pub.jms:send service executes. A JMS message is sent as part of a transaction if the JMS connection alias specified in connectionAliasName:

• Uses a transaction type of LOCAL_TRANSACTION or XA_TRANSACTION.
• Connects to the webMethods Broker using a cluster connection factory to which the multisend guaranteed policy is applied. Integration Server uses an XA transaction to perform a two-phase commit when sending JMS messages.

If you want more control over the actual javax.jms.Message that Integration Server sends to the JMS provider, you can create a Java service that calls the com.wm.app.b2b.server.jms.producer.ProducerFacade class, which will create a javax.jms.Message. See:

• com.wm.app.b2b.server.jms.producer.ProducerFacade.createBytesMessage(String)
• com.wm.app.b2b.server.jms.producer.ProducerFacade.createMapMessage(String)
• com.wm.app.b2b.server.jms.producer.ProducerFacade.createObjectMessage(String)
• com.wm.app.b2b.server.jms.producer.ProducerFacade.createStreamMessage(String)
• com.wm.app.b2b.server.jms.producer.ProducerFacade.createTextMessage(String)

The Java service calling this API must return an Object of type javax.jms.Message, which can then be mapped to the JMSMessage/body/message input parameter of the pub.jms:send service.

When creating the javax.jms.Message with the com.wm.app.b2b.server.jms.producer.ProducerFacade, you can use the javax.jms.Message setter methods to set the values of the message headers and properties directly. You can also set the value of message headers and properties using the input parameters of the pub.jms:sendservice that you use to send the message. If you set the message headers and properties both ways, the values provided to the pub.jms:sendservice take precedence.

Software AG recommends that you use a pub.jms:send service to create and send the JMS message. This may provide better performance on average. However, if you want to send a StreamMessage or a MapMessage, you need to use the appropriate com.wm.app.b2b.server.jms.producer.ProducerFacade API.

To send a StreamMessage, create a Java service that calls com.wm.app.b2b.server.jms.producer.ProducerFacade.createStreamMessage(String).The Java service calling this API must return an Object of type javax.jms.Message. Map the javax.jms.Message object to the JMSMessage/body/message input parameter of the pub.jms:send service.

To send a MapMessage, create a Java service that calls com.wm.app.b2b.server.jms.producer.ProducerFacade.createMapMessage(String).The Java service calling this API must return an Object of type javax.jms.Message. Map the javax.jms.Message object to the JMSMessage/body/message input parameter of the pub.jms:send service.

If you use the input parameter JMS_WMClusterNodes to override the policy applied to the cluster connection factory, make sure to code the invoking service to handle any exception that the Broker Server throws when policy requirements are not or cannot be met. For more information about policy override scenarios that might result in an exception from Broker Server, see Using webMethods Integration Server to Build a Client for JMS .

You can use the pub.jms:send service to specify a destination for response messages when you do not need to wait for the response. The act of waiting for a response message comes with extra overhead for Integration Server which is unnecessary if you merely want to specify a JMSReplyTo destination but do not want the sending service to wait for a reply.

When executing the pub.jms:send service with a valid value for the JMSMessage/header/replyTo parameter, Integration Server creates the javax.jms.Destination and maps it to the JMSReplyTo field within the message header. Integration Server sends the message and returns immediately. The service does not wait for the response message. If JMSMessage/header/replyTo is empty, then Integration Server does not set the JMSReplyTo header for the JMS message. If JMSMessage/header/replyTo is invalid, then Integration Server throws a ServiceException.

When the body of the message is supplied as an IData in the JMSMessage/body/data input parameter, the pub.jms:send service sends a message that is twice the size of the original IData. This occurs because Integration Server encodes the IData as a byte array using IDataBinCoder which encodes data as two-byte instead of single-byte when sending the message. This causes a dramatic increase in message size. When Universal Messaging is the JMS provider, this can result in the default 20 MB max buffer size being exceeded when the IData for the message body is just 10 MB. To resolve this issue, Integration Server includes a custom property to indicate that the message should be encoded as XML and decoded from XML instead of as a byte array. When creating a service that invokes the pub.jms:send add the following custom property of type String and value to the JMSMessage/properties document in the pipeline: $coderType = idata_xml_bytes. The presence of the custom property $coderType and the value idata_xml_bytes instructs the sending Integration Server to encode the IData message as XML using IDataXMLCoder. The same property and value also instructs the receiving Integration Server to decode the JMS message as XML to IData.

Usage Notes

Thepub.jms:sendAndWait service creates a JMS message (javax.jms.Message) based on input provided to the service or takes an existing JMS message, sends it to the JMS provider and optionally, waits for a reply.

If a transaction has not been started, the transaction manager starts a transaction context for an implicit transaction when Integration Server executes a pub.jms:sendAndWait service that uses a transacted JMS connection alias. A JMS connection alias is considered to be transacted when it has a transaction type of XA TRANSACTION or LOCAL TRANSACTION.

You can add properties to a JMS message when building a flow service that invokes this service. In Designer, use the Pipeline view to add a new variable to JMSMessage/properties document.

If the JMS connection alias specified for connectionAliasName uses the native webMethods API, you need to specify destinationName and destinationType to indicate where the webMethods Broker should send the message.

If you specify a destination that does not exist in the JNDI namespace and the JMS connection alias specified for the connectionAliasName input parameter is configured to create administered objects on demand, Integration Server creates the destination when the service executes. The ability to create administered objects on demand applies only when Universal Messaging is the JMS provider. For more information about creating administered objects on demand, see Creating Administered Objects .

Integration Server creates the output parameter JMSMessage because some of the header fields in a JMS message are populated by the JMS provider after the message is sent. For example, the header field JMSMessageID is not in the JMS message sent by Integration Server, but JMSMessageID is in the header after the JMS provider receives the message.

When sending a JMS message to Universal Messaging, Integration Server sets the JMSMessageID.

You can use the pub.jms:sendAndWait service to initiate a request/reply. The sending client sends a request for information to either a topic or queue. Clients that subscribe to the destination compose and send a reply document that contains the information requested by the sender.

A single request might receive many reply messages. Integration Server that sent the request uses only the first reply document it receives from the JMS provider. Integration Server discards all other replies. First is arbitrarily defined. There is no guarantee provided for the order in which the JMS provider processes incoming replies.

The pub.jms:sendAndWait service can be useful in situations where multiple sources contain the response data. For example, suppose that an enterprise uses one application for managing customer data, another for storing master customer records, and a mainframe system for saving customer lists. Each of these applications could answer a request for customer data. The requesting service will use the first reply message it receives.

The pub.jms:sendAndWait service can issue a request/reply in a synchronous or asynchronous manner.

• In a synchronous request/reply, the service that sends the request stops executing while it waits for a reply. When the service receives a reply message, the service resumes execution. If the timeout elapses before the service receives a reply, Integration Server ends the request, and the service returns a null message that indicates that the request timed out. Integration Server then executes the next step in the flow service.
• In an asynchronous request/reply, the service that sends the request continues executing the steps in the service after sending the message. To retrieve the reply, the requesting flow service must invoke the pub.jms:waitForReply service. If the timeout value specified in pub.jms:waitForReply elapses before the pub.jms:waitForReply service receives a reply, the pub.jms:waitForReply service returns a null document indicating that the request timed out.

When using pub.jms:sendAndWait to issue a request/reply, you must specify a queue as the value of the destinationNameReplyTo parameter. In a request/reply scenario, it is possible that the message consumer created to receive the reply might be created after the reply message is sent. (In a synchronous request/reply, the pub.jms:sendAndWait service creates the message consumer. In an asynchronous request/reply, the pub.jms:waitForReply service or a custom solution, such as a JMS trigger, creates the message consumer.) If the reply destination is a queue, a message consumer can receive messages published to the queue regardless of whether the message consumer was active at the time the message was published. If the destination is a topic, a message consumer can receive only messages published when the message consumer was active. If the reply is sent to a topic before the message consumer is created, the message consumer will not receive the reply. Consequently, when creating a request/reply, the destinationNameReplyTo parameter should specify the name or lookup name of a queue.

A service that contains multiple asynchronous send and wait invocations allows the service to send all the requests before collecting the replies. This approach can be more efficient than sending a request, waiting for a reply, and then sending the next request.

The replying Integration Server uses the value of the wm_tag, uuid or JMSMessageID in the requesting JMS message to correlate the request and the response. For more information, see pub.jms:reply.

If you create a service that contains multiple asynchronous requests, make sure to link the JMSMessage field (uuid or JMSMessageID) whose value will be used as the reply message's JMSCorrelationID to another field in the pipeline. Each asynchronous request produces a JMSMessage document in the pipeline. If you do not link the uuid or JMSMessageID field from the JMSMessage document to another field, the next asynchronous request (that is, the next execution of the pub.jms:sendAndWait service), will overwrite the previous JMSMessage document. When you invoke the pub.jms:waitForReply service, the pipeline will contain only the input needed to retrieve the reply to the last request. The pipeline will not contain the information needed to retrieve replies to the previous requests. (That is, there will be nothing to map to the correlationID input parameter of the pub.jms:waitForReply service.)

Each JMS connection alias can be configured to have its own client side queue. A JMS connection alias has a client side queue if the Maximum CSQ Size property for the alias is set to a value other than 0 (zero). If you want to use the client side queue with the pub.jms:sendAndWait service, the JMS connection alias specified for connectionAliasName must be configured to have a client side queue. If the JMS connection alias is configured to use a client side queue and useCSQ is set to true, Integration Server places messages in the client side queue if the JMS provider is not available at the time the pub.jms:sendAndWait service executes. When the JMS provider becomes available, Integration Server sends messages from the client side queue to the JMS provider.

If the client side queue is not used (useCSQ is set to false or the JMS connection alias is not configured to have a client side queue), Integration Server throws an ISRuntimeException if the JMS provider is not available when this service executes. Make sure to code your service to handle this situation.

Integration Server can write messages to the client side queue only for messages sent as part of an asynchronous request/reply. That is, if async is set to true (the default) and the JMS provider is not available at the time this service executes, Integration Server places the message in the client side queue. The client side queue cannot be used for a synchronous request/reply.

The client side queue cannot be used if the reply destination is a temporary queue. Consequently, if useCSQ is set to true, values must be specified for the destinationNameReplyTo and destinationTypeReplyTo input parameters. If these parameters are not specified, Integration Serverthrows the following ServiceException when it executes the pub.jms:sendAndWait service: [ISS.0134.9082] The client side queue cannot be used with a send and wait request if the reply destination is a temporary queue.

The JMS provider populates the header fields in the JMSMessage output parameter after it successfully receives the sent message from Integration Server. If the JMS provider is not available at the time the pub.jms:sendAndWait executes and useCSQ is set to true, the header fields in the output JMSMessage will not be populated. Instead these fields will be blank or be set to 0 (zero).

The pub.jms:waitForReply service cannot be used to retrieve response to requests that were routed through the client side queue. To retrieve the response, create a JMS trigger that subscribes to the reply to queue.

If the pub.jms:sendAndWait service executes and the message is sent directly to the JMS provider (i.e., it is not sent to the client side queue), the JMSMessage\header\JMSMessageID contains a unique identifier assigned by the JMS provider. If the JMSMessageID field is null after the service executes, the JMS provider was not available at the time the service executed.Integration Server wrote the message to the client side queue.

When sending a message as part of a transaction client side queuing cannot be used. That is, the useCSQ field should be set to false. If useCSQ is set to true, Integration Server throws a JMSSubsystemException when the pub.jms:sendAndWait service executes. A JMS message is sent as part of a transaction if the JMS connection alias specified in connectionAliasName:

• Uses a transaction type of LOCAL_TRANSACTION or XA_TRANSACTION.
• Connects to the webMethods Broker using a cluster connection factory to which the multisend guaranteed policy is applied. Integration Server uses an XA transaction to perform a two-phase commit when sending JMS messages.

If you do not specify a destination for reply messages, Integration Server uses a temporaryQueue to receive the reply. A temporaryQueue is a queue object created for the duration of a particular connection. It can only be consumed by the connection from which it was created.

If you want more control over the actual javax.jms.Message that Integration Server sends to the JMS provider, you can create a Java service that calls the com.wm.app.b2b.server.jms.producer.ProducerFacade class, which will create a javax.jms.Message. See:

• com.wm.app.b2b.server.jms.producer.ProducerFacade.createBytesMessage(String)
• com.wm.app.b2b.server.jms.producer.ProducerFacade.createMapMessage(String)
• com.wm.app.b2b.server.jms.producer.ProducerFacade.createObjectMessage(String)
• com.wm.app.b2b.server.jms.producer.ProducerFacade.createStreamMessage(String)
• com.wm.app.b2b.server.jms.producer.ProducerFacade.createTextMessage(String)

The Java service calling this API must return an Object of type javax.jms.Message, which can then be mapped to the JMSMessage/body/message input parameter of the pub.jms:sendAndWait service.

When creating the javax.jms.Message with the com.wm.app.b2b.server.jms.producer.ProducerFacade, you can use the javax.jms.Message setter methods to set the values of the message headers and properties directly. You can also set the value of message headers and properties using the input parameters of the pub.jms:sendAndWaitservice that you use to send the message. If you set the message headers and properties both ways, the values provided to the pub.jms:sendAndWaitservice take precedence.

Software AG recommends that you use a pub.jms:sendAndWait service to create and send the JMS message. This method may provide better performance on average. However, if you want to send a StreamMessage or a MapMessage, you need to use the appropriate com.wm.app.b2b.server.jms.producer.ProducerFacade API.

To send a StreamMessage, create a Java service that calls com.wm.app.b2b.server.jms.producer.ProducerFacade.createStreamMessage(String).The Java service calling this API must return an Object of type javax.jms.Message. Map the javax.jms.Message object to the JMSMessage/body/message input parameter of the pub.jms:sendAndWait service.

To send a MapMessage, create a Java service that calls com.wm.app.b2b.server.jms.producer.ProducerFacade.createMapMessage(String).The Java service calling this API must return an Object of type javax.jms.Message. Map the javax.jms.Message object to the JMSMessage/body/message input parameter of the pub.jms:sendAndWait service.

If you use the input parameter JMS_WMClusterNodes to override the policy applied to the cluster connection factory, make sure to code the invoking service to handle any exception that the Broker Server throws when policy requirements are not or cannot be met. For more information about policy override scenarios that might result in an exception from Broker Server, see Using webMethods Integration Server to Build a Client for JMS .

When using Universal Messaging as the JMS provider, the JMS client can use synchronous or asynchronous publishing. To ensure delivery of a persistent JMS message (deliveryMode is set to PERSISTENT), Integration Server always uses synchronous publishing to send a persistent JMS message to Universal Messaging.

You can use the pub.jms:send service to specify a destination for response messages when you do not need to wait for the response. The act of waiting for a response message comes with extra overhead for Integration Server which is unnecessary if you merely want to specify a JMSReplyTo destination but do not want the sending service to wait for a reply. For more information, see the JMSMessage/header/replyTo input parameter description and Usage Notes in pub.jms:JMSMessage.

See Also

• pub.jms:reply
• pub.jms:waitForReply

Usage Notes

The pub.jms:sendBatch service can be used with webMethods Broker or Universal Messaging only. If you set the connectionAliasName parameter to a JMS connection alias that uses a different JMS provider, the pub.jms:sendBatch service ends with an exception.

The pub.jms:sendBatch service creates multiple JMS messages (javax.jms.Message) based on input provided to the service or takes existing JMS messages and sends them to the JMS provider.

Sending a batch of messages using the pub.jms:sendBatch service is an all or nothing operation. If Integration Server or the JMS provider determines that one of the messages is not valid during a pre-processing check, none of the messages will be sent. Make sure to code your service to handle this possibility.

When Integration Server executes a pub.jms:sendBatch service that uses a transacted JMS connection alias, Integration Server sends the messages as part of a transaction. If a transaction has not yet been started, the transaction manager starts a transaction context for an implicit transaction A JMS connection alias is considered to be transacted when it has a transaction type of XA TRANSACTION or LOCAL TRANSACTION.

You can add properties to a JMS message when building a flow service that invokes this service. To add a new property, use the Pipeline to add a new variable to JMSMessages/properties document.

If the JMS connection alias specified for connectionAliasName uses the native webMethods API, you need to specify destinationName and destinationType to indicate where the webMethods Broker should send the message.

If you specify a destination that does not exist in the JNDI namespace and the JMS connection alias specified for the connectionAliasName input parameter is configured to create administered objects on demand, Integration Server creates the destination when the service executes. The ability to create administered objects on demand applies only when Universal Messaging is the JMS provider. For more information about creating administered objects on demand, see Creating Administered Objects .

Integration Server creates the output parameter JMSMessages because some of the header fields in a JMS message are populated by the JMS provider after the message is sent. For example, the header field JMSMessageID is not in the JMS message sent by Integration Server, but JMSMessageID is in the header after the JMS provider receives the message.

When sending a JMS message to Universal Messaging, Integration Server sets the JMSMessageID.

Each JMS connection alias can be configured to have its own client side queue. A JMS connection alias has a client side queue if the Maximum CSQ Size property for the alias is set to a value other than 0 (zero). If you want to use the client side queue with the pub.jms:sendBatch service, the JMS connection alias specified for connectionAliasName must be configured to have a client side queue. If the JMS connection alias is configured to use a client side queue and useCSQ is set to true, Integration Server places messages in the client side queue if the JMS provider is not available at the time the pub.jms:sendBatch service executes. When the JMS provider becomes available, Integration Server sends messages from the client side queue to the JMS provider.

If the client side queue is not used (useCSQ is set to false or the JMS connection alias is not configured to have a client side queue), Integration Server throws an ISRuntimeException if the JMS provider is not available when this service executes. Make sure to code your service to handle this situation.

When sending a message as part of a transaction, the client side queue cannot be used. The useCSQ field should be set to false. If useCSQ is set to true, Integration Server throws a JMSSubsystemException when the pub.jms:send service executes. A JMS message is sent as part of a transaction if the JMS connection alias specified in connectionAliasName uses a transaction type of LOCAL_TRANSACTION or XA_TRANSACTION.

The JMS provider populates the header fields in the JMSMessages output parameter after it successfully receives the sent message from Integration Server. If the JMS provider is not available at the time pub.jms:sendBatchexecutes and useCSQ is set to true, the header fields in the output JMSMessages will not be populated. Instead these fields will be blank or be set to 0 (zero).

If you want more control over the actual javax.jms.Message that Integration Server sends to the JMS provider, you can create a Java service that calls the com.wm.app.b2b.server.jms.producer.ProducerFacade class, which will create a javax.jms.Message. See:

• com.wm.app.b2b.server.jms.producer.ProducerFacade.createBytesMessage(String)
• com.wm.app.b2b.server.jms.producer.ProducerFacade.createMapMessage(String)
• com.wm.app.b2b.server.jms.producer.ProducerFacade.createObjectMessage(String)
• com.wm.app.b2b.server.jms.producer.ProducerFacade.createStreamMessage(String)
• com.wm.app.b2b.server.jms.producer.ProducerFacade.createTextMessage(String)

The Java service calling this API must return an Object of type javax.jms.Message, which can then be mapped to the JMSMessage/body/message input parameter of the pub.jms:send service.

When creating the javax.jms.Message with the com.wm.app.b2b.server.jms.producer.ProducerFacade, you can use the javax.jms.Message setter methods to set the values of the message headers and properties directly. You can also set the value of message headers and properties using the input parameters of the pub.jms:sendservice that you use to send the message. If you set the message headers and properties both ways, the values provided to the pub.jms:sendservice take precedence.

Software AG recommends that you use a pub.jms:sendBatch service to create and send the JMS message. This may provide better performance on average. However, if you want to send a StreamMessage or a MapMessage, you need to use the appropriate com.wm.app.b2b.server.jms.producer.ProducerFacade API.

To send a StreamMessage, create a Java service that calls com.wm.app.b2b.server.jms.producer.ProducerFacade.createStreamMessage(String).The Java service calling this API must return an Object of type javax.jms.Message. Map the javax.jms.Message object to the JMSMessage/body/message input parameter of the pub.jms:send service.

To send a MapMessage, create a Java service that calls com.wm.app.b2b.server.jms.producer.ProducerFacade.createMapMessage(String).The Java service calling this API must return an Object of type javax.jms.Message. Map the javax.jms.Message object to the JMSMessage/body/message input parameter of the pub.jms:send service.

When using Universal Messaging as the JMS provider, the JMS client can use synchronous or asynchronous publishing. To ensure delivery of a persistent JMS message (deliveryMode is set to PERSISTENT), Integration Server always uses synchronous publishing to send a persistent JMS message to Universal Messaging.

Usage Notes

If you want to use a JMS trigger to retrieve and process multiple messages in one batch, use pub.jms:batchTriggerSpec to declare the inputs and outputs of the JMS trigger service.

See Also

• pub.jms:batchTriggerSpec
• pub.jms:JMSMessage

Usage Notes

Integration Server uses the value of the uuid or JMSMessageID fields in the requesting JMS message to correlate the response to the request. If you specify the uuid when sending the request, the replying Integration Server will use the uuid as the JMSCorrelationID of the reply message (JMSReplyMessage). If you do not specify a uuid, the replying Integration Server uses the JMSMessageID set by the JMS provider as the JMSCorrelationID of the reply message (JMSReplyMessage).

If you set the uuid in the JMS message request, you can link the value of the uuid field from the JMSMessage produced by the pub.jms:sendAndWait service to the correlationID input field of the pub.jms:waitForReply service. If you did not specify a uuid, you can link the JMSMessageID field from the JMSMessage produced by the pub.jms:sendAndWait to the correlationID input field.

The timeout value of the sending service specifies how long Integration Server will keep the request open while waiting for a reply. If a reply is not available at the time Integration Server executes the pub.jms:waitForReply service, Integration Server continues to wait for the document until the time specified in the timeout parameter elapses. If the service does not receive a reply by the time the timeout interval elapses, the service returns a null document.

The pub.jms:waitForReply service cannot be used to retrieve response to requests that were routed through the client side queue. To retrieve the response, create a JMS trigger that subscribes to the reply queue.

If the pub.jms:sendAndWait service executes and the message is sent directly to the JMS provider (i.e., it is not sent to the client side queue), the JMSMessage\header\JMSMessageID contains a unique identifier assigned by the JMS provider. If the JMSMessageID field is null after the service executes, the JMS provider was not available at the time the service executed. Integration Server wrote the message to the client side queue.

See Also

• pub.jms:sendAndWait

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.

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 .

Usage Notes

webMethods Broker is deprecated, resulting in the deprecation of the pub.jms.wmjms:sendStream service. There is no replacement service.

When using the 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. 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 connectionAliasName specifies a JMS connection alias with a transaction type of LOCAL_TRANSACTION or XA_TRANSACTION, Integration Server throws the exception com.wm.app.b2b.server.jms.JMSSubsystemException when it executes the pub.jms.wmjms:sendStream service.

If the connection between Integration Server and the webMethods Broker fails before the pub.jms.wmjms:sendStream sends the entire message stream, you need to re-send the entire stream when the connection is re-established.