Resumable Transfer

With the resumable transfer method, you can suspend and resume the data transfer. This method is appropriate when you need to upload and download large files in locations with low network quality.

When an upload is finished, the previous data will be replaced with the new data and automatically deleted. If multiple uploads to the same object body occur simultaneously, the last uploaded data will remain; there is no optimistic lock feature for object bodies.

There is no limit to the size of each object body when you use the resumable transfer method. You can store object bodies up to the maximum storage size for your fee plan.

Class structure

The figure below summarizes the class structure used for the object body transfer with the Kii Cloud SDK. Relace <<interface>> with <<protocol>> for iOS.

  • After a KiiObject instance and the target file are prepared, you can create a KiiUploader or KiiDownloader instance for controlling the upload or download processing. In addition, you can get the progress (i.e. how many bytes out of the total file size has been transferred) by specifying a callback upon starting the transfer.

  • KiiUploader and KiiDownloader instances for ongoing transfers are managed by a KiiRTransferManager instance that belongs to a KiiBucket instance. A KiiRTransferManager instance maintains a list of all the files currently being transferred. When a file transfer completes, the transferred file is removed from the list.

  • KiiUploader and KiiDownloader instances have a KiiRTransferInfo instance from which you can get information such as the number of bytes currently being transferred.

Transfer status

KiiUploader and KiiDownloader instances hold one of the three statuses defined in the KiiRTransferStatus enum. The following figure indicates the status transition.

Status Description
NOENTRY No transfer entry exists.
ONGOING A transfer is ongoing.
SUSPENDED A transfer is suspended and can be resumed.

When the status changes to NOENTRY, a KiiUploader or KiiDownloader instance is released from the KiiRTransferManager instance and ends its lifecycle.

For Android, be careful with a recoverable error that can happen when the transfer is in the ONGOING status. For example, if the target file is not found when a transfer starts, the corresponding KiiUploader or KiiDownloader instance remains in the SUSPENDED status because this is a recoverable error. To cancel the task, you need to explicitly terminate the task. Otherwise, the KiiUploader or KiiDownloader instance remains in the KiiRTransferManager instance. Note that this does not apply to iOS development.

Implementation tips

Review the following tips when you process object bodies.

  • On Android, the transfer status is preserved even when the process is killed during the transfer.

    • The status data is stored in the Kii Cloud SDK and you need to delete the data from the KiiRTransferManager instance. Otherwise, the data remains until the user clears the mobile app data in the Settings app in the Android OS.
    • If the mobile app's process is killed during the transfer, the status will be SUSPENDED when you launch the process next time.
    • The data transfer continues even if the user switches to another mobile app as long as the process that involves the Kii Cloud SDK is alive.
  • On iOS, the Kii Cloud SDK automatically suspends the transfer when the process is switched because the home button or the lock button is pressed.

  • The Kii Cloud SDK directly accesses the target file during the transfer. If the local file is changed while the transfer is in the SUSPENDED status, the attempt to resume the transfer will fail.

  • Some platforms allow you to run multiple data transfers at the same time. For such a platform, your mobile app needs to ensure the transfer consistency. For example, simultaneous uploads might cause unexpected results depending on the order of completed uploads (Note that such results do not include data corruption like a file with the mixed content of several uploads).

  • If you try to download an object body that is being updated by an upload from another client, you will get the existing old data on Kii Cloud until the upload fully completes. Once the upload completes, the new file becomes available for download. If a download is ongoing when the upload completes, the download fails.