net.rim.device.api.system
Class PersistentStore

java.lang.Object
  extended by net.rim.device.api.system.PersistentStore
All Implemented Interfaces:
Persistable, 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
Category: Signed static void destroyPersistentObject(long key)
          Removes persistent object from store by key.
Category: Signed static PersistentObject getPersistentObject(long key)
          Retrieves persistent object from store by key.
Category: Signed static Object getSynchObject()
          Retrieves 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 persistent object from store by key.

Parameters:
key - Key of object to retrieve.
Returns:
Persistent object associated with key; if no object currently associated with 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 persistent object from store by 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 monitor object for this persistent store.

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

Returns:
Monitor object on which to synchronize to perform batch operations upon 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





Copyright 1999-2010 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Copyright 1993-2003 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A. All Rights Reserved.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark of Sun Microsystems, Inc.