pub.publish:deliverAndWait
WmPublic. Requests a reply document from a specific client. The service waits for the reply or indicates that the
pub.publish:waitForReply service should retrieve the reply later.
Input Parameters
documentTypeName | String Fully qualified name of the publishable document type being delivered. The publishable document type must be in sync with the associated provider definition. The provider definition is a representation of the publishable document type and its properties on the provider. In the case of Universal Messaging, this is a channel. For Broker, it is a Broker document type. If the document type and provider definition are not synchronized, publication might fail. A publishable document type that uses the IS_LOCAL_CONNECTION alias cannot be delivered because delivery can only occur with a messaging provider (Broker or Universal Messaging). |
document | Document Document (IData object) conforming to the publishable document type in documentTypeName. |
receiveDocumentType Name
| String Optional. Fully qualified name of the publishable document type expected as a reply. If no value is specified, the service uses the first reply document of any type it receives, as long as the value of tag in the envelope of the reply document matches the tag in the envelope of the published document. All other reply documents are discarded. |
destId | String The destination to which the document will be delivered. You can specify the ID for an individual trigger or the default client of an Integration Server as the destination. When you deliver a document to the default client of Integration Server, Integration Server routes the delivered document to any subscribers on that Integration Server. When working with Universal Messaging, the destination ID is a subject. When working with Broker, the destination ID is the client ID. The destination ID for a trigger uses the following naming convention: clientPrefix _folderName_subfolderName_triggerName Where clientPrefix is the client prefix for the messaging connection alias used by the trigger, folderName is the folder in which the trigger is located, subfolderName is the subfolder in which the trigger is located, and triggerName is the local name of the trigger. For example, for a trigger with the fully qualified name myFolder.mySubFolder:myTrigger that uses a messaging connection alias with the client prefix “myAlias”, the destination ID of the trigger is: myAlias_myFolder_mySubfolder_myTrigger. The destination ID for the default client of an Integration Server uses the following naming convention: clientPrefix_DefaultClient Where clientPrefix is the client prefix for the messaging connection alias used by subscribers to the publishable document type on the Integration Server. Note: | The naming conventions for destination IDs are the same on Universal Messaging and Broker. If you change the messaging provider for a publishable document type and therefore the triggers that subscribe to it, you do not need to change the destID for any services that deliver a document to the trigger or default client. |
If you specify an invalid client ID, the Integration Server delivers the document to the messaging provider, but the messaging provider never delivers the document to the intended recipient and no error is produced. |
waitTime | String Optional. Specifies the time to wait (in milliseconds) for the response to arrive. If no value is specified, the service waits indefinitely until it receives a reply. |
async | String Optional. Flag specifying whether this is an asynchronous or synchronous request/reply. Set to:  true to indicate that this is an asynchronous request/reply. After publishing the document, the Integration Server executes the next step in the flow service immediately. Integration Server does not wait for a reply before continuing service execution. false to indicate that this is a synchronous request/reply. After publishing the document, Integration Server waits for a reply before executing the next step in the flow service. This is the default. |
Output Parameters
receivedDocument | Document A Document (IData object) received as reply. Important: | Integration Server treats all reply documents as volatile documents. If the Integration Server shuts down before processing the reply document, the reply document is lost. |
|
tag | String Conditional. A unique identifier for a deliver request. The Integration Server uses the tag value to match the requesting document with its corresponding reply document. The service produces a tag output value only when the async field is set to true. The tag value is required input when using the pub.publish:waitForReply service to retrieve the reply. Note: | The tag output value is the same value that the Integration Server places in the tag field of the request document's envelope. |
|
Usage Notes
You can use the pub.publish:deliverAndWait service to deliver a document to a destination where the destination can be a webMethods messaging trigger or the default client of an Integration Server. For a trigger that receives messages from Universal Messaging, you specify the subject that corresponds to the trigger or the Integration Server. For a trigger that receives messages from the Broker, you specify the client ID that corresponds to the trigger or the Integration Server.
To view the subjects for a trigger used with Universal Messaging, use Integration Server Administrator to open the Settings > Messaging > webMethods Messaging Trigger Management screen. In the Individual webMethods Messaging Trigger list, click the name of the trigger for which you want to view the client ID. On the Settings > Messaging > webMethods Messaging Trigger Management > triggerName screen, under Destination ID for Deliver, the Trigger Client ID field displays the client ID for the trigger. The Default Client ID field displays the client of the Integration Server.
To view a list of client IDs on the Broker, use the Broker user interface within My webMethods or use Designer to test the publishable document type that you want to deliver.
For a Universal Messaging connection alias the Publish Wait Time While Reconnecting value specifies the number of milliseconds that a publishing service using alias will wait for a connection to the Universal Messaging server to be re-established after the connection fails. If Integration Server re-establishes the connection before the Publish Wait Time While Reconnecting elapses, the publishing service continues executing. If the specified time elapses before a connection is re-established, the publishing service ends with an ISRuntimeException. Make sure to code your service to handle this situation.
You can use the pub.publish:deliverAndWait service to initiate and continue a private conversation between two clients. This is a variation of the request/reply model. One client executes a service that delivers a document to a specific client. This document requests information from the receiving client.
In a synchronous request/reply, the delivering service stops executing while it waits for a response. When the service receives a reply document from the specified client, the servers resumes executing. If the
waitTime elapses before the service receives a reply,
Integration Server ends the request, and the service returns a null document indicating that the request timed out.
Integration Server then executes the next step in the flow service. If a reply document arrives after the flow service resumes execution,
Integration Server rejects the document and creates a journal log message stating that the document was rejected because there is no service thread waiting for the document.
In an asynchronous request/reply, the delivering service continues executing the steps in the service after publishing the document. To retrieve the reply, the delivering service must invoke the
pub.publish:waitForReply service. If the wait time elapses before the
pub.publish:waitForReply service receives a document, the
pub.publish:waitForReply service returns a null document indicating that the request timed out.
A service that contains multiple asynchronous deliver requests allows the service to deliver all the requests before collecting the replies. This approach can be more efficient than delivering a request, waiting for a reply, and then delivering the next request.
If you create a service that contains multiple asynchronous requests, make sure to link the tag output to another field in the pipeline. Each asynchronous delivery produces a tag field in the pipeline. If the tag field is not linked to another field, the next asynchronous delivery request (that is, the next execution of the pub.publish:deliverAndWait service) will overwrite the first tag value.
Use pub.publish:deliverAndWait if you need to know that a specific client successfully received and processed the request document.
If the publishable document type in documentTypeName is associated with a Universal Messaging connection alias, the Enable Request/Reply Channel and Listener check box must be selected for the alias. When this check box is selected, Integration Server ensures that a request/reply channel exists for the Universal Messaging connection alias on the Universal Messaging server and that Integration Server has a listener that subscribes to the alias-specific request/reply channel. If the check box is cleared, there will be no channel in which Universal Messaging can collect replies and no listener with which Integration Server can retrieve replies. The pub.publish:deliverAndWait service will end with a ServiceException if the Enable Request/Reply Channel and Listener check box is not selected for the Universal Messaging connection alias.
If outbound client-side queuing is disabled (the watt.server.publish.useCSQ property is set to "never"), Integration Server throws a ServiceException if the webMethods Broker is not available when this service executes. Make sure to code your service to handle this situation.
If the pub.publish:deliverAndWait services publishes a document to Universal Messaging and use of the client side queue is disabled for the Universal Messaging connection alias, Integration Server throws an ISRuntimeException if the Universal Messaging server is not available when the service executes. Make sure to code your service to handle this situation.
For more information about how to build a services that initiate synchronous or asynchronous request/reply scenarios, see the Publish-Subscribe Developer’s Guide.
See Also
