net.rim.device.api.database
Class DatabaseFactory

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

public class DatabaseFactory
extends Object

Creates a new instance of a SQLite database or opens an existing instance. Databases can be created as temporary (in-memory) or persistent (in-store) objects.

Example of setting a custom path: "file:///SDCard/MyRoot/Database/"

Example of creating a URI:

 URI myURI = URI.create("file:///SDCard/Databases/SQLite_Guide/" + "MyTestDatabase.db");
 

A microSD media card is the preferred storage for databases if the device supports it.

A database file can be encrypted or plaintext. If the 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 must be decrypted first. Even when a 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 the device is unlocked. An encrypted database should be closed as soon as possible. An open database connection is susceptible to cold boot attack.

You can open multiple read-only connections to a database, but only one read-write connection can be made at the same time. In addition, you cannot open a database as read-write when it is already open as read-only. An attempt to open a database as read-write when it is already open (either as read-write or read-only) will generate “File system error 12”, which indicates that there was an attempt to open more than one read-write connection to the same database.

The database may close automatically when the file system is unmounted. One such example is when a database file is stored on an external media card and the user connects the device to a desktop PC and enables USB mass storage mode. In this case the file system is managed by the desktop operating system and the BlackBerry device has no access to it. All the opened databases on the external card will be closed and cannot be opened until USB mass storage mode is finished.

Copying a database to an encrypted storage location

If you copy a SQLite database to an encrypted storage location (eMMC or SD card), the database can become inaccessible to the Database API. This happens because the media card uses a different type of encryption from that used by the Database API. To copy a database so that you can access it, you should use the Database API to create an empty database file, truncate the file to zero, and then copy the database into the file. The following code sample demonstrates this technique.
 // Copy a database to an encrypted storage location. 

  private void copyDBRecommendedWay() {
          
      try {
          String dbPath = "file:///SDCard/original.db";
          String dbPathCopy = "file:///SDCard/copy.db"; 
          Database dbCopy = null;
          try {
              // Delete if there's an existing one.
              DatabaseFactory.delete(URI.create(dbPathCopy));
              
              // Create the database using the DatabaseFactory class.                
              dbCopy = DatabaseFactory.create(URI.create(dbPathCopy));
          } catch (DatabaseException e) {
              System.out.println("DatabaseException: error code: " + e.getErrorCode() + 
                          " msg: " + e.getMessage());        
          } finally {
              // Close the database.
              dbCopy.close();            
          }
          
          // Open a file connection to the database file that was created.
          FileConnection outfc = (FileConnection)Connector.open(dbPathCopy);
          
          // Truncate the file
          outfc.truncate(0);
                      
          // Write out the downloaded database data to FileConnection.openOutputStream().
          OutputStream os = outfc.openOutputStream();
          
          FileConnection infc = (FileConnection)Connector.open(dbPath);        
          InputStream is = infc.openInputStream();
                      
          byte[] buf = new byte[1024];
          int len;
          while ((len = is.read(buf)) > 0){
              os.write(buf, 0, len);
          }
          is.close();
          os.close();                     
          
          // Close the file connection.
          outfc.close();
          
          System.out.println("Copied " + dbPath + " to " + dbPathCopy);
          
          // The database can now be reopened with the DatabaseFactory class.
          } catch (Exception e) {
          System.out.println("Exception: " + e.getMessage());
      }
  } 
 

Code sample: Creating a SQLite database

 import net.rim.device.api.ui.component.*;
 import net.rim.device.api.ui.container.*;
 import net.rim.device.api.database.*;
 import net.rim.device.api.io.*;
 import net.rim.device.api.ui.*;
 
 public class CreateDatabase extends UiApplication
 {
     public static void main(String[] args)
     {
        CreateDatabase theApp = new CreateDatabase();
        theApp.enterEventDispatcher();
     }  
     public CreateDatabase()
     {
        pushScreen(new CreateDatabaseScreen());
     }   
 }
 
 class CreateDatabaseScreen extends MainScreen
 {
     Database d;
     public CreateDatabaseScreen()
     {
        LabelField title = new LabelField("SQLite Create Database Sample", 
                                           LabelField.ELLIPSIS | 
                                           LabelField.USE_ALL_WIDTH);
        setTitle(title);
        add(new RichTextField("Creating a database called " +
                              "MyTestDatabase.db on the SDCard."));
        try
        {
           URI myURI = URI.create("file:///SDCard/Databases/SQLite_Guide/" + 
                       "MyTestDatabase.db"); 
           d = DatabaseFactory.create(myURI);            
        }
        catch ( Exception e ) 
        {         
           System.out.println( e.getMessage() );
        }
        finally
        {
           d.close();
        }
        try {
           d.close();
        } 
        catch (DatabaseException e) {
        }
        {         
           System.out.println( e.getMessage() );
           e.printStackTrace();
        }
     }
 }
 

