This is the third part of a series of articles where I am walking you through the creation of an end-to-end BlackBerry application that will serve as a mobile front-end to my Knowledge Base sample web application.
In my previous article of this series I finished building the screens that serve as the application’s user interface. I also added some test code in order to test the interface against some basic usage scenarios.
In this article I will cover the subject of how to store and retrieve data from the device’s flash memory. This is a very important subject since most applications have no value without the ability to preserve some state across device resets.
What data do we need to save?
-
The URL of our application server
-
A list of recently viewed articles
-
The maximum number of recently viewed articles the above list should contain
Items 1 and 3 are application settings and their storage and retrieval will occur within the context of the Options Screen
The list of recently viewed articles will be built as the user opens articles. It will be committed to memory upon application shutdown.
Storing Data Using the Persistent Store
The BlackBerry API provides for persisting information across device resets through the Persistent Store (PersistenStore Class). Persistent objects (PersistentObject Class) are objects whose contents can persist across device resets. These objects (in the form of key-value pairs) can be committed to the persistent store and later retrieved via the key. Here's a sample usage of the persistent store taken from the BlackBerry API documentation
Options Class
The Options Class encapsulates all the code related with storing and retrieving the data we need to persist across device resets. The class constructor will be in charge of retrieving our application’s persistent object from the persistent store like so
The constructor is private in order to reinforce a singleton behavior that will prevent the existence of multiple instances of our application’s store being worked with at the same time.
The number 0xf6354ee14c6cc857 is a hash of “KnowledgeBase”. You can obtain this hash by selecting the package name at the top of the file, in this case “KnowledgeBase”, right-clicking and choosing the [Convert “KnowledgeBase” To Long] menu item.
The object that I chose to serve as container for the application state that needs to be persisted and that in turn will be contained by the Persistent Object instance that we will commit to the persistent store is a LongHashtableCollection, which is a Hashtable collection using long integers as keys.
Here’s a diagram that will help you visualize how our data will be stored in memory
I created a couple of private methods set(long key, Object value) and get(long key) that will directly deal with setting and getting the contents of the persistent store
Each distinct piece of data (application setting, etc.) to commit to the store will be identified by a unique key
And based on these pieces of data, these are the methods that consumers of the Options Class can use
Options Screen
Within the Options Screen, displaying and saving the application settings is pretty straightforward. These operations are handled by displayOptions() and saveOptions()
Note how saveOptions()does a simple validation of the data before committing it to memory via our Options Class.
Articles Screen
Let’s modify the test code within the ActiclesScreen class’s constructor to take advantage of our Options class ability to save and retrieve a list of recently viewed articles. Before, our test code just created a list of dummy articles in order to display them on the screen
Now, let’s first check if there are any articles cached and if not, create our dummy articles and commit them to the device’s memory
The last item for this article is a very important one and has to do with the fact that any objects that we’d like to commit to the Persistent Store have to implement the net.rim.device.api.util.Persistable interface. Since we are storing instances of the Article Class as a way to persist a list of recently viewed articles across device resets, the Article Class must explicitly implement this interface. Here’s the code
What’s next
Well, this is it for now. In the next article of this series I will add the networking code. This will pretty much take care of the device-side code and set the stage for moving to the server side. On the server side, I will put together the pieces that will handle the communications with the device.
Downloads
Download the source code for this article from the Downloads page.