Database (BlackBerry JDE 6.0.0 API Reference)

Overview

Package

Class

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

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.

Create a SQL statement by calling Database.createStatement().
Prepare the statement to run by calling Statement.prepare(). Performing this step is like compiling the statement.
Run the statement by calling Statement.getCursor() if the statement might return results and Statement.execute() otherwise.
If there are results, retrieve them by iterating over the returned cursor row by row.

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