net.rim.vm.PersistentRootObject
net.rim.device.api.system.PersistentObject
|
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||
java.lang.Object
public final class PersistentObject
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
PersistentObject.commit() and PersistentObject.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 PersistentObject.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 PersistentObject.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 PersistentObject.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 PersistentObject.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.
| Method Summary | ||
|---|---|---|
|
void |
commit()
Commits this object to the persistent store. |
|
static void |
commit(Object obj)
Commits provided object to the persistent store. |
|
void |
forceCommit()
Immediately commits this object to the persistent store. |
|
static void |
forceCommit(Object obj)
Immediately commits provided object to the persistent store. |
|
Object |
getContents()
Retrieves the contents of this object. |
|
Object |
getContents(CodeSigningKey readAndReplaceKey)
Retrieves the contents of this object. |
|
Object |
getContents(CodeSigningKey readKey,
CodeSigningKey replaceKey)
Retrieves the contents of this object. |
|
ControlledAccess |
getControlledAccess()
Retrieves the controlled access object associated with this object. |
|
void |
setContents(Object contents)
Sets the contents of this object. |
|
void |
setContents(Object contents,
int signerId)
Sets the contents of this object, wrapping the object in a controlled access object. |
|
void |
setContents(Object contents,
int signerId,
boolean preventReadAccess)
Sets the contents of this object, wrapping the object in a controlled access object. |
|
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 |
|---|
public void commit()
If your thread does not have a lock on the persistent store's monitor
object, then this method behaves the same as PersistentObject.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.
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.public void forceCommit()
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.
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.public static void commit(Object obj)
If your thread does not have a lock on the persistent store's monitor
object, then this method behaves the same as PersistentObject.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.
obj - Object to commit; this object must either implement
Persistable, or be implicitly persistable (see this class's
description for details).
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.public static void forceCommit(Object obj)
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.
obj - Object to commit; this object must either implement
Persistable, or be implicitly persistable (see this class's
description for details).
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.
public Object getContents()
throws ControlledAccessException
This method automatically unwraps controlled access objects.
ControlledAccessException - Thrown if the caller does not have read permission.
public Object getContents(CodeSigningKey readAndReplaceKey)
throws ControlledAccessException
This method automatically unwraps controlled access objects.
readAndReplaceKey - Key to match for read and replace
permission. May be null if caller doesn't care what keys are in force.
ControlledAccessException - Thrown if the caller does not have read
permission, or the existing keys do not match the given key.
public Object getContents(CodeSigningKey readKey,
CodeSigningKey replaceKey)
throws ControlledAccessException
This method automatically unwraps controlled access objects.
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.
ControlledAccessException - If the caller does not have read
permission, or the existing keys do not match the given keys.
public void setContents(Object contents)
throws ControlledAccessException
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.
contents - Contents this object should envelope.
ControlledAccessException - If the caller does not have replace
permission.
public void setContents(Object contents,
int signerId)
throws ControlledAccessException
Note: the caller of this method must have replace permissions on this object's current contents.
contents - Contents this object should envelope.signerId - Numeric ID for the code signer.
ControlledAccessException - If the caller does not have replace
permission.
public void setContents(Object contents,
int signerId,
boolean preventReadAccess)
throws ControlledAccessException
Note: the caller of this method must have replace permissions on this object's current contents.
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.
ControlledAccessException - If the caller does not have replace
permission.public ControlledAccess getControlledAccess()
public void setReservedMemorySize(int size)
size - Size of memory to reserve in bytes
IllegalArgumentException - if size is negative.
|
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||
Copyright 1999-2011 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Java is a trademark of Oracle America Inc. in the US and other countries.
Legal