Blocking vs. Non-Blocking API

Many of our SDK methods, such as registering a new user and uploading data, require network communication with the Kii Cloud. The Kii Cloud SDK for Android provides both blocking and non-blocking versions of these methods.

Threading model in application

Avoid directly accessing the network from UI threads when you use the Kii Cloud SDK.

Android, iOS and HTML5 adopt an event-driven architecture. When application developers make some actions (e.g. clicking a button or scrolling a screen), the dedicated event handler will be called. All UI-triggered events will be handled by the dedicated UI thread, so the executing time-consuming process in this thread will degrade the overall performance of the application.

Accessing Kii Cloud server can usually take up to a few dozen of milliseconds. If the network condition is bad, it might even take a few seconds. Executing these features in the UI thread, therefore, is a big no-no.

Client SDK API

Some of the APIs provided by the client SDK do not require any networking while other APIs do require the network accesses. For those APIs that require some network accesses, Kii Cloud client SDK provides both non-blocking and blocking APIs.

API without network access

This type of API will return the result instantly because the process is executed on the device (e.g. fetching values from an Object).

API with network access - Blocking API

This type of API will send an HTTPS request to Kii Cloud and waits for the response. It will block the process until it gets the response from Kii Cloud.

To prevent blocking the overall application, you should make a worker thread and call this type of API from this worker thread, as shown in the diagram below.

If any problem occurs at runtime, this type of API returns an exception in a platform-dependent way. An exception is thrown on a platform such as Android and Swift. An exception object is returned on a platform such as Objective-C.

API with network access - Non-blocking API

This type of API will also send an HTTPS request to Kii Cloud, but it will handle the network access in a background and return the control instantly. The result will be notified with a callback passed to the API.

You can call this type of API from a UI thread. The callback execution by the SDK will be also made in the UI thread.

When an error occurs, it will be usually notified using an exception object in the callback argument. Some errors, like invalid parameters, could be thrown at the time when you call the API.

For the mobile application development, non-blocking APIs are handy because you do not have to manage multiple threads. You might, however, want to use blocking API when you want to call sequentially multiple APIs or need to coordinate with other background processes.

In any cases, take note that your process might take some time to finish. Make sure to design your mobile application so as to prevent the duplicating execution and such.

Sample code

In the guides, we generally provide sample code for both non-blocking and blocking APIs. For example, the following sample code is used in the guide that explains the user registration.

KiiUser.Builder builder = KiiUser.builderWithName("user_123456");
builder.setEmail("user_123456@example.com");
builder.setGlobalPhone("+819012345678");
KiiUser user = builder.build();

try {
  user.register("123ABC");
} catch (AppException e) {
  // Handle the error.
} catch (IOException e) {
  // Handle the error.
}

KiiUser.Builder builder = KiiUser.builderWithName("user_123456");
builder.setEmail("user_123456@example.com");
builder.setGlobalPhone("+819012345678");
KiiUser user = builder.build();

user.register(new KiiUserCallBack() {
  @Override
  public void onRegisterCompleted(int token, KiiUser user, Exception exception) {
    if (exception != null) {
      // Handle the error.
      return;
    }
  }
}, "123ABC");

Unlike the iOS SDK, calling a blocking API from the main thread in the Android SDK will throw an exception. You need to call a blocking API from a background thread. This limitation is due to Android OS not allowing network access from the main thread.

Whether to use blocking APIs or non-blocking APIs depends on the situation. Typically, using non-blocking APIs will allow you to implement you application easily. If your application needs to execute multiple processes serially, however, you might want to create a background thread and use blocking APIs to execute the processes in the correct order.