Synchronous vs. Asynchronous Calls |
Top Previous Next |
Each PAWS service can be invoked either synchronously or asynchronously.
Using Synchronous Calls A synchronous call opens a socket and waits for a response before closing the socket.
Using synchronous calls can waste server resources, and can cause requests to "timeout" when waiting on an operation that takes a long time to complete, such as running a server upgrade or downloading an upgrade file.
Using Asynchronous Calls When using asynchronous calls, the client sends the request and then the response is sent to the specified callback server. An HTTP 202 response is immediately returned across the same HTTP connection that invoked the service. Upon service completion the response is sent to the Callback URL specified in the <wsa:ReplyTo> element.
•Asynchronous calls do not wait for a response to close the socket •Once the service is complete, the response is sent to the specified callback server. •The MessageID that is specified in the request can be used to relate the response to the request. •For calls which can take a long time to complete, it is better use an asynchronous call. •The callback server must be available or the response will be lost. •A maximum of 3 concurrent requests are allowed on a given server. Additional requests are queued for up to 60 seconds before being rejected.
The following calls should be made asynchronously (non-blocking):
•UpgradeFilterService: upgradeFilter •UpgradeProgressStageService: getUpgradeProgress •CancelUpgradeService: cancelUpgrade •PrepareUpgradeService: prepareRemoteUpgrade •StartUpgradeService: startUpgrade
Selecting Synchronous or Asynchronous Behavior Platform Administrative Web Services require a WS-Addressing element (wsa) in the request header. This element contains values for MessageID (wsa:MessageID) and ReplyTo (wsa:Replyto). Requests lacking a properly formatted WS-Addressing element will fail immediately with a status of error.validation.required.
The ReplyTo (wsa:Replyto) element is used to select between synchronous and asynchronous behavior. This element always includes a <wsa:Address> element which is used to specify the address of the callback server.
For synchronous behavior, specify the Anonymous URL ( http://schemas.xmlsoap.org/ws/2004/08/addressing/role/anonymous ) as the Callback URL.
<wsa:ReplyTo> <wsa:Address>http://www.w3.org/2005/08/addressing/anonymous</wsa:Address> </wsa:ReplyTo>
For asynchronous behavior, specify the address of your application's callback server.
<wsa:ReplyTo> <wsa:Address>http://<application server>/servlet/WSACallBackHandler</wsa:Address> </wsa:ReplyTo>
The <wsa:MessageID> element is free form text and is returned in the RelatesTo field in the asynchronous response. The RelatesTo field can be used by the invoker of the service to map the response to the original request.
The following sections show the information flow and example requests for how to use the APIVersionService both synchronously and asynchronously.
Example Synchronous Call to getAPIVersion
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"> <soapenv:Header xmlns:wsa="http://www.w3.org/2005/08/addressing"> <wsa:Action>urn:getAPIVersion</wsa:Action> <wsa:ReplyTo> <wsa:Address>http://www.w3.org/2005/08/addressing/anonymous</wsa:Address> </wsa:ReplyTo> <wsa:MessageID>uuid:26634481-3273-4a70-b537-ab4b874e4d6b</wsa:MessageID> </soapenv:Header> <soapenv:Body/> </soapenv:Envelope>
Example Asynchronous Call to getAPIVersion
<?xml version="1.0" encoding="UTF-8"?> <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"> <soapenv:Header xmlns:wsa="http://www.w3.org/2005/08/addressing"> <wsa:Action>urn:getAPIVersion</wsa:Action> <wsa:ReplyTo> <wsa:Address>http://<application server>/servlet/WSACallBackHandler</wsa:Address> </wsa:ReplyTo> <wsa:MessageID>uuid:5bc69555-f961-4286-9079-a61986e201d2</wsa:MessageID> </soapenv:Header> <soapenv:Body/> </soapenv:Envelope> .
|