SHOW Signed
 

net.rim.device.api.system
Class PersistentObject

java.lang.Object
  |
  +--net.rim.vm.PersistentRootObject
        |
        +--net.rim.device.api.system.PersistentObject
All Implemented Interfaces:
Persistable, Persistable

public final class PersistentObject
extends PersistentRootObject
implements Persistable

An object whose contents can persist between device resets.

For storage, persistant objects are committed in a PersistentStore object. There are two general ways one can commit objects to the persistent store: in single transactions, or in batches of transactions. Both sorts of transactions are fault tolerant, that is, if the single commit transaction, or the batch transaction, does not entirely succeed, then any existing copy of the object in the store remains untouched.

Single transactions
If you want to commit a single object to the store (and your thread has no lock on the persistent store's monitor object, c.f.), then invoking commit() and forceCommit() does exactly the same thing, that is, they immediately commit this object (or the provided object) to the persistent store, replacing any previous instance of the object.

Batch transactions
If you have a number of objects you want to commit to the store, it's far more efficient to commit them in a batch transaction. To do this, invoke PersistentStore.getSynchObject() to retrieve the persistent store's monitor locking object. Then, synchronize on that object, and do all the commits using commit(). When you release the synchronization on the monitor object, the store will commit all your transactions in one single batch. Notice that if any single commit in this batch fails, then the entire batch transaction will fail.

Notice also that if you invoke forceCommit() while synchronized on the monitor object this object (or the provided object) will get immediately committed, and not be part of the eventual batch transaction.

To set or replace the contents of a persistable object, an application only needs to invoke one of the setContents(java.lang.Object) methods once. Whenever data is changed, added to, or removed from a persistent object, write the contents of the persistable object to persistent memory by invoking one of the commit() methods. Use code similar to the following:

    String[] userinfo = {username, password};
    synchronized(store) {
    store.setContents(userinfo); 
    store.commit();
    }
    
 

See the BlackBerry Java Development Environment Development Guide for more information.

Controlling access to persistent objects
You can control read and replace access to objects placed in a persistent object by wrapping them in a ControlledAccess object. Use code similar to the following example:

    long MY_DATA_ID = 0x33abf322367f9018L;
    Hashtable myHashtable = new Hashtable();
    
    PersistentObject persistentObject = PersistentStore.getPersistentObject( MY_DATA_ID );
    
    // Get the code signing key associated with "ACME"
    CodeSignKey codeSigningKey = CodeSigningKey.get( "ACME" );   

    // Store myHashtable in the PersistentObject but protect it
    // with the "ACME" code signing key
    persistentObject.setContents( new ControlledAccess( myHashtable, codeSigningKey ) );  
    
    // Now, only code files signed with the ACME key can read or replace myHashtable
 

To retrieve something from a persistent object, use code similar to this:

    Hashtable myHashtable = (Hashtable) persistentObject.getContents();  
    // Note: no need to unwrap ControlledAccess
 

Or, to check if your data is protected by your controlled access object, use code similar to this:

    Hashtable myHashtable = (Hashtable) persistentObject.getContents( codeSigningKey );  
    // Note: no need to unwrap ControlledAccess
 

Implicit persistance
Notice that some classes are implicitly persistable: Boolean, Byte, Character, Integer, Long, Object, Short, String, Vector, Hashtable

Also note that, when you persist an object, any persistable object it refers to will also get persisted.

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:
JDE 3.6.0

Method Summary
 Category: Signed  void commit()
          Commits this object to the persistent store.
 Category: Signed static void commit(Object obj)
          Commits provided object to the persistent store.
 Category: Signed  void forceCommit()
          Immediately commits this object to the persistent store.
 Category: Signed static void forceCommit(Object obj)
          Immediately commits provided object to the persistent store.
 Category: Signed  Object getContents()
          Retrieves the contents of this object.
 Category: Signed  Object getContents(CodeSigningKey readAndReplaceKey)
          Retrieves the contents of this object.
 Category: Signed  Object getContents(CodeSigningKey readKey, CodeSigningKey replaceKey)
          Retrieves the contents of this object.
 Category: Signed  ControlledAccess getControlledAccess()
          Retrieves the controlled access object associated with this object.
 Category: Signed  void setContents(Object contents)
          Sets the contents of this object.
 Category: Signed  void setContents(Object contents, int signerId)
          Sets the contents of this object, wrapping the object in a controlled access object.
 Category: Signed  void setContents(Object contents, int signerId, boolean preventReadAccess)
          Sets the contents of this object, wrapping the object in a controlled access object.
 Category: Signed  void setReservedMemorySize(int size)
          Set a reserved memory size for the persistent root.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

commit

public void commit()
Commits this object to the persistent store.

If your thread does not have a lock on the persistent store's monitor object, then this method behaves the same as forceCommit(). If your thread is currently synchronized on the store's monitor object, then invoking this method adds this persistent object to the batch of commit transactions. See the class description for details.

Throws:
NonPersistableObjectException - if this object either does not implement Persistable or is not implicitly persistable (see this class's description for details).
PersistentContentException - if security is enabled and this object's content is not secured.
Since:
JDE 3.6.0
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.

commit

public static void commit(Object obj)
Commits provided object to the persistent store.

If your thread does not have a lock on the persistent store's monitor object, then this method behaves the same as forceCommit(Object). If your thread is currently synchronized on the store's monitor object, then invoking this method adds the provided persistent object to the batch of commit transactions. See the class description for details.

Parameters:
obj - Object to commit; this object must either implement Persistable, or be implicitly persistable (see this class's description for details).
Throws:
NonPersistableObjectException - if the provided object either does not implement Persistable or is not implicitly persistable.
PersistentContentException - if security is enabled and the provided object's content is not secured.
Since:
JDE 3.6.0
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.

forceCommit

public void forceCommit()
Immediately commits this object to the persistent store.

Invoke this method to immediately commit this object to the persistent store, whether currently synchronized on the persistent store's monitor object or not.

Note: Use of this method is expensive, especially for multiple commits.

Throws:
NonPersistableObjectException - if this object either does not implement Persistable or is not implicitly persistable (see this class's description for details).
PersistentContentException - if security is enabled and this object's content is not secured.
Since:
JDE 3.6.0
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.

forceCommit

public static void forceCommit(Object obj)
Immediately commits provided object to the persistent store.

Invoke this method to immediately commit this object to the persistent store, whether currently synchronized on the persistent store's monitor object or not.

Note: Use of this method is expensive, especially for multiple commits.

Parameters:
obj - Object to commit; this object must either implement Persistable, or be implicitly persistable (see this class's description for details).
Throws:
NonPersistableObjectException - if the provided object either does not implement Persistable or is not implicitly persistable.
PersistentContentException - if security is enabled and the provided object's content is not secured.
Since:
JDE 3.6.0
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.

getContents

public Object getContents()
                   throws ControlledAccessException
Retrieves the contents of this object.

This method automatically unwraps controlled access objects.

Returns:
Wrapped object.
Throws:
ControlledAccessException - Thrown if the caller does not have read permission.
Since:
JDE 3.6.0
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.

getContents

public Object getContents(CodeSigningKey readAndReplaceKey)
                   throws ControlledAccessException
Retrieves the contents of this object.

This method automatically unwraps controlled access objects.

Parameters:
readAndReplaceKey - Key to match for read and replace permission. May be null if caller doesn't care what keys are in force.
Returns:
Wrapped object.
Throws:
ControlledAccessException - Thrown if the caller does not have read permission, or the existing keys do not match the given key.
Since:
JDE 3.6.0
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.

getContents

public Object getContents(CodeSigningKey readKey,
                          CodeSigningKey replaceKey)
                   throws ControlledAccessException
Retrieves the contents of this object.

This method automatically unwraps controlled access objects.

Parameters:
readKey - Key to match for read permission; may be null if caller doesn't care what read key is in force.
replaceKey - Key to match for replace permission; may be null if caller doesn't care what replace key is in force.
Returns:
Wrapped object.
Throws:
ControlledAccessException - If the caller does not have read permission, or the existing keys do not match the given keys.
Since:
JDE 3.6.0
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.

getControlledAccess

public ControlledAccess getControlledAccess()
Retrieves the controlled access object associated with this object.

Returns:
Controlled access object wrapping this object's wrapped contents; if the wrapped object is currently unwrapped by a controlled access object, then this method first wraps it with a controlled access object using null read and replace keys, and then returns the newly wrapped object.
Since:
JDE 3.6.0
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.

setContents

public void setContents(Object contents)
                 throws ControlledAccessException
Sets the contents of this object.

Note: if this object currently envelopes a controlled access object, then the caller of this method must have replace permissions on this object's current contents.

Parameters:
contents - Contents this object should envelope.
Throws:
ControlledAccessException - If the caller does not have replace permission.
Since:
JDE 3.6.0
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.

setContents

public void setContents(Object contents,
                        int signerId)
                 throws ControlledAccessException
Sets the contents of this object, wrapping the object in a controlled access object.

Note: the caller of this method must have replace permissions on this object's current contents.

Parameters:
contents - Contents this object should envelope.
signerId - Numeric ID for the code signer.
Throws:
ControlledAccessException - If the caller does not have replace permission.
Since:
JDE 3.6.0
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.

setContents

public void setContents(Object contents,
                        int signerId,
                        boolean preventReadAccess)
                 throws ControlledAccessException
Sets the contents of this object, wrapping the object in a controlled access object.

Note: the caller of this method must have replace permissions on this object's current contents.

Parameters:
contents - Contents this object should envelope.
signerId - Numeric ID for the code signer.
preventReadAccess - A boolean that prevents read access to the data. true to prevent read access, false to allow read access.
Throws:
ControlledAccessException - If the caller does not have replace permission.
Since:
JDE 3.6.0
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.

setReservedMemorySize

public void setReservedMemorySize(int size)
Set a reserved memory size for the persistent root. The JVM will make sure that this amount of memory is reserved for this collection. Collections with a reserved memory size should always be committed using PersistentObject.forceCommit(). Committing individual objects will not cause the reserved memory size calculation to be updated.
Parameters:
size - Size of memory to reserve in bytes
Throws:
IllegalArgumentException - if size is negative.
Since:
JDE 4.2.0
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.



Copyright 1999-2008 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.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.