net.rim.device.api.system
Class RuntimeStore

java.lang.Object
  extended by net.rim.device.api.system.RuntimeStore

public final class RuntimeStore
extends Object

Provides a central location for applications to share information.

Note that the store is not persistent; if the device resets, then information stored in the store will be lost.

You can control read and write access to any object you place in the store by wrapping it in a ControlledAccess object. Use code similar to this example:

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

  // Store myHashtable in the RuntimeStore but protect
  // it with the "ACME" code signing key
  RuntimeStore.put( MY_DATA_ID, new ControlledAccess( myHashtable, codeSigningKey ) );  
 

Now, only code files signed with the ACME key can read or replace the myHashtable object.

To retrieve something from the RuntimeStore, use code similar to this example:

  Hashtable myHashtable = (Hashtable) RuntimeStore.get( MY_DATA_ID );  
  // Note: no need to unwrap ControlledAccess
 

Or, to check if your data is protected with a particular code signing key, use code similar to this:

  Hashtable myHashtable = (Hashtable) RuntimeStore.get( MY_DATA_ID, codeSigningKey );  
  // Note: no need to unwrap ControlledAccess
 

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  Object get(long id)
          Retrieves object in the store by ID.
Category: Signed  Object get(long id, CodeSigningKey readAndReplaceKey)
          Retrieves object in the store by ID, verifying permissions with provided key.
Category: Signed  Object get(long id, CodeSigningKey readKey, CodeSigningKey replaceKey)
          Retrieves object in the store by ID, verifying permissions with provided keys.
Category: Signed  ControlledAccess getControlledAccess(long id)
          Retrieves controlled access object associated with ID.
Category: Signed static RuntimeStore getRuntimeStore()
          Retrieves the system-wide RuntimeStore instance.
Category: Signed  void put(long id, Object value)
          Adds the given object to the store.
Category: Signed  Object remove(long id)
          Removes an object from the store
Category: Signed  Object remove(long id, CodeSigningKey readAndReplaceKey)
          Removes object in the store by ID, verifying permissions with provided key.
Category: Signed  Object remove(long id, CodeSigningKey readKey, CodeSigningKey replaceKey)
          Removes object in the store by ID, verifying permissions with provided keys.
Category: Signed  Object replace(long id, Object value)
          Adds the given object to the store.
Category: Signed  Object waitFor(long id)
          Retrieves object in the store by ID.
Category: Signed  Object waitFor(long id, CodeSigningKey readAndReplaceKey)
          Retrieves object in the store by ID.
Category: Signed  Object waitFor(long id, CodeSigningKey readKey, CodeSigningKey replaceKey)
          Retrieves object in the store by ID.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 



Method Detail

get

public Object get(long id)
Retrieves object in the store by ID.

ControlledAccess objects are automatically unwrapped.

Parameters:
id - Identifier of the object to retrieve.
Returns:
Object matching ID, or null if no object with that ID exists.
Throws:
ControlledAccessException - If the caller does not have read 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

get

public Object get(long id,
                  CodeSigningKey readAndReplaceKey)
Retrieves object in the store by ID, verifying permissions with provided key.

Use this method to retrieve an object by ID, and check that read and replace permisions are protected with the given key.

ControlledAccess objects are automatically unwrapped.

Parameters:
id - Identifier of the object to retrieve.
readAndReplaceKey - Key to match for read and replace permission. May be null, if caller doesn't care what keys are in force.
Returns:
Object matching ID, or null if no object with that ID exists.
Throws:
ControlledAccessException - If the caller does not have read permission, or the existing keys do not match the given key.
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

get

public Object get(long id,
                  CodeSigningKey readKey,
                  CodeSigningKey replaceKey)
Retrieves object in the store by ID, verifying permissions with provided keys.

Use this method to retrieve an object ID, and check that read and replace permissions are protected with the given (separate) keys.

ControlledAccess objects are automatically unwrapped.

Parameters:
id - Identifier of the object to retrieve.
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:
Object matching ID, or null if no object with that ID exists.
Throws:
ControlledAccessException - If the caller does not have read permission, or the existing keys do not match the given keys.
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

