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

 

sync_sm

 

<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

 

async_sm

 

<?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>

.