Asynchronous Request Processing
Normally Map24 Web Services and their clients communicate in a synchronous way. The client sends a request to the service and waits for the service to return with a result or a failure notice. To support long running requests the Map24 Web Services provide a way to process requests in an asynchronous way. Requests that are initiated by the client are immediately answered by the Web service. But this initial answer does not contain the actual response to the request. The answer contains a job ID that can be used be the client to check for the status of the request and to retrieve the result from the service when the job is done. This asynchronous communication is especially useful for large requests or large datasets where processing can take a relatively long time. With synchronous communication clients risk to run into time-outs. Another use case is batch processing. The client can send a number of requests to a service and request the results at a later time.
The following diagram shows the sequence of steps (top-down) that must be executed for the asynchronous communication with the Map24 Web Service:
- Client sends a request to the server. The operation name must have the prefix _asynch_. The service returns a Job ID that can be used to check the status of the operation on the server, to retrieve the result, and also to abort the request.
- Client checks the status of the operation. This is done with the _asynch_job_status operation. The Job ID must be provided in the request. The service returns the status of the operation. For a description of possible job states see the table below.
- If the operation on the service was successful (job status is "JOB_DONE") the client can retrieve the result of the operation from the service with _asynch_job_retrieve_* whereby * must be replaced with the operation name. The Job ID must be provided in the request. The service returns the results of the operation.
Client applications can abort requests by sending an _asynch_job_abort request.
The following table lists possible job states:
Job Status
|
Description
|
| JOB_DONE |
The job has been processed successfully on the server and the results can be retrieved. |
| JOB_WAITING |
The job is queued. |
| JOB_ACTIVE |
The job is currently processed. |
| JOB_FAILED |
The processing of the job failed. Information on the cause of the failure can possibly be retrieved with an _asynch_job_retrieve_* request. |
| JOB_ABORTED |
The job has been aborted by the user with an _asynch_job_abort request. |
| ID_UNKNOWN |
The provided Job ID is not known in this service. |
| NOT_MY_CUP_OF_TEA |
The provided Job ID is not known in this service. The service has requested the state of the job from other services, but did not get an answer. |
Note: Only some of the Map24 Web Services provide asynchronous request processing. The operations are listed in the general description of these services. Links to the general service descriptions are provided in the navigation bar.
Examples
Examples for sending an _async_* request to the server, requesting the job status, and retrieving the response:
|
