checkRetrieveStatus()

Syntax

In all API versions:

1RetrieveResult = metadatabinding.checkRetrieveStatus(ID id);

In API version 34.0 and later, this call takes the optional includeZip boolean parameter.

1RetrieveResult = metadatabinding.checkRetrieveStatus(ID id, boolean includeZip);

Usage

Use checkRetrieveStatus() to check the progress of the metadata retrieve() operation. The RetrieveResult object that this method returns indicates when the asynchronous retrieve() call is completed. If the retrieval is completed, RetrieveResult contains the zip file contents. Use the following process to retrieve metadata components with the retrieve() call.

1. Issue a retrieve() call to start the asynchronous retrieval. An AsyncResult object is returned. Note the value in the id field and use it for the next step.
2. Issue a checkRetrieveStatus() call and pass in the id value from the AsyncResult object from the first step. Check the value of the done field of the returned RetrieveResult. If it is true, this means that the call is completed and proceed to the next step. Otherwise, repeat this step to call checkRetrieveStatus() again until the done field is true.
3. Retrieve the zip file (zipFile field) and other desired fields from RetrieveResult that was returned by the final call to checkRetrieveStatus() in the previous step.

In API version 31.0 and later, the process of making a retrieve() call has been simplified. You no longer have to call checkStatus() after a retrieve() call to obtain the status of the retrieve operation. Instead, make calls to checkRetrieveStatus() only. If the retrieve operation is in progress, call checkRetrieveStatus() again until the retrieve operation is completed. The checkStatus() call is still supported in versions API version 30.0 or earlier, but is not available in API version 31.0 and later.

Retrieving the Zip File In a Second Process

By default, checkRetrieveStatus() returns the zip file on the last call to this operation when the retrieval is completed (RetrieveResult.isDone() == true) and then deletes the zip file from the server. Subsequent calls to checkRetrieveStatus() for the same retrieve operation can’t retrieve the zip file after it has been deleted. Starting with API version 34.0, you can pass a second boolean parameter to checkRetrieveStatus() to indicate whether to retrieve the zip file. This way, you can retrieve the file in a separate process after the retrieval operation is completed. After the zip file is retrieved by passing true to the boolean parameter, it’s deleted from the server. For example, a background file transfer service can call checkRetrieveStatus(id, true) to retrieve the zip file. This service is separate from another process that polls the retrieval status by calling checkRetrieveStatus(id, false) in a loop.

1// First process: Poll the retrieval but don’t retrieve the zip file.
2AsyncResult asyncResult = metadataConnection.retrieve(retrieveRequest);
3String asyncResultId = asyncResult.getId();
4// Wait for the retrieve to complete
5int poll = 0;
6long waitTimeMilliSecs = ONE_SECOND;
7RetrieveResult result = null;
8do {
9    Thread.sleep(waitTimeMilliSecs);
10    // Check the status but don’t retrieve zip file.
11    result = metadataConnection.checkRetrieveStatus(asyncResultId, false);
12} while (!result.isDone());
13
14// Second process: Retrieve the zip file.
15// For example, this process can be a background file transfer service.
16// Retrieve the zip file.
17result = metadataConnection.checkRetrieveStatus(asyncResultId, true);
18// Get the zip file from the RetrieveResult (result) variable
19if (result.getStatus() == RetrieveStatus.Succeeded) {
20    ByteArrayInputStream bais = new ByteArrayInputStream(result.getZipFile());
21    // ...
22}

Sample Code—Java

See the retrieve() sample code for sample usage of this call.

Arguments

Response

RetrieveResult