getControlledAccess

public ControlledAccess getControlledAccess(long id)
Retrieves controlled access object associated with ID.

Parameters:
id - Identifier of object to check.
Returns:
Controlled access object associated with provided ID, or null if the object was not wrapped in a ControlledAccess object.
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

put

public void put(long id,
                Object value)
Adds the given object to the store. If an object with the same ID already exists in the store, an IllegalArgumentException is thrown.

Parameters:
id - Identifier to associate with the stored object.
value - Object to store.
Throws:
ControlledAccessException - If the caller does not have authorization to replace the existing object.
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

replace

public Object replace(long id,
                      Object value)
Adds the given object to the store. If an object with the same ID already exists in the store, it is replaced.

Parameters:
id - Identifier to associate with the stored object.
value - Object to store.
Returns:
Previous object stored in the store with that ID; or null, if there was no previous object associated with your ID.
Throws:
ControlledAccessException - If the caller does not have authorization to replace the existing object.
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

remove

public Object remove(long id)
Removes an object from the store

Parameters:
id - the unique key identifying the object
Returns:
the object associated with id or null if no such object exists
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 4.0.0

remove

public Object remove(long id,
                     CodeSigningKey readAndReplaceKey)
Removes object in the store by ID, verifying permissions with provided key.

Use this method to remove an object by ID, and check that read and replace permisions are protected with the given key.

ControlledAccess objects are automatically unwrapped.

Parameters:
id - Identifier of the object to retrieve.
readAndReplaceKey - Key to match for read and replace permission. May be null, if caller doesn't care what keys are in force.
Returns:
Object matching ID, or null if no object with that ID exists.
Throws:
ControlledAccessException - If the caller does not have read permission, or the existing keys do not match the given key.
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 4.0.0

remove

public Object remove(long id,
                     CodeSigningKey readKey,
                     CodeSigningKey replaceKey)
Removes object in the store by ID, verifying permissions with provided keys.

Use this method to remove an object ID, and check that read and replace permissions are protected with the given (separate) keys.

ControlledAccess objects are automatically unwrapped.

Parameters:
id - Identifier of the object to retrieve.
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:
Object matching ID, or null if no object with that ID exists.
Throws:
ControlledAccessException - If the caller does not have read permission, or the existing keys do not match the given keys.
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 4.0.0

waitFor

public Object waitFor(long id)
Retrieves object in the store by ID. If the object does not currently exist, the method will block for a maximum of 2 minutes waiting for the object to be registered. If the object is not registered after MAX_WAIT_MILLIS, a RuntimeException is thrown.

ControlledAccess objects are automatically unwrapped.

Parameters:
id - Identifier of the object to retrieve.
Returns:
Object matching ID.
Throws:
ControlledAccessException - If the caller does not have read 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

waitFor

public Object waitFor(long id,
                      CodeSigningKey readAndReplaceKey)
Retrieves object in the store by ID. If the object does not currently exist, the method will block for a maximum of MAX_WAIT_MILLIS waiting for the object to be registered. If the object is not registered after MAX_WAIT_MILLIS, a RuntimeException is thrown.

ControlledAccess objects are automatically unwrapped.

Parameters:
id - Identifier of the object to retrieve.
readAndReplaceKey - Key to match for read and replace permission. May be null, if caller doesn't care what keys are in force.
Returns:
Object matching ID.
Throws:
ControlledAccessException - If the caller does not have read 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

waitFor

public Object waitFor(long id,
                      CodeSigningKey readKey,
                      CodeSigningKey replaceKey)
Retrieves object in the store by ID. If the object does not currently exist, the method will block for a maximum of MAX_WAIT_MILLIS waiting for the object to be registered. If the object is not registered after MAX_WAIT_MILLIS, a RuntimeException is thrown.

ControlledAccess objects are automatically unwrapped.

Parameters:
id - Identifier of the object to retrieve.
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:
Object matching ID.
Throws:
ControlledAccessException - If the caller does not have read 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

getRuntimeStore

public static RuntimeStore getRuntimeStore()
Retrieves the system-wide RuntimeStore instance.

Returns:
The system-wide RuntimeStore instance.
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.