How To Save BlackBerry Settings in The Persistent Store

One of the options the BlackBerry API provides for persisting information across device resets is the Persistent Store.  As the Persistent Store supports saving to the smartphone’s flash memory, but not to the SD card, it is a good choice for storing data that does not require large amounts of space, such as application settings and user preferences.

Today we will create a generic Class that we can use in our BlackBerry Java applications to save and retrieve settings and user preferences from the Persistent Store.

We will also create a sample screen that uses this Class.  The screen will contain an EditField instance whose text will be retrieved and saved to the Persistent Store.  This is how the screen will look like:

Let’s get started.

The DataContext Class as a Persistent Store Wrapper

The DataContext Class will encapsulate our interactions with the Persistent Store, allowing us to save and retrieve application settings.

We can start with the private members:

class DataContext {

    private PersistentObject persistentObject;
    private Hashtable settingsTable;

    // Continue implementation...

}

The only private members of DataContext are settingsTable and persistentObject.  The settingsTable variable is a hashtable that will contain our application’s settings.  The persistentObject variable is an instance of the PersistentObjec Class that we will use to save the settings hashtable to the Persistent Store.

With this in mind, let’s continue and define DataContext’s constructor:

public DataContext() {    

    // Hash of examples.persistentstore.
    persistentObject = PersistentStore.getPersistentObject(0xc8027082ac5f496cL);

    synchronized(persistentObject) {

        settingsTable = (Hashtable)persistentObject.getContents();
        if (null == settingsTable) {
            settingsTable = new Hashtable();
            persistentObject.setContents(settingsTable);
            persistentObject.commit();
        }
    }

}

Persistent objects are instances of the PersistentObject Class – in the form of key-value pairs – that can be committed to the persistent store and later retrieved.  Applying this concept, in the constructor we create our persistentObject instance using the static method getPersistentObject(long key).  We provide a hash of “examples.persistentstore” as the unique key that identifies this object as belonging to our application.

As shown in the following screenshot, this hash is created using the “Convert to long” context menu while highlighting the project’s package name.

Once we obtain the PersistentObject reference, we proceed to retrieve our settings table.  If the settings table has never been saved, we put an empty table in the persistent object using persistentObject.setContents(object contents).  This change takes place when we call persistentObject.commit().

With the constructor in place, we can implement the methods that will allow us to save and retrieve specific settings.  These operations are so simple that they do not require an explanation:

public Object get(String key) {

    return settingsTable.get(key);

}

public void set(String key, Object value) {

    settingsTable.put(key, value);

}

public void commit() {

    persistentObject.commit();

}

Using the Persistent Store Wrapper in a BlackBerry Application

Let’s now create a sample screen that uses the DataContext Class.  As I already mentioned, this screen will contain an EditField instance whose text will be retrieved and saved to the Persistent Store using the DataContext Class.

class HomeScreen extends MainScreen {

    private EditField homepageEditField;

    private MenuItem saveMenu = new MenuItem("Save", 100, 100) {
        public void run() {

            Screen screen = UiApplication.getUiApplication().getActiveScreen();
            try {
                screen.save();
            } catch (java.io.IOException ex) {
                Dialog.inform("Could not save settings.");
            }
            screen.close(); 

        }
    };

    public HomeScreen() {

        super();

        this.setTitle("Persistent Store Example");

        DataContext dataContext = new DataContext();        

        homepageEditField = new EditField("Home page: ",(String)dataContext.get("HomePage"),256,EditField.FIELD_RIGHT);
        this.add(homepageEditField);

    }

    protected void makeMenu(Menu menu, int instance) {

        super.makeMenu(menu, instance);

        menu.add(saveMenu);
    }

    public void save() throws java.io.IOException {

        DataContext dataContext = new DataContext();

        dataContext.set("HomePage",homepageEditField.getText().trim());
        dataContext.commit();

    }
}

There are two places in the screen where the DataContext Class is used.  The first place is the constructor, where we call dataContext.get(key) to retrieve the text for the homepage EditField.  The second place is the save() method.  There we use dataContext.set(key, value) and dataContext.commit() to save the edited value back to the the Persistent Store.

Conclusion

I hope you find this approach useful when working with the Persistent Store in your BlackBerry applications.

Do you use a method like this to work with the Persistent Store?