Saving and Restoring Initialized Information with Gateway

The SDK provides two ways to save and restore the ThingIFAPI and GatewayAPI instances created upon initialization.

Saving and Restoring upon Process Restart

The Android system will reconstruct the mobile app and Activity instances when the app is moved to the background or when the language setting is changed. When this happens, the ThingIFAPI and GatewayAPI instances will be trashed, and all initialized information will be lost.

To restore the instances with all Thing-IF SDK related information upon the Activity reconstruction, save the instances as bundles in the mobile app. To save, use the Parcelable interface implemented in the Activity#onSaveInstanceState of the ThingIFAPI and GatewayAPI. To restore, implement the restoration logic in the Activity#onCreate method.

Here is a sample code for saving and restoring the initialized information. The code assumes three end nodes but an actual mobile app would store end nodes in a variable area such as an array. Save and restore the information as shown below.

public class AppActivity extends Activity {
  private static final String BUNDLE_KEY_THING_IF_API_GATEWAY = "ThingIFAPIGateway";
  private static final String BUNDLE_KEY_GATEWAY_API = "GatewayAPI";
  private static final String BUNDLE_KEY_THING_IF_API_ENDNODE_1 = "ThingIFAPIEndNode1";
  private static final String BUNDLE_KEY_THING_IF_API_ENDNODE_2 = "ThingIFAPIEndNode2";
  private static final String BUNDLE_KEY_THING_IF_API_ENDNODE_3 = "ThingIFAPIEndNode3";

  private ThingIFAPI mApiGateway = null;
  private GatewayAPI mGatewayLocal = null;
  private ThingIFAPI mApiEndNode1 = null;
  private ThingIFAPI mApiEndNode2 = null;
  private ThingIFAPI mApiEndNode3 = null;

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

    if (savedInstanceState != null) {
      // Restore API instances.
      mApiGateway = savedInstanceState.getParcelable(BUNDLE_KEY_THING_IF_API_GATEWAY);
      mGatewayLocal = savedInstanceState.getParcelable(BUNDLE_KEY_GATEWAY_API);
      mApiEndNode1 = savedInstanceState.getParcelable(BUNDLE_KEY_THING_IF_API_ENDNODE_1);
      mApiEndNode2 = savedInstanceState.getParcelable(BUNDLE_KEY_THING_IF_API_ENDNODE_2);
      mApiEndNode3 = savedInstanceState.getParcelable(BUNDLE_KEY_THING_IF_API_ENDNODE_3);
    }

    setContentView(R.layout.activity_second);
  }

  @Override
  protected void onSaveInstanceState(Bundle outState) {
    super.onSaveInstanceState(outState);

    // Save API instances.
    outState.putParcelable(BUNDLE_KEY_THING_IF_API_GATEWAY, mApiGateway);
    outState.putParcelable(BUNDLE_KEY_GATEWAY_API, mGatewayLocal);
    outState.putParcelable(BUNDLE_KEY_THING_IF_API_ENDNODE_1, mApiEndNode1);
    outState.putParcelable(BUNDLE_KEY_THING_IF_API_ENDNODE_2, mApiEndNode2);
    outState.putParcelable(BUNDLE_KEY_THING_IF_API_ENDNODE_3, mApiEndNode3);
  }

}

You can use any key name for bundles.

The above example restores the state in the Activity#onCreate method. You can optionally restore the state in the Activity#onRestoreInstanceState method.

To learn more about the activity lifecycle in Android, please read the documentation by Google.

Serializing in Storage

If you need to save the ThingIFAPI and GatewayAPI instances for a long time, you can use the serialization feature to save them in the storage (i.e., Android's shared preferences).

The instances are automtically saved to the storage by the SDK.

After the process restarted, you can restore the instances as below. The code assumes three end nodes but an actual mobile app would store end nodes in a variable area such as an array. The mobile app needs to save and load the number of end nodes for that case.

try {
  // Load API instances.
  ThingIFAPI apiGateway = ThingIFAPI.loadFromStoredInstance(getApplicationContext(), "gateway");
  GatewayAPI gatewayLocal = GatewayAPI.loadFromStoredInstance(getApplicationContext());
  ThingIFAPI apiEndNode1 = ThingIFAPI.loadFromStoredInstance(getApplicationContext(), "endnode1");
  ThingIFAPI apiEndNode2 = ThingIFAPI.loadFromStoredInstance(getApplicationContext(), "endnode2");
  ThingIFAPI apiEndNode3 = ThingIFAPI.loadFromStoredInstance(getApplicationContext(), "endnode3");
} catch (StoredThingIFAPIInstanceNotFoundException e) {
  // Handle the error.
}

Specify the tag names as the second argument of the ThingIFAPI.loadFromStoredInstance method. These tag names were specified in the setTag method of the ThingIFAPIBuilder when the ThingIFAPI instances were created in Initializing and Onboarding with Gateway. When loading the stored instances, specify the tag names used in initialization in order to locate where each instance is stored.

You can delete stored instances with the removeStoredInstance method. Please refer to the Javadoc for more information.

When saving to the shared preferences, we use key names ThingIFAPI_INSTANCE, ThingIFAPI_INSTANCE_tag name, GatewayAPI_INSTANCE, or GatewayAPI_INSTANCE_tag name. All information previously stored with these keys will be overwritten.