Sorry about the red box, but we really need you to update your browser. Read this excellent article if you're wondering why we are no longer supporting this browser version. Go to Browse Happy for browser suggestions and how to update.

Storing objects nonpersistently

The runtime store provides a central location for apps to store and share information on a smartphone. Data in the runtime store is not saved when the smartphone is restarted. The RuntimeStore API was introduced with BlackBerry Device Software 3.6.

The runtime store is implemented in the net.rim.device.api.system.RuntimeStore class.

Objects are stored using a key-value pair. When you store an object in the runtime store, you assign the object a unique ID of type long and later use the ID to retrieve the object from the store. You can generate the unique ID in the Eclipse editor by right-clicking the fully-qualified class name and clicking Convert 'name' to long.

Before your app closes, remove objects from the runtime store that your app no longer requires. If you add an object instance to the runtime store and don't remove it, you could create a memory leak.

Common uses of the runtime store

You can use the runtime store to store any object, and you can retrieve the object from a different process or a different app. You can also restrict access to data.

Here are some common uses of the runtime store:

Implement system-wide singletons

An app might require one or more singleton objects to be accessed from within the app itself or by other apps.

Share data between two apps

For example, an application suite could be made up of multiple apps, all of which use data that is pushed to the smartphone. One of the apps receives all the push data and shares it with the other apps by temporarily storing the data in the runtime store. The runtime store could also be used to set up communication between a listener (such as a PushListener) and a running app.

Store a reference to an object for later use

For example, an app that allows a smartphone user to add and remove an ApplicationMenuItem could use the runtime store to store a reference to an ApplicationMenuItem it has registered. After the app is closed and re-opened, the ApplicationMenuItem can be accessed and unregistered.

Security of the runtime store

By default, only apps that Research In Motion digitally signs can access data in the runtime store.

Restrict access to runtime store data using code signing keys

Code signing keys can be used to control access to the runtime store. This is a way to restrict or share access with other apps on a BlackBerry smartphone.

Import the required classes and interfaces.

import java.util.Hashtable;
import net.rim.device.api.system.RuntimeStore;

Create a hash ID for the object you want to store in the runtime store.

long MY_DATA_ID = 0x33abf322367f9018L;
Hashtable myHashtable = new Hashtable();

Store the object in the runtime store and protect the object with the CodeSigningKey object. Only applications signed with the key can read or change the object.

RuntimeStore.put( MY_DATA_ID, new ControlledAccess( myHashtable, key ) );

Make sure that the object is protected with a particular code signing key, and invoke RuntimeStore.get, providing as parameters the hash ID for the object and the CodeSigningKey object.

Add an object to the runtime store

Invoke RuntimeStore.put(long, String) and provide as parameters a unique long ID and the runtime object to store.

Create a try/catch block to manage the IllegalArgumentException that put() throws if a runtime object with the same ID exists.

RuntimeStore store = RuntimeStore.getRuntimeStore();
String msg = "Some shared text";
long ID = 0x60ac754bc0867248L;
try {
store.put( ID, msg );
} catch(IllegalArgumentException e) {
}

Replace an object in the runtime store

Invoke replace().

Create a try/catch block to manage the ControlledAccessException that replace() throws if the runtime object with the specified ID does not exist.

RuntimeStore store = RuntimeStore.getRuntimeStore();
String newmsg = "Some new text";
try {
Object obj = store.replace( 0x60ac754bc0867248L, newmsg);
} catch(ControlledAccessException e) {
} not exist.

Retrieve the runtime store

Import the required classes and interfaces.

import java.lang.IllegalArgumentException;
import java.lang.RuntimeException;
import java.lang.String;
import net.rim.device.api.system.ControlledAccessException;
import net.rim.device.api.system.RuntimeStore;
import net.rim.device.api.util.ListenerUtilities;

Invoke RuntimeStore.getRuntimeStore().

RuntimeStore store = RuntimeStore.getRuntimeStore();

Retrieve a registered runtime object

Invoke RuntimeStore.get() and provide as a parameter the runtime object ID.

Create a try/catch block to manage the ControlledAccessException that get() throws if the application does not have read access to the specified runtime object.

RuntimeStore store = RuntimeStore.getRuntimeStore();
try {
Object obj = store.get(0x60ac754bc0867248L);
} catch(ControlledAccessException e) {
}

Retrieve an unregistered runtime object

Invoke RuntimeStore.waitFor() to wait for registration of a runtime object to complete. If the runtime object with the specified ID does not exist, waitFor() blocks for a maximum of MAX_WAIT_MILLIS.

Create code for handling exceptions.

RuntimeStore store = RuntimeStore.getRuntimeStore();
try {
Object obj = store.waitFor(0x60ac754bc0867248L);
} catch(ControlledAccessException e) {
} catch(RuntimeException e) {
}

Code sample: Storing a String in the runtime store

For simplicity, this example does not show how to create the unique ID.

import net.rim.device.api.system.Application;
import net.rim.device.api.system.RuntimeStore;

public class RuntimeSet extends Application 
{
   public static void main(String[] args) 
   {
      RuntimeSet app = new RuntimeSet();
      System.exit(0);
   }

   public RuntimeSet()
   {
      RuntimeStore rts = RuntimeStore.getRuntimeStore();
      long ID = 0x60ac754bc0867248L; //just a unique ID - generate any way you want
      rts.put(ID, "Shared Message");
   }
}

Code sample: Getting a stored String from the runtime store

For simplicity, this example does not show how to create the unique ID.

import net.rim.device.api.system.RuntimeStore;
import net.rim.device.api.ui.UiApplication;
import net.rim.device.api.ui.component.Dialog;
import net.rim.device.api.ui.component.LabelField;
import net.rim.device.api.ui.container.MainScreen;

public class RuntimeGet extends UiApplication 
{
   public static void main(String[] args) 
   {
      RuntimeGet app = new RuntimeGet();
      app.enterEventDispatcher();
   }
 
   public RuntimeGet()
   {
      RuntimeStore rts = RuntimeStore.getRuntimeStore();
      long ID = 0x60ac754bc0867248L; //just a unique ID - generate any way you want
      String msg = (String)rts.get(ID);
      pushScreen(new HomeScreen(msg));
   }

}

class HomeScreen extends MainScreen
{
   public HomeScreen(String msg)
   {
      add(new LabelField(msg));
   }
}

Code sample: Creating a singleton using the RuntimeStore API

The following example creates a singleton using the runtime store. In this example, the static variable _instance is initialized to null for each process running on the system, so getInstance() must check the _instance variable each time it is invoked.

For simplicity, this example does not show how to create the unique ID.

import net.rim.device.api.system.*;

class MySingleton {
   private static MySingleton _instance;
   private static final long GUID = 0xab4dd61c5d004c18L;

   // constructor
   MySingleton() {}

   public static MySingleton getInstance() {
      if (_instance == null) {
         _instance = (MySingleton)RuntimeStore.getRuntimeStore().get(GUID);
      if (_instance == null) {
         MySingleton singleton = new MySingleton();

         RuntimeStore.getRuntimeStore().put(GUID, singleton);
         _instance = singleton;
         }
      }

      return _instance;

   }
}