net.rim.device.api.system
Class RuntimeStore

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

public final class RuntimeStore
extends Object

Provides a central location for applications to share information.

The store is not persistent. If the device resets, then information stored in the store is lost.

You will create a memory leak if you add an object instance to the global RuntimeStore and don't remove it.

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: There is 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
	Object	get(long id) Retrieves an object in the store by ID.
	Object	get(long id, CodeSigningKey readAndReplaceKey) Retrieves an object in the store by ID, verifying permissions with the provided key.
	Object	get(long id, CodeSigningKey readKey, CodeSigningKey replaceKey) Retrieves an object in the store by ID, verifying permissions with the provided keys.
	ControlledAccess	getControlledAccess(long id) Retrieves a controlled access object associated with the given ID.
	static RuntimeStore	getRuntimeStore() Retrieves the system-wide RuntimeStore instance.
	void	put(long id, Object value) Adds the given object to the store.
	Object	remove(long id) Removes an object from the store
	Object	remove(long id, CodeSigningKey readAndReplaceKey) Removes an object in the store by ID, verifying permissions with the provided key.
	Object	remove(long id, CodeSigningKey readKey, CodeSigningKey replaceKey) Removes an object in the store by its ID, verifying permissions with the provided keys.
	Object	replace(long id, Object value) Adds the given object to the store.
	Object	waitFor(long id) Retrieves an object in the store by ID.
	Object	waitFor(long id, CodeSigningKey readAndReplaceKey) Retrieves an object in the store by ID.
	Object	waitFor(long id, CodeSigningKey readKey, CodeSigningKey replaceKey) Retrieves an 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 an object in the store by ID.

ControlledAccess objects are automatically unwrapped.

Parameters:

id - Identifier of the object to retrieve.

Returns:

An object matching the 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 an object in the store by ID, verifying permissions with the provided key.

Use this method to retrieve an object by ID, and to check that read and replace permissions 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. Can be null if the caller doesn't care what keys are in force.

Returns:

An object matching the 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 an object in the store by ID, verifying permissions with the 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. Can be null if the caller doesn't care what read key is in force.

replaceKey - Key to match for replace permission. Can be null if the caller doesn't care what replace key is in force.

Returns:

Object matching the 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 a controlled access object associated with the given ID.

Parameters:

id - Identifier of the object to check.

Returns:

Controlled access object associated with the 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 an object in the store by ID, verifying permissions with the provided key.

Use this method to remove an object by ID and to 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. Can be null if the 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 an object in the store by its ID, verifying permissions with the 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. Can be null if the caller doesn't care what read key is in force.

replaceKey - Key to match for replace permission. Can be null if the caller doesn't care what replace key is in force.

Returns:

Object matching the 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 an object in the store by ID. If the object does not currently exist, the method blocks 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 an 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. Can be null if the 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 an 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. Can be null if the caller doesn't care what read key is in force.

replaceKey - Key to match for replace permission. Can be null if the 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