net.rim.device.api.database
Interface Database


public interface Database

Lets you create, modify, and access SQLite databases.

BlackBerry devices that run BlackBerry® Device Software 5.0 or later include the open source SQLite library. The Database API gives you access to this library. Although SQLite databases are optimized for use on a smartphone, the API is similar to other database APIs. The Database API is an interface for the SQLite library so that you can create, delete and execute SQLite SQL statements, as well as perform other common database management tasks. For more information about SQLite, visit http://www.sqlite.org.

Use the following approach to work with an existing SQLite database.

By default, a transaction is created for each statement. If the statement runs successfully, it is automatically committed. If it fails, it is rolled back. If you do not want each statement to run in its own transaction (for example, if you want to run multiple statements in one transaction, which can have performance benefits), then you should use Database.beginTransaction() and Database.commitTransaction() to change the default behavior and manually manage transactions. Nested transactions are not supported.

SQLite databases created by your application are not removed automatically when your application is removed.

Code sample: Creating a SQLite database

This example creates a SQLite database at the root of a media card.
 import net.rim.device.api.system.Application;
 import net.rim.device.api.database.*;
 import net.rim.device.api.io.*;
 
 public class CreateDatabase extends Application
 {
    public static void main(String[] args)
    {
        CreateDatabase app = new CreateDatabase();
      try
      {
           URI strURI = URI.create("file:///SDCard/test.db"); 
           DatabaseFactory.create(strURI);
       }
       catch ( Exception e ) 
       {         
           System.out.println( e.getMessage() );
      }  
   } 
 }
 

Code sample: Adding a table to a SQLite database

 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
      {
         URI myURI = URI.create("/SDCard/test.db"); 
         Database d = DatabaseFactory.open(myURI);
         Statement st = d.createStatement( "CREATE TABLE 'People' ( " +
                                           "'Name' TEXT, " +
                                           "'Age' INTEGER )" );
         st.prepare();
         st.execute();
         st.close();
         }
         catch ( Exception e ) 
         {         
           System.out.println( e.getMessage() );
         }
  }
 }
 

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
       {
          URI myURI = URI.create("/SDCard/test.db"); 
          Database d = DatabaseFactory.open(myURI);
          Statement st = d.createStatement("INSERT INTO People(Name,Age) " +
                                           "VALUES ('John',37)");
          st.prepare();
          st.execute();
          st.close();
       }
       catch ( Exception e ) 
       {         
          System.out.println( e.getMessage() );
       }
   }
 }
 

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  void beginTransaction()
          Starts a new transaction.
Category: Signed  void close()
          Closes the database.
Category: Signed  void commitTransaction()
          Commits the current transaction.
Category: Signed  Statement createStatement(String sqlStatement)
          Creates a Statement in this database.
Category: Signed  DatabaseSecurityOptions getDatabaseSecurityOptions()
          Returns a new object with populated database security options.
Category: Signed  URI getFile()
          Returns the URI of the database file.
Category: Signed  String getLastError()
          Returns the last error message from the database.
Category: Signed  int getNumberOfChanges()
          Returns the number of rows affected by the last database modification.
Category: Signed  boolean isEncrypted()
          Returns encrypted database property.
Category: Signed  long lastInsertedRowID()
          Returns the last automatically-generated RowID (the primary key).
Category: Signed  void rollbackTransaction()
          Rolls back the current transaction.
 



Method Detail

close

void close()
           throws DatabaseIOException
Closes the database.

Statements should be closed explicitly to free up resources.

Throws:
DatabaseIOException - If the database file can't be closed and data can't be flushed from the file. For example, a DatabaseIOException is thrown when close() is called and the microSD card has been removed.
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

createStatement

Statement createStatement(String sqlStatement)
                          throws DatabaseException
Creates a Statement in this database.

If the given SQL parameter contains multiple statements separated by semicolons (;) then only the first one is parsed and executed. The remaining statements after the first semicolon are ignored.

Statements should be closed explicitly to free up resources.

Parameters:
sqlStatement - SQL statement to execute.
Returns:
Statement.
Throws:
DatabaseException - If the database is closed.
NullPointerException - If the SQL statement is null.
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

getFile

URI getFile()
            throws DatabasePathException
Returns the URI of the database file. In SQLite, each database is one file.

Returns:
The URI of the database file.
Throws:
DatabasePathException - If the specified path is incorrect. The path can be incorrect when the microSD card is removed.
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

getNumberOfChanges

int getNumberOfChanges()
                       throws DatabaseException
Returns the number of rows affected by the last database modification.

Returns:
The number of rows affected.
Throws:
DatabaseException - If the database is closed.
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

lastInsertedRowID

long lastInsertedRowID()
                       throws DatabaseException
Returns the last automatically-generated RowID (the primary key).

Each entry in a SQLite table has a unique 64-bit signed integer key called the RowID. The RowID is always available as an undeclared column named ROWID, OID, or _ROWID_ as long as those names are not also used by explicitly declared columns. If the table has a column of type INTEGER PRIMARY KEY then that column is another alias for the RowID.

Care should be taken when there are concurrent inserts to the same database. To ensure that the correct RowID is returned, the INSERT and the call to lastInsertedRowID() should be done within a synchronized block. The synchronized block should be used in a way that blocks any other INSERT statement from executing (and modifying the last inserted RowID).

Returns:
The ID (primary key) of the last row that was inserted.
Throws:
DatabaseException - Thrown when the database is closed.
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

getLastError

String getLastError()
                    throws DatabaseException
Returns the last error message from the database.

Returns:
Error message string.
Throws:
DatabaseException - If the database is closed.
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

isEncrypted

boolean isEncrypted()
                    throws DatabaseException
Returns encrypted database property.

Returns:
true if the database is encrypted; otherwise false.
Throws:
DatabaseException - If the database is not open.
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

getDatabaseSecurityOptions

DatabaseSecurityOptions getDatabaseSecurityOptions()
                                                   throws DatabaseException
Returns a new object with populated database security options.

Returns:
DatabaseSecurityOptions New object with populated database security options.
Throws:
DatabaseException - If the database is not open.
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

beginTransaction

void beginTransaction()
                      throws DatabaseException
Starts a new transaction. All the following statements are executed in the transaction until it is committed or rolled back. If the transaction is not committed then it is rolled back. Nested transactions are not supported and if this method is called twice, a DatabaseException is thrown.

Throws:
DatabaseException - If the database is not open or if this method is called twice.
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

commitTransaction

void commitTransaction()
                       throws DatabaseException
Commits the current transaction.

If the application does not close all cursors that were started within the transaction, the commit fails.

Throws:
DatabaseException - If the database is not open or the transaction was not started.
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

rollbackTransaction

void rollbackTransaction()
                         throws DatabaseException
Rolls back the current transaction. All updates are lost.

Throws:
DatabaseException - If the database is not open or the transaction was not started.
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.