Code sample: Adding content to a SQLite table

 import net.rim.device.api.database.Database;
 import net.rim.device.api.database.DatabaseFactory;
 import net.rim.device.api.database.Statement;
 import net.rim.device.api.io.URI;
 import net.rim.device.api.system.Application;
 
 public class AddDatabaseTable extends Application 
 {
    public static void main(String[] args)
   {
       AddDatabaseTable app = new AddDatabaseTable();
       try
       {
           Database d = null;
           Statement st = null;
           try
           {
               URI myURI = URI.create("/SDCard/test.db"); 
               d = DatabaseFactory.open(myURI);
               st = d.createStatement("INSERT INTO People(Name,Age) " +
                              "VALUES ('John',37)");
               st.prepare();
               st.execute();
           }
           catch ( Exception e ) 
           {         
               System.out.println( e.getMessage() );
           }
           finally
           {
               st.close();
               d.close();
          }
       }
       catch ( Exception e ) 
       {         
          System.out.println( e.getMessage() );
       }
   }
 }
 

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)
          Creates a new plaintext database.
Category: Signed static Database create(String id, DatabaseOptions databaseOptions)
          Creates a new plaintext database with specified database options.
Category: Signed static Database create(String id, DatabaseSecurityOptions securityOptions)
          Creates a new database with the specified security options.
Category: Signed static Database create(String id, DatabaseSecurityOptions securityOptions, DatabaseOptions databaseOptions)
          Creates a new database with the specified security options and database options.
Category: Signed static Database create(URI fileURI)
          Creates a new plaintext database.
Category: Signed static Database create(URI fileURI, DatabaseOptions databaseOptions)
          Creates a new plaintext database with specified database options.
Category: Signed static Database create(URI fileURI, DatabaseSecurityOptions securityOptions)
          Creates a new database with specified security options.
Category: Signed static Database create(URI fileURI, DatabaseSecurityOptions securityOptions, DatabaseOptions databaseOptions)
          Creates a new database with specified security options and database 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 an existing database from the device.
Category: Signed static void delete(URI fileURI)
          Removes an existing database from the device.
Category: Signed static void encrypt(String id, DatabaseSecurityOptions securityOptions)
          Encrypts a plaintext database.
Category: Signed static void encrypt(URI fileURI, DatabaseSecurityOptions securityOptions)
          Encrypts a plaintext 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()
          Gets the default root at which database files are created.
Category: Signed static Database open(String id)
          Opens an existing database.
Category: Signed static Database open(String id, boolean readOnly)
          Opens an existing database.
Category: Signed static Database open(String id, boolean readOnly, DatabaseOptions databaseOptions)
          Opens an existing database with specified database options.
Category: Signed static Database open(String id, boolean readOnly, DatabaseSecurityOptions securityOptions, DatabaseOptions databaseOptions)
          Opens an existing database with specified database options.
Category: Signed static Database open(String id, DatabaseOptions databaseOptions)
          Opens an existing database with specified database options.
Category: Signed static Database open(URI fileURI)
          Opens an existing database.
Category: Signed static Database open(URI fileURI, boolean readOnly)
          Opens an existing database; optionally, opens the database in read-only mode.
Category: Signed static Database open(URI fileURI, boolean readOnly, DatabaseOptions databaseOptions)
          Opens an existing database with specified database options; optionally, opens the database in read-only mode.
Category: Signed static Database open(URI fileURI, boolean readOnly, DatabaseSecurityOptions securityOptions, DatabaseOptions databaseOptions)
          Opens an existing database with specified database options.
Category: Signed static Database open(URI fileURI, DatabaseOptions databaseOptions)
          Opens an existing database with the specified database options.
Category: Signed static Database openOrCreate(String id)
          Opens or creates a plaintext database.
Category: Signed static Database openOrCreate(String id, DatabaseOptions databaseOptions)
          Opens or creates a plaintext database with specified database options.
Category: Signed static Database openOrCreate(String id, DatabaseSecurityOptions securityOptions)
          Opens or creates an encrypted database.
Category: Signed static Database openOrCreate(String id, DatabaseSecurityOptions securityOptions, DatabaseOptions databaseOptions)
          Opens or creates an encrypted database with specified database options.
Category: Signed static Database openOrCreate(URI fileURI)
          Opens or creates a plaintext database.
Category: Signed static Database openOrCreate(URI fileURI, DatabaseOptions databaseOptions)
          Opens or creates a plaintext database with specified database options.
Category: Signed static Database openOrCreate(URI fileURI, DatabaseSecurityOptions securityOptions)
          Opens or creates a database.
Category: Signed static Database openOrCreate(URI fileURI, DatabaseSecurityOptions securityOptions, DatabaseOptions databaseOptions)
          Opens or creates a database with the specified database options.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 



Method Detail

getDefaultRoot

public static String getDefaultRoot()
Gets the default root at which database files are created.

Returns:
The default root at which database 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
Creates a new database with the specified security options.

If the securityOptions argument is null, the database will be plaintext and accessible from any application.

Parameters:
id - Database filename using the default root.
securityOptions - Defines optional database security options, such as encryption.
Returns:
Database instance.
Throws:
DatabaseIOException - If the database already exists or there was an IO exception creating the database.
DatabasePathException - If the path is invalid.
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,
                              DatabaseSecurityOptions securityOptions,
                              DatabaseOptions databaseOptions)
                       throws DatabaseIOException,
                              DatabasePathException
Creates a new database with the specified security options and database options.

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

Parameters:
id - Database filename using the default root.
securityOptions - Defines optional database security options, such as encryption.
databaseOptions - Defines optional database options, such as foreign key constraints.
Returns:
Database instance.
Throws:
DatabaseIOException - If the database already exists or there was an IO exception creating the database.
DatabasePathException - If the path is invalid.
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 6.0.0

create

public static Database create(String id)
                       throws DatabaseIOException,
                              DatabasePathException
Creates a new plaintext database.

Parameters:
id - Database filename using the default root.
Returns:
Instance of a new database.
Throws:
DatabaseIOException - If the database already exists or there was an IO exception creating the database.
DatabasePathException - If the path is invalid.
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,
                              DatabaseOptions databaseOptions)
                       throws DatabaseIOException,
                              DatabasePathException
Creates a new plaintext database with specified database options.

Parameters:
id - Database filename using the default root.
databaseOptions - Defines optional database options, such as foreign key constraints.
Returns:
Instance of a new database.
Throws:
DatabaseIOException - If the database already exists or there was an IO exception creating the database.
DatabasePathException - If the path is invalid.
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 6.0.0

create

public static Database create(URI fileURI)
                       throws DatabaseIOException,
                              DatabasePathException
Creates a new plaintext database.

Parameters:
fileURI - URI of the database file.
Returns:
Database instance.
Throws:
DatabaseIOException - If the database already exists or there was an IO exception creating the database.
DatabasePathException - If the path is invalid.
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,
                              DatabaseOptions databaseOptions)
                       throws DatabaseIOException,
                              DatabasePathException
Creates a new plaintext database with specified database options.

Parameters:
fileURI - URI of the database file.
databaseOptions - Defines optional database options, such as foreign key constraints.
Returns:
Database instance.
Throws:
DatabaseIOException - If the database already exists or there was an IO exception creating the database.
DatabasePathException - If the path is invalid.
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 6.0.0

create

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

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

Parameters:
fileURI - URI of the database file.
securityOptions - Defines optional database security options, such as encryption.
Returns:
Database instance
Throws:
DatabaseIOException - If the database already exists or there was an IO exception creating the database.
DatabasePathException - If the path is invalid.
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,
                              DatabaseOptions databaseOptions)
                       throws DatabaseIOException,
                              DatabasePathException
Creates a new database with specified security options and database options.

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

Parameters:
fileURI - URI of the database file.
securityOptions - Defines optional database security options, such as encryption.
databaseOptions - Defines optional database options, such as foreign key constraints.
Returns:
Database instance.
Throws:
DatabaseIOException - If the database already exists or there was an IO exception creating the database.
DatabasePathException - If the path is invalid.
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 6.0.0

open

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

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

Only one read-write connection to a database can be opened at the same time. Other database connections must be read-only. If you need to open a database as read-write and read-only at the same time, you must open it first as read-write. Otherwise, “File system error 12” is generated, which indicates that an attempt was made to open more than one read-write connection.

Parameters:
fileURI - URI of the database file.
Returns:
Database instance.
Throws:
DatabaseIOException - If the database does not exist or there was an exception opening the database or if the caller does not have read permission.
DatabasePathException - If the path is invalid.
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,
                            DatabaseOptions databaseOptions)
                     throws DatabaseIOException,
                            DatabasePathException
Opens an existing database with the specified database options.

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

Only one read-write connection to a database can be opened at the same time. Other database connections must be read-only. If you need to open a database as read-write and read-only at the same time, you must open it first as read-write. Otherwise, “File system error 12” is generated, which indicates that an attempt was made to open more than one read-write connection.

Parameters:
fileURI - URI of the database file.
databaseOptions - Defines optional database options, such as foreign key constraints.
Returns:
Database instance.
Throws:
DatabaseIOException - If the database does not exist or there was an exception opening the database or if the caller does not have read permission.
DatabasePathException - If the path is invalid.
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 6.0.0

open

public static Database open(URI fileURI,
                            boolean readOnly)
                     throws DatabaseIOException,
                            DatabasePathException
Opens an existing database; optionally, opens the database in read-only mode. By default, databases open in read-write mode. A database file can be opened by multiple read-only database connnections, but it can only be opened by one read-write connection at a time.

If you need to open a database as read-write and read-only at the same time, you must open it first as read-write. Otherwise, “File system error 12” is generated, which indicates that an attempt was made to open more than one read-write connection.

If the 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.
Returns:
Database instance.
Throws:
DatabaseIOException - If the database does not exist or there was an exception opening the database or if the caller does not have read permission.
DatabasePathException - If the path is invalid.
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,
                            DatabaseOptions databaseOptions)
                     throws DatabaseIOException,
                            DatabasePathException
Opens an existing database with specified database options; optionally, opens the database in read-only mode. By default, databases open in read-write mode. A database file can be opened by multiple read-only database connnections, but it can only be opened by one read-write connection at a time.

If you need to open a database as read-write and read-only at the same time, you must open it first as read-write. Otherwise, “File system error 12” is generated, which indicates that an attempt was made to open more than one read-write connection.

If the 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.
databaseOptions - Defines optional database options, such as foreign key constraints.
Returns:
Database instance.
Throws:
DatabaseIOException - If the database does not exist or there was an exception opening the database or if the caller does not have read permission.
DatabasePathException - If the path is invalid.
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 6.0.0

open

public static Database open(URI fileURI,
                            boolean readOnly,
                            DatabaseSecurityOptions securityOptions,
                            DatabaseOptions databaseOptions)
                     throws DatabaseIOException,
                            DatabasePathException
Opens an existing database with specified database options. Optionally, opens the database in read-only mode (instead of read-write mode). A database file can be opened by multiple read-only database connnections, but it can only be opened by one read-write connection at a time.

If you need to open a database as read-write and read-only at the same time, you must open it first as read-write. Otherwise, “File system error 12” is generated, which indicates that an attempt was made to open more than one read-write connection.

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

Note that a database file may be replaced accidentally or by a malicious application. To verify that the database security attributes haven't changed, the securityOptions must be specified with the same values that were used during database creation. If database security attributes are different from what is specified by the security options argument then the method would fail with a ControlledAccessException.

Parameters:
fileURI - URI of the database file.
readOnly - Open for read-only.
securityOptions - Defines optional database security options, such as encryption. The database will be opened only if it was created with the same security options.
databaseOptions - Defines optional database options, such as foreign key constraints.
key - The code signing key for this database.
Returns:
Database instance.
Throws:
DatabaseIOException - If the database does not exist; there was an exception opening the database; if the caller does not have read permission; or database security attributes are different from what was specified in the securityOptions method argument.
DatabasePathException - If the path is invalid.
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 7.0.0

open

public static Database open(String id)
                     throws DatabaseIOException,
                            DatabasePathException
Opens an existing database.

Only one read-write connection to a database can be opened at the same time. Other database connections must be read-only. If you need to open a database as read-write and read-only at the same time, you must open it first as read-write. Otherwise, “File system error 12” is generated, which indicates that an attempt was made to open more than one read-write connection.

Parameters:
id - Database filename using the default root.
Returns:
Database instance.
Throws:
DatabaseIOException - If the database does not exist; there was an exception opening the database; if the caller does not have read permission; or database security attributes are different from what was specified in the securityOptions method argument.
DatabasePathException - If the path is invalid.
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,
                            DatabaseOptions databaseOptions)
                     throws DatabaseIOException,
                            DatabasePathException
Opens an existing database with specified database options.

Only one read-write connection to a database can be opened at the same time. Other database connections must be read-only. If you need to open a database as read-write and read-only at the same time, you must open it first as read-write. Otherwise, “File system error 12” is generated, which indicates that an attempt was made to open more than one read-write connection.

Parameters:
id - Database filename using the default root.
databaseOptions - Defines optional database options, such as foreign key constraints.
Returns:
Database instance.
Throws:
DatabaseIOException - If the database does not exist; there was an exception opening the database; if the caller does not have read permission; or database security attributes are different from what was specified in the securityOptions method argument.
DatabasePathException - If the path is invalid.
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 6.0.0

open

public static Database open(String id,
                            boolean readOnly)
                     throws DatabaseIOException,
                            DatabasePathException
Opens an existing database. Optionally, opens the database in read-only mode (instead of read-write mode). A database file can be opened by multiple read-only database connnections, but it can only be opened by one read-write connection at a time.

If you need to open a database as read-write and read-only at the same time, you must open it first as read-write. Otherwise, “File system error 12” is generated, which indicates that an attempt was made to open more than one read-write connection.

Parameters:
id - Database filename using the default root.
readOnly - Open for read-only.
Returns:
Database instance.
Throws:
DatabaseIOException - If the database does not exist; there was an exception opening the database; if the caller does not have read permission; or database security attributes are different from what was specified in the securityOptions method argument.
DatabasePathException - If the path is invalid.
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,
                            DatabaseOptions databaseOptions)
                     throws DatabaseIOException,
                            DatabasePathException
Opens an existing database with specified database options. Optionally, opens the database in read-only mode (instead of read-write mode). A database file can be opened by multiple read-only database connnections, but it can only be opened by one read-write connection at a time.

If you need to open a database as read-write and read-only at the same time, you must open it first as read-write. Otherwise, “File system error 12” is generated, which indicates that an attempt was made to open more than one read-write connection.

Parameters:
id - Database filename using the default root.
readOnly - Open for read-only.
databaseOptions - Defines optional database options, such as foreign key constraints.
Returns:
Database instance.
Throws:
DatabaseIOException - If the database does not exist; there was an exception opening the database; if the caller does not have read permission; or database security attributes are different from what was specified in the securityOptions method argument.
DatabasePathException - If the path is invalid.
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 6.0.0

open

public static Database open(String id,
                            boolean readOnly,
                            DatabaseSecurityOptions securityOptions,
                            DatabaseOptions databaseOptions)
                     throws DatabaseIOException,
                            DatabasePathException
Opens an existing database with specified database options. Optionally, opens the database in read-only mode (instead of read-write mode). A database file can be opened by multiple read-only database connnections, but it can only be opened by one read-write connection at a time.

If you need to open a database as read-write and read-only at the same time, you must open it first as read-write. Otherwise, “File system error 12” is generated, which indicates that an attempt was made to open more than one read-write connection.

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

Note that a database file may be replaced accidentally or by a malicious application. To verify that the database security attributes haven't changed, the securityOptions must be specified with the same values that were used during database creation. If database security attributes are different from what is specified by the security options argument then the method would fail with a ControlledAccessException.

Parameters:
id - Database filename using the default root.
readOnly - Open for read-only.
securityOptions - Defines optional database security options, such as encryption. The database will be opened only if it was created with the same security options.
databaseOptions - Defines optional database options, such as foreign key constraints.
Returns:
Database instance.
Throws:
DatabaseIOException - If the database does not exist; there was an exception opening the database; if the caller does not have read permission; or database security attributes are different from what was specified in the securityOptions method argument.
DatabasePathException - If the path is invalid.
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 7.0.0

openOrCreate

public static Database openOrCreate(String id)
                             throws DatabaseIOException,
                                    DatabasePathException
Opens or creates a plaintext database.

Parameters:
id - Database filename using the default root.
Returns:
Database instance.
Throws:
DatabaseIOException - If there was an exception opening or creating the database.
DatabasePathException - If the path is invalid.
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,
                                    DatabaseOptions databaseOptions)
                             throws DatabaseIOException,
                                    DatabasePathException
Opens or creates a plaintext database with specified database options.

Only one read-write connection to a database can be opened at the same time. Other database connections must be read-only. If you need to open a database as read-write and read-only at the same time, you must open it first as read-write. Otherwise, “File system error 12” is generated, which indicates that an attempt was made to open more than one read-write connection.

Parameters:
id - Database filename using the default root.
databaseOptions - Defines optional database options, such as foreign key constraints.
Returns:
Database instance.
Throws:
DatabaseIOException - If there was an exception opening or creating the database.
DatabasePathException - If the path is invalid.
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 6.0.0

openOrCreate

public static Database openOrCreate(URI fileURI)
                             throws DatabaseIOException,
                                    DatabasePathException
Opens or creates a plaintext database.

Only one read-write connection to a database can be opened at the same time. Other database connections must be read-only. If you need to open a database as read-write and read-only at the same time, you must open it first as read-write. Otherwise, “File system error 12” is generated, which indicates that an attempt was made to open more than one read-write connection.

Parameters:
fileURI - URI of the database file.
Returns:
Database instance.
Throws:
DatabaseIOException - If there was an exception opening or creating the database.
DatabasePathException - If the path is invalid.
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,
                                    DatabaseOptions databaseOptions)
                             throws DatabaseIOException,
                                    DatabasePathException
Opens or creates a plaintext database with specified database options.

Only one read-write connection to a database can be opened at the same time. Other database connections must be read-only. If you need to open a database as read-write and read-only at the same time, you must open it first as read-write. Otherwise, “File system error 12” is generated, which indicates that an attempt was made to open more than one read-write connection.

Parameters:
fileURI - URI of the database file.
databaseOptions - Defines optional database options, such as foreign key constraints.
Returns:
Database instance.
Throws:
DatabaseIOException - If there was an exception opening or creating the database.
DatabasePathException - If the path is invalid.
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 6.0.0

openOrCreate

public static Database openOrCreate(URI fileURI,
                                    DatabaseSecurityOptions securityOptions)
                             throws DatabaseIOException,
                                    DatabasePathException
Opens or creates a database. If the database doesn't exist then it is created based on the securityOptions parameter.

If the database already exists then its security options remain the same. If the securityOptions argument is specified and the database already exists then opening procedure will succeed only if database security options haven't changed. So, for example, if a code signing key is specified then database will be opened only if it was protected with the given key during creation.

Only one read-write connection to a database can be opened at the same time. Other database connections must be read-only. If you need to open a database as read-write and read-only at the same time, you must open it first as read-write. Otherwise, “File system error 12” is generated, which indicates that an attempt was made to open more than one read-write connection.

Parameters:
fileURI - URI of the database file.
securityOptions - Defines optional database security options, such as encryption. If database exists and security options are specified then the database will be opened only if it was created with the same security options.
Returns:
Database instance.
Throws:
DatabaseIOException - If there was an exception opening or creating the database.
DatabasePathException - If the path is invalid.
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,
                                    DatabaseOptions databaseOptions)
                             throws DatabaseIOException,
                                    DatabasePathException
Opens or creates a database with the specified database options. If the database doesn't exist then it is created based on the securityOptions parameter.

Only one read-write connection to a database can be opened at the same time. Other database connections must be read-only. If you need to open a database as read-write and read-only at the same time, you must open it first as read-write. Otherwise, “File system error 12” is generated, which indicates that an attempt was made to open more than one read-write connection.

If the database already exists then its security options remain the same. If the securityOptions argument is specified and the database already exists then opening procedure will succeed only if database security options haven't changed. So, for example, if a code signing key is specified then database will be opened only if it was protected with the given key during creation.

Parameters:
fileURI - URI of the database file.
securityOptions - Defines optional database security options, such as encryption. If database exists and security options are specified then the database will be opened only if it was created with the same security options.
databaseOptions - define optional database options, e.g. foreign key constraints
Returns:
Database instance.
Throws:
DatabaseIOException - If there was an exception opening or creating the database.
DatabasePathException - If the path is invalid.
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 6.0.0

exists

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

Parameters:
id - Database ID.
Returns:
true if the database exists, false otherwise.
Throws:
DatabasePathException - If the default root is invalid or the database ID contains illegal characters.
DatabaseIOException - If the file system cannot 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 DatabaseIOException,
                             DatabasePathException
Checks whether a database already exists by specified URI.

Parameters:
uri - Database file URI.
Returns:
true if the database exists, false otherwise.
Throws:
DatabasePathException - If the default root is invalid or the database ID contains illegal characters.
DatabaseIOException - If the file system cannot 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,
                                    DatabasePathException
Opens or creates an encrypted database. If the database doesn't exist then it is created based on the securityOptions parameter.

If the database already exists then its security options remain the same. If the securityOptions argument is specified and the database already exists then opening procedure will succeed only if database security options haven't changed. So, for example, if a code signing key is specified then database will be opened only if it was protected with the given key during creation.

Only one read-write connection to a database can be opened at the same time. Other database connections must be read-only. If you need to open a database as read-write and read-only at the same time, you must open it first as read-write. Otherwise, “File system error 12” is generated, which indicates that an attempt was made to open more than one read-write connection.

Parameters:
id - Database filename using the default root.
securityOptions - Defines optional database security options, such as encryption. If database exists and security options are specified then the database will be opened only if it was created with the same security options.
Returns:
Database instance.
Throws:
DatabaseIOException - If there was an exception opening or creating the database.
DatabasePathException - If the path is invalid.
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,
                                    DatabaseOptions databaseOptions)
                             throws DatabaseIOException,
                                    DatabasePathException
Opens or creates an encrypted database with specified database options. If the database doesn't exist then it is created based on the securityOptions parameter.

Only one read-write connection to a database can be opened at the same time. Other database connections must be read-only. If you need to open a database as read-write and read-only at the same time, you must open it first as read-write. Otherwise, “File system error 12” is generated, which indicates that an attempt was made to open more than one read-write connection.

If the database already exists then its security options remain the same. If the securityOptions argument is specified and the database already exists then opening procedure will succeed only if database security options haven't changed. So, for example, if a code signing key is specified then database will be opened only if it was protected with the given key during creation.

Parameters:
id - Database filename using the default root.
securityOptions - Defines optional database security options, such as encryption. If database exists and security options are specified then the database will be opened only if it was created with the same security options.
databaseOptions - Defines optional database options, such as foreign key constraints.
Returns:
Database instance.
Throws:
DatabaseIOException - If there was an exception opening or creating the database.
DatabasePathException - If the path is invalid.
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 6.0.0

delete

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

Parameters:
fileURI - URI of the database file.
Throws:
DatabaseIOException - If the database is not deleted.
DatabasePathException - If the path is invalid.
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 an existing database from the device.

Parameters:
id - Database filename using the default root.
Throws:
DatabaseIOException - If the database is not deleted.
DatabasePathException - If the path is invalid.
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 plaintext database. This method binds the database to the current device. If the database is already encrypted then the method exits gracefully.

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

Parameters:
id - Existing database filename using the default root.
securityOptions - Defines database security options, such as whether protection by code signing key is required.
Throws:
DatabaseIOException - If there was a failure to encrypt the database.
DatabasePathException - If the path is invalid.
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 plaintext database. This method binds the database to the current device. If the database is already encrypted then the method exits gracefully.

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

Parameters:
fileURI - URI of the database file.
securityOptions - Defines database security options, such as whether protection by code signing key is required.
Throws:
DatabaseIOException - If there was a failure to encrypt the database.
DatabasePathException - If the path is invalid.
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. The database file must be closed before calling this method. If the database is plaintext already then the method exits gracefully.

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

Parameters:
id - Existent database filename using the default root.
Throws:
DatabaseIOException - If there was a failure to decrypt the database.
DatabasePathException - If the path is invalid.
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. The database file must be closed before calling this method. If the database is plaintext already then the method exits gracefully.

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

Parameters:
fileURI - URI of the database file.
Throws:
DatabaseIOException - If there was a failure to decrypt the database.
DatabasePathException - If the path is invalid.
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-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