Implementing an Activity

This and subsequent topics explain the implementation of Kii Balance. First, let us see the implementation of the MainActivity class.

The MainActivity is the only activity class in Kii Balance. The MainActivity class works as the container of fragments that provides screen transitions.

At the same time, the MainActivity class enables screen transitions based on the user's login state. Kii Balance restores the user information used for the last successful login and skips the title screen while Hello Kii always opens the login screen after the mobile app starts and before the data listing screen opens.

Screen transitions and the saved state

When you implement activity classes of Android, you need to carefully control the activity lifecycle. The activity lifecycle is one of the most basic concepts in Android implementation. For more information, refer to specialized books and information on the Internet.

The MainActivity class has the onCreate() method and onSaveInstanceState() method. These methods are called when the lifecycle state of the activity changes.

@Override
public void onCreate(Bundle savedInstanceState) {
  super.onCreate(savedInstanceState);
  ...
}

public void onSaveInstanceState(Bundle outState) {
  super.onSaveInstanceState(outState);
  ...
}

Use these methods to save and restore the state of the Kii Cloud SDK for Android.

The onCreate() method is called when the activity is created. The savedInstanceState argument tells why the activity is created.

  • If the savedInstanceState argument is not null

    The activity is recreated by the OS because of an event such as a screen rotation or transition. The internal state that was saved by the last execution of the onSaveInstanceState() method is passed as the savedInstanceState argument of the onCreate() method.

    In this case, all the mobile app needs to do is to restore internal variables and so on because the OS automatically restores screen elements in the activity.

    Implement the MainActivity class as described in Restoring the internal state below.

    Note that this type of method call does not occur depending on conditions such as OS version, device type, and activity settings in the AndroidManifest.xml file.

  • If the savedInstanceState argument is null

    The new activity is created because of an event such as starting the mobile app.

    In this case, initialization is required for both screen elements in the activity and internal variables.

    Implement the MainActivity class as described in Processing when the activity starts below.

The figure below shows three patterns of how the onCreate() method and the onSaveInstanceState() method are called when the activity state is changed. See that the patterns follow the above rules.

Restoring the internal state

If the savedInstanceState argument of the onCreate() method is not null, restore the internal state of the Kii Cloud SDK from the savedInstanceState argument.

The Kii Cloud SDK can save and restore the internal state with the onSaveInstanceState() method and the onCreate() method.

In Kii Balance, this capability is implemented as below.

@Override
public void onCreate(Bundle savedInstanceState) {
  super.onCreate(savedInstanceState);
  setContentView(R.layout.activity_main);

  if (savedInstanceState != null) {
    Kii.onRestoreInstanceState(savedInstanceState);
  } else {
    initializeScreen();
  }
}

@Override
public void onSaveInstanceState(Bundle outState) {
  super.onSaveInstanceState(outState);
  Kii.onSaveInstanceState(outState);
}

The onSaveInstanceState() method saves the internal state of the Kii Cloud SDK to a Bundle instance by executing the Kii.onSaveInstanceState() method.

When the OS recreates the activity, the saved internal state is passed as the savedInstanceState argument of the onCreate() method. The onCreate() method checks if the savedInstanceState argument is valid and restores the internal state of the Kii Cloud SDK with the Kii.onRestoreInstanceState() method.

As mentioned earlier, the mobile app only needs to restore the internal state of the Kii Cloud SDK because the OS restores the screen. That is all for Kii Balance because it does not retain any other internal state data. If your actual app has internal variables, save and restore them as with the Kii Cloud SDK.

Processing when the activity starts

If the savedInstanceState argument of the onCreate() method is null, perform the processing required when the new activity is started.

See below for the code implemented in the MainActivity class.

@Override
public void onCreate(Bundle savedInstanceState) {
  super.onCreate(savedInstanceState);
  setContentView(R.layout.activity_main);

  if (savedInstanceState != null) {
    Kii.onRestoreInstanceState(savedInstanceState);
  } else {
    initializeScreen();
  }
}

private void initializeScreen() {
  KiiUser.loginWithStoredCredentials(new KiiCallback<KiiUser>() {
    @Override
    public void onComplete(KiiUser user, Exception exception) {
      if (exception != null) {
        // Show the title screen.
        ViewUtil.toNextFragment(getSupportFragmentManager(), TitleFragment.newInstance(), false);
      } else {
        // Show the data listing screen.
        ViewUtil.toNextFragment(getSupportFragmentManager(), BalanceListFragment.newInstance(), false);
      }
    }
  });
}

The onCreate() method sets the activity view and then calls the initializeScreen() method. This method performs the following tasks.

In order to restore the login credentials, the KiiUser.loginWithStoredCredentials() method is called. You can restore such authentication information because the Kii Cloud SDK automatically saves the internal authentication information to the shared preferences when the user is successfully logged in or refreshed.

  • If the credentials are not restored, the Kii Cloud SDK cannot use the user information that was saved last time. The title screen opens for re-authentication. For screen transitions, see Screen transitions with fragments.

  • If the credentials are restored, the user has been logged in. The data listing screen immediately opens.

Note that the user argument of the onComplete() function does not contain some of the user information. When the login information is restored, the user argument is created from the minimum information saved in the shared preferences without accessing Kii Cloud. In order to access detailed information such as user attributes, you need to refresh the user. For more information, see the learn more section at the end of this topic.

Access token in the saved information

You can restore the user information that was valid for the last successful login from the shared preferences by using the KiiUser.loginWithStoredCredentials() method.

The access token is important among other various pieces of data such as the user ID and username included in the saved information. It is a string that identifies an authenticated user.

The access token is one of the basic concepts of Kii Cloud and there are many opportunities to use it. Let us review the usage of the access token.

The mobile app accesses Kii Cloud via the Kii Cloud SDK. The SDK sends requests to Kii Cloud on the basis of the specification of the public REST API.

When the user logs in with the username and password, Kii Cloud issues an access token that enables access based on the user's privileges.

In the subsequent requests of the REST API, the access token is specified in the HTTPS header. The token identifies the requesting user and allows processing under the user's privileges.

In order to restore the login state including the access token, use the KiiUser.loginWithStoredCredentials() method in your own mobile app as with Kii Balance. Additionally, a lower-level API supports login with an access token only. That is, in order to log in with the KiiUser.loginWithToken() method, you can save the access token as a string somewhere at a successful login.

What's Next?

Let us review the implementation of the title page.

Go to Implementing the Title Screen.

If you want to learn more...