net.rim.device.api.system
Class PersistentStore

java.lang.Object
  net.rim.device.api.system.PersistentStore

All Implemented Interfaces:

Persistable

public final class PersistentStore
extends Object
implements Persistable

Store for persistent objects.

The persistent store provides a means for objects to persist across device resets. A persistent object consists of a key-value pair. When a persistent object is committed to the persistent store, that object's value is stored in flash memory via a deep copy. The value can then be retrieved at a later point in time via the key.

Here is an example of a persistent address book:

 import java.util.*;
 import net.rim.device.api.system.*;
 
 public class AddressBook
 {
     static Vector addresses;
     static PersistentObject persist;
 
     static {
         // Hash of "net.rim.sample.AddressBook".
         long KEY =  0xa3b3159378f59a29L;
         persist = PersistentStore.getPersistentObject( KEY );
         addresses = (Vector) persist.getContents();
         if( addresses == null ) {
             addresses = new Vector();
             persist.setContents( addresses );
             persist.commit();
         }
     }
     
     void add( Address a ) {
         addresses.addElement( a );
         persist.commit();
     }
 }
 

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 3.6.0

Method Summary
	static void	destroyPersistentObject(long key) Removes the persistent object from the store by its key.
	static PersistentObject	getPersistentObject(long key) Retrieves a persistent object from store by its key.
	static Object	getSynchObject() Retrieves the monitor object for this persistent store.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

getPersistentObject

public static PersistentObject getPersistentObject(long key)

Retrieves a persistent object from store by its key.

Parameters:

key - Key of object to retrieve.

Returns:

The persistent object associated with the key. If no object is currently associated with the provided key, this method creates a new persistent object, associates it with the key, commits it to storage, and then returns it to the caller.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 3.6.0

destroyPersistentObject

public static void destroyPersistentObject(long key)

Removes the persistent object from the store by its key.

If the identified object is wrapped in a controlled access object, then the caller must have replace permissions on that object in order to destroy it.

Parameters:

key - Key of object to destroy.

Throws:

ControlledAccessException - If the caller does not have replace permission.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 3.6.0

getSynchObject

public static Object getSynchObject()

Retrieves the monitor object for this persistent store.

In order to perform efficient batch-commit transactions on this store, callers must synchronize the object returned by this method.

Returns:

The monitor object that callers must synchronize to perform batch operations on this store.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 3.6.0