checkRetrieveStatus()

Syntax

In API version 34.0 and later:

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

In API version 33.0 and earlier:

1RetrieveResult = metadatabinding.checkRetrieveStatus(ID id);

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 by default. 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 you 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, which the final call to checkRetrieveStatus() returned 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, pass a boolean value for the includeZip argument of checkRetrieveStatus() to indicate whether to retrieve the zip file. The includeZip argument gives you the option to retrieve the file in a separate process after the retrieval operation is completed. For example, a service polls the retrieval status by calling checkRetrieveStatus(id, false) in a loop. This call returns the status of the retrieval operation, but doesn’t retrieve the zip file. After the retrieval operation is completed, another process, such as a background file transfer service, calls checkRetrieveStatus(id, true) to retrieve the zip file. This last call causes the zip file to be deleted from the server.

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