net.rim.device.api.database
Class DatabaseFactory

java.lang.Object
  extended by net.rim.device.api.database.DatabaseFactory

public class DatabaseFactory
extends Object

Creates new or opens existing instances of a device database. Databases can be created as temporary (in-memory) or persistent (in-store) objects. Example of setting a custom path "/SDCard/MyRoot/Database/"
Example of creating a URI
1. String path = "/SDCard/MyRoot/Database/MyDB";
2. URI myURI = URI.create(path);
Note: A SD card is the preferred storage for databases, currently Storm and Bold are the devices that can create databases with internal memory.

A database file can be encrypted or plain text. If database is encrypted then it is linked to the device that created it. In order to transfer an encrypted database to another device the database file should be decrypted first. Even though database file is encrypted, the maximum protection level is achieved when content protection is turned ON. An application can open or create an encrypted database only when device is unlocked. An encrypted database should be closed as soon as possible. An open database connection is susceptible to cold boot attack.

Note that database may be closed automatically when the file system is unmounted. One such example is when DB file is stored on external media card and user connects the device to a desktop PC and enables USB mass storage mode. In such event, the file system is managed by desktop OS while BlackBerry has no access to it. All the opened databases on external card will be closed and can not be opened until the USB MS mode is finished.

See Also:
PersistentObject, DatabaseSecurityOptions
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 5.0.0

Method Summary
Category: Signed static Database create(String id)
          Create a new plain-text database
Category: Signed static Database create(String id, DatabaseSecurityOptions securityOptions)
          Create a new database with specified security options.
Category: Signed static Database create(URI fileURI)
          Create a new plain-text database
Category: Signed static Database create(URI fileURI, DatabaseSecurityOptions securityOptions)
          Create a new database with specified security options.
Category: Signed static void decrypt(String id)
          Decrypts an encrypted database.
Category: Signed static void decrypt(URI fileURI)
          Decrypts an encrypted database.
Category: Signed static void delete(String id)
          Removes existing database from the device.
Category: Signed static void delete(URI fileURI)
          Removes existing database from the device.
Category: Signed static void encrypt(String id, DatabaseSecurityOptions securityOptions)
          Encrypts a plain text database.
Category: Signed static void encrypt(URI fileURI, DatabaseSecurityOptions securityOptions)
          Encrypts a plain text database.
Category: Signed static boolean exists(String id)
          Checks whether a database already exists by specified ID.
Category: Signed static boolean exists(URI uri)
          Checks whether a database already exists by specified URI.
Category: Signed static String getDefaultRoot()
          Get the default root at which db files are created.
Category: Signed static Database open(String id)
          Open existing database
Category: Signed static Database open(String id, boolean readOnly)
          Open existing database
Category: Signed static Database open(URI fileURI)
          Open an existing database.
Category: Signed static Database open(URI fileURI, boolean readOnly)
          Open an existing database.
Category: Signed static Database openOrCreate(String id)
          Open or Create a plain-text database
Category: Signed static Database openOrCreate(String id, DatabaseSecurityOptions securityOptions)
          Open or create an encrypted database.
Category: Signed static Database openOrCreate(URI fileURI)
          Open or create a plain-text database
Category: Signed static Database openOrCreate(URI fileURI, DatabaseSecurityOptions securityOptions)
          Open or create database.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 



Method Detail

getDefaultRoot

public static String getDefaultRoot()
Get the default root at which db files are created.

Returns:
The default root at which db files are created
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 5.0.0

create

public static Database create(String id,
                              DatabaseSecurityOptions securityOptions)
                       throws DatabaseIOException,
                              DatabasePathException
Create a new database with specified security options.

If securityOptions argument is null then the database will be plain text and accessible from any application.

Parameters:
id - database filename using the default root
securityOptions - define optional database security options, e.g. encryption
Returns:
Database instance
Throws:
DatabasePathException
DatabaseIOException
See Also:
DatabaseFactory.create(String)
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 5.0.0

create

public static Database create(String id)
                       throws DatabaseIOException,
                              DatabasePathException
Create a new plain-text database

Parameters:
id - database filename using the default root
Returns:
instance of a new database
Throws:
DatabasePathException
DatabaseIOException
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 5.0.0

create

public static Database create(URI fileURI)
                       throws DatabaseIOException,
                              DatabasePathException
Create a new plain-text database

Parameters:
fileURI - URI of the database file
Returns:
Database instance
Throws:
DatabasePathException
DatabaseIOException
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 5.0.0

create

public static Database create(URI fileURI,
                              DatabaseSecurityOptions securityOptions)
                       throws DatabaseIOException,
                              DatabasePathException
Create a new database with specified security options.

If securityOptions argument is null then the database will be plain text and accessible from any application.

Parameters:
fileURI - URI of the database file
securityOptions - define optional database security options, e.g. encryption
Returns:
Database instance
Throws:
DatabasePathException
DatabaseIOException
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 5.0.0

open

public static Database open(URI fileURI)
                     throws ControlledAccessException,
                            DatabaseIOException,
                            DatabasePathException
Open an existing database.

If database was encrypted then the caller's module is verified against the code signing key that was used during database creation.

Parameters:
fileURI - URI of the database file
key - The code signing key for this database
Returns:
Database instance
Throws:
DatabaseIOException - on failure
ControlledAccessException - Thrown if the caller does not have read permission
DatabasePathException
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 5.0.0

open

public static Database open(URI fileURI,
                            boolean readOnly)
                     throws ControlledAccessException,
                            DatabaseIOException,
                            DatabasePathException
Open an existing database.

If database was encrypted then the caller's module is verified against the code signing key that was used during database creation.

Parameters:
fileURI - URI of the database file
readOnly - open for read-only
key - The code signing key for this database
Returns:
Database instance
Throws:
DatabaseIOException - on failure
ControlledAccessException - Thrown if the caller does not have read permission
DatabasePathException
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 5.0.0

open

public static Database open(String id)
                     throws ControlledAccessException,
                            DatabaseIOException,
                            DatabasePathException
Open existing database

Parameters:
id - database filename using the default root
Returns:
Database instance
Throws:
DatabaseIOException - on failure
ControlledAccessException - on access restriction
DatabasePathException
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 5.0.0

open

public static Database open(String id,
                            boolean readOnly)
                     throws ControlledAccessException,
                            DatabaseIOException,
                            DatabasePathException
Open existing database

Parameters:
id - database filename using the default root
readOnly - open for read-only
Returns:
Database instance
Throws:
DatabaseIOException - on failure
ControlledAccessException - on access restriction
DatabasePathException
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 5.0.0

openOrCreate

public static Database openOrCreate(String id)
                             throws DatabaseIOException,
                                    ControlledAccessException,
                                    DatabasePathException
Open or Create a plain-text database

Parameters:
id - database filename using the default root
Returns:
Database instance
Throws:
DatabaseIOException - on failure
ControlledAccessException - on access restriction
DatabasePathException
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 5.0.0

openOrCreate

public static Database openOrCreate(URI fileURI)
                             throws DatabaseIOException,
                                    ControlledAccessException,
                                    DatabasePathException
Open or create a plain-text database

Parameters:
fileURI - URI of the database file
Returns:
Database instance
Throws:
DatabaseIOException - on failure
ControlledAccessException - on access restriction
DatabasePathException
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 5.0.0

openOrCreate

public static Database openOrCreate(URI fileURI,
                                    DatabaseSecurityOptions securityOptions)
                             throws DatabaseIOException,
                                    ControlledAccessException,
                                    DatabasePathException
Open or create database. If database doesn't exist then it will be created based on securityOptions parameter.

Note that if database already exists then its security options remain the same. The securityOptions argument is used only when a new database is created.

Parameters:
fileURI - URI of the database file
securityOptions - defines optional database security options, e.g. encryption, used only if database is being created
Returns:
Database instance
Throws:
DatabaseIOException - on failure
ControlledAccessException - on access restriction
DatabasePathException
IllegalArgumentException
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 5.0.0

exists

public static boolean exists(String id)
                      throws DatabasePathException,
                             DatabaseIOException
Checks whether a database already exists by specified ID. Uses the default file system and root location.

Parameters:
id - database ID
Returns:
true if exists, false otherwise
Throws:
DatabasePathException - if default root is invalid or database ID contains illegal characters
DatabaseIOException - if file system can not be accessed at the moment
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 5.0.0

exists

public static boolean exists(URI uri)
                      throws DatabasePathException,
                             DatabaseIOException
Checks whether a database already exists by specified URI.

Parameters:
uri - database file URI
Returns:
true if exists, false otherwise
Throws:
DatabasePathException - if default root is invalid or database ID contains illegal characters
DatabaseIOException - if file system can not be accessed at the moment
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 5.0.0

openOrCreate

public static Database openOrCreate(String id,
                                    DatabaseSecurityOptions securityOptions)
                             throws DatabaseIOException,
                                    ControlledAccessException,
                                    DatabasePathException
Open or create an encrypted database. If database doesn't exist then it will be created based on securityOptions parameter.

Note that if database already exists then its security options remain the same. The securityOptions argument is used only when a new database is created.

Parameters:
id - database filename using the default root
securityOptions - defines optional database security options, e.g. encryption, used only if database is being created
Returns:
Database instance
Throws:
DatabaseIOException - on failure
ControlledAccessException - on access restriction
DatabasePathException
IllegalArgumentException
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 5.0.0

delete

public static void delete(URI fileURI)
                   throws DatabaseIOException,
                          DatabasePathException
Removes existing database from the device.

Parameters:
fileURI - URI of the database file
Throws:
DatabasePathException
DatabaseIOException
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 5.0.0

delete

public static void delete(String id)
                   throws DatabaseIOException,
                          DatabasePathException
Removes existing database from the device.

Parameters:
id - database filename using the default root
Throws:
DatabasePathException
DatabaseIOException
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 5.0.0

encrypt

public static void encrypt(String id,
                           DatabaseSecurityOptions securityOptions)
                    throws DatabaseIOException,
                           DatabasePathException
Encrypts a plain text database. This method binds the database to the current device. If database is already encrypted then the method exits gracefully.

If content protection is turned ON then this operation will succeed only when device is unlocked.

Parameters:
id - existent database filename using the default root
securityOptions - defines database security options, e.g. whether protection by code signing key is required
Throws:
DatabaseIOException
DatabasePathException
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 5.0.0

encrypt

public static void encrypt(URI fileURI,
                           DatabaseSecurityOptions securityOptions)
                    throws DatabaseIOException,
                           DatabasePathException
Encrypts a plain text database. This method binds the database to the current device. If database is already encrypted then the method exits gracefully.

If content protection is turned ON then this operation will succeed only when device is unlocked.

Parameters:
fileURI - URI of the database file
securityOptions - defines database security options, e.g. whether protection by code signing key is required
Throws:
DatabaseIOException
DatabasePathException
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 5.0.0

decrypt

public static void decrypt(String id)
                    throws DatabaseIOException,
                           DatabasePathException
Decrypts an encrypted database. This method should be called only when an encrypted database needs to be transferred to another device with further encryption. Database file must be closed before calling this method. If database is plain text already then the method exits gracefully.

If content protection is turned ON then this operation will succeed only when device is unlocked.

Parameters:
id - existent database filename using the default root
key - The code signing key for this database
Throws:
DatabaseIOException
DatabasePathException
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 5.0.0

decrypt

public static void decrypt(URI fileURI)
                    throws DatabaseIOException,
                           DatabasePathException
Decrypts an encrypted database. This method should be called only when an encrypted database needs to be transferred to another device with further encryption. Database file must be closed before calling this method. If database is plain text already then the method exits gracefully.

If content protection is turned ON then this operation will succeed only when device is unlocked.

Parameters:
fileURI - URI of the database file
Throws:
DatabaseIOException
DatabasePathException
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 5.0.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.