pub.publish:publishAndWait
WmPublic. Broadcasts a request for a document from any client subscribed to a specific document type. 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 published. If you intend to publish the document to a messaging provider (Broker or Universal Messaging), 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. |
document | Document Document (IData object) conforming to the document type in documentTypeName. |
receiveDocumentType Name
| String Optional. Fully qualified name of the 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 reply document envelope matches the tag in the envelope of the published document. All other reply documents are discarded. |
local | String Optional. Flag specifying whether the document is to be published locally or to the webMethods Broker. Set to:  true to publish locally (to this Integration Server only). false to publish to the webMethods Broker. This is the default. The local parameter is applicable only when the publishable document type uses Broker as the messaging provider. The local parameter is applicable only when the publishable document type uses Broker as the messaging provider. If the publishable document type specifies the IS_LOCAL_CONNECTION alias, the document can be published locally only. Integration Server ignores the value of local. A publishable document type that specifies Universal Messaging as the messaging provider cannot be published locally. If the document type in documentTypeName is associated with a Universal Messaging connection alias, Integration Server ignores the value of local. |
waitTime | String Optional. Time to wait (in milliseconds) for the response to arrive. If no value is specified, the service waits indefinitely for a reply. |
async | String Optional. Flag specifying whether this is an asynchronous or synchronous publish. 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. The 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, the Integration Server waits for a reply before executing the next step in the flow service. This is the default. |
Output Parameters
receivedDocument | Document Document (IData object) received as response. If no matching document is received within the wait time, this will be null. Important: | Integration Server treats all reply documents as volatile documents. If Integration Server shuts down before processing the reply document, the reply document is lost. |
|
tag | String Conditional. A unique identifier for a publish request. Integration Server uses the tag value to match the request 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 Integration Server places in the tag field of the request document's envelope. |
|
status | String Conditional. Status indicating whether the service was successful. Integration Server reports status only for locally published documents. A value of: success indicates that the service executed successfully. Note: | If at least one subscribing trigger has room in its queue, the status is set to success. |
requestTimedOut indicates that the service timed out (that is, the waitTime specified in the service elapsed before Integration Server received a reply). noSubscriber indicates that Integration Server does not contain any triggers that subscribe to the document. capacityExceeded indicates that the document could not be placed in the queue of the subscribing trigger because the trigger queue is currently at its maximum capacity. Note: | Integration Server reports the capacityExceeded status only when the watt.server.publish.local.rejectOOS property is set to true. |
|
Usage Notes
You can use the pub.publish:publishAndWait service to publish a document to Universal Messaging, Broker, or locally within Integration Server.
Integration Server writes a message to the journal log whenever it rejects or discards a document.
You can use the pub.publish:publishAndWait service to initiate a request/reply. The publishing client broadcasts a request for information. Subscribers to the broadcast document compose and send a reply document that contains the information the publisher requested.
A single publish and wait request might receive many response documents. The
Integration Server that made the publish and wait request uses only the first reply document it receives from the
webMethods Broker. The
Integration Server discards all other replies.
First is arbitrarily defined. There is no guarantee provided for the order in which the messaging provider processes incoming replies. If you need a reply document from a specific client, use the
pub.publish:deliverAndWait service instead.
The pub.publish:publishAndWait 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 published request for customer data. The publishing service will use the first reply document it receives.
A service can issue a publish and wait request in a synchronous or asynchronous manner.
In a synchronous request/reply, the publishing flow service stops executing while it waits for a response. One of the following occurs:
If the service receives a reply before the
waitTime elapses, the service resumes execution.
If the
waitTime elapses before the service receives a reply,
Integration Server ends the request, and the service returns a null document that indicates 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 was no thread waiting for the document.
In an asynchronous request/reply, the publishing flow service continues executing the steps in the service after publishing the document. To retrieve the reply, the publishing flow 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.
If a service contains multiple asynchronous publish and wait invocations, you can build the service such that the service publishes all the requests before collecting the replies. This approach can be more efficient than publishing a request, waiting for a reply, and then publishing 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 asynchronously published request produces a tag field in the pipeline. If the tag field is not linked to another field, the next asynchronously published request (that is, the next execution of the pub.publish:publishAndWait service) will overwrite the first tag value.
If the client side queue is disabled for the messaging connection alias and the document type has a storage type of guaranteed, the pub.publish:waitForReply service ends with a ServiceException if the messaging provider is not available. Make sure to code your publishing service to handle this situation.
The messaging connection alias assigned to a publishable document type determines the message provider to which the Integration Server publishes the document. Only subscribers to the document type on that messaging provider will receive the published document. The Connection alias name property for the document type specifies the message provider. If there is no specified message provider alias, Integration Server publishes the document to the provider in the default messaging connection alias.
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:publishAndWait 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.
For more information about building a service that follows the request/reply model, see the Publish-Subscribe Developer’s Guide.
See Also
