|
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||
java.lang.Objectnet.rim.device.api.database.DatabaseFactory
public class DatabaseFactory
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.
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.
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();
}
}
}
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() );
}
}
}
PersistentObject,
DatabaseSecurityOptions| Method Summary | ||
|---|---|---|
|
static Database |
create(String id)
Creates a new plaintext database. |
|
static Database |
create(String id,
DatabaseOptions databaseOptions)
Creates a new plaintext database with specified database options. |
|
static Database |
create(String id,
DatabaseSecurityOptions securityOptions)
Creates a new database with the specified security options. |
|
static Database |
create(String id,
DatabaseSecurityOptions securityOptions,
DatabaseOptions databaseOptions)
Creates a new database with the specified security options and database options. |
|
static Database |
create(URI fileURI)
Creates a new plaintext database. |
|
static Database |
create(URI fileURI,
DatabaseOptions databaseOptions)
Creates a new plaintext database with specified database options. |
|
static Database |
create(URI fileURI,
DatabaseSecurityOptions securityOptions)
Creates a new database with specified security options. |
|
static Database |
create(URI fileURI,
DatabaseSecurityOptions securityOptions,
DatabaseOptions databaseOptions)
Creates a new database with specified security options and database options. |
|
static void |
decrypt(String id)
Decrypts an encrypted database. |
|
static void |
decrypt(URI fileURI)
Decrypts an encrypted database. |
|
static void |
delete(String id)
Removes an existing database from the device. |
|
static void |
delete(URI fileURI)
Removes an existing database from the device. |
|
static void |
encrypt(String id,
DatabaseSecurityOptions securityOptions)
Encrypts a plaintext database. |
|
static void |
encrypt(URI fileURI,
DatabaseSecurityOptions securityOptions)
Encrypts a plaintext database. |
|
static boolean |
exists(String id)
Checks whether a database already exists by specified ID. |
|
static boolean |
exists(URI uri)
Checks whether a database already exists by specified URI. |
|
static String |
getDefaultRoot()
Gets the default root at which database files are created. |
|
static Database |
open(String id)
Opens an existing database. |
|
static Database |
open(String id,
boolean readOnly)
Opens an existing database. |
|
static Database |
open(String id,
boolean readOnly,
DatabaseOptions databaseOptions)
Opens an existing database with specified database options. |
|
static Database |
open(String id,
boolean readOnly,
DatabaseSecurityOptions securityOptions,
DatabaseOptions databaseOptions)
Opens an existing database with specified database options. |
|
static Database |
open(String id,
DatabaseOptions databaseOptions)
Opens an existing database with specified database options. |
|
static Database |
open(URI fileURI)
Opens an existing database. |
|
static Database |
open(URI fileURI,
boolean readOnly)
Opens an existing database; optionally, opens the database in read-only mode. |
|
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. |
|
static Database |
open(URI fileURI,
boolean readOnly,
DatabaseSecurityOptions securityOptions,
DatabaseOptions databaseOptions)
Opens an existing database with specified database options. |
|
static Database |
open(URI fileURI,
DatabaseOptions databaseOptions)
Opens an existing database with the specified database options. |
|
static Database |
openOrCreate(String id)
Opens or creates a plaintext database. |
|
static Database |
openOrCreate(String id,
DatabaseOptions databaseOptions)
Opens or creates a plaintext database with specified database options. |
|
static Database |
openOrCreate(String id,
DatabaseSecurityOptions securityOptions)
Opens or creates an encrypted database. |
|
static Database |
openOrCreate(String id,
DatabaseSecurityOptions securityOptions,
DatabaseOptions databaseOptions)
Opens or creates an encrypted database with specified database options. |
|
static Database |
openOrCreate(URI fileURI)
Opens or creates a plaintext database. |
|
static Database |
openOrCreate(URI fileURI,
DatabaseOptions databaseOptions)
Opens or creates a plaintext database with specified database options. |
|
static Database |
openOrCreate(URI fileURI,
DatabaseSecurityOptions securityOptions)
Opens or creates a database. |
|
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 |
|---|
public static String getDefaultRoot()
public static Database create(String id,
DatabaseSecurityOptions securityOptions)
throws DatabaseIOException,
DatabasePathException
If the securityOptions argument is null, the database will be plaintext and accessible from any application.
id - Database filename using the default root.securityOptions - Defines optional database security options, such as encryption.
DatabasePathException
DatabaseIOExceptionDatabaseFactory.create(String)
public static Database create(String id,
DatabaseSecurityOptions securityOptions,
DatabaseOptions databaseOptions)
throws DatabaseIOException,
DatabasePathException
If the securityOptions argument is null then the database will be plaintext and accessible from any application.
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.
DatabasePathException
DatabaseIOExceptionDatabaseFactory.create(String)
public static Database create(String id)
throws DatabaseIOException,
DatabasePathException
id - Database filename using the default root.
DatabasePathException
DatabaseIOException
public static Database create(String id,
DatabaseOptions databaseOptions)
throws DatabaseIOException,
DatabasePathException
id - Database filename using the default root.databaseOptions - Defines optional database options, such as foreign key constraints.
DatabasePathException
DatabaseIOException
public static Database create(URI fileURI)
throws DatabaseIOException,
DatabasePathException
fileURI - URI of the database file.
DatabasePathException
DatabaseIOException
public static Database create(URI fileURI,
DatabaseOptions databaseOptions)
throws DatabaseIOException,
DatabasePathException
fileURI - URI of the database file.databaseOptions - Defines optional database options, such as foreign key constraints.
DatabasePathException
DatabaseIOException
public static Database create(URI fileURI,
DatabaseSecurityOptions securityOptions)
throws DatabaseIOException,
DatabasePathException
If the securityOptions argument is null then the database will be plaintext and accessible from any application.
fileURI - URI of the database file.securityOptions - Defines optional database security options, such as encryption.
DatabasePathException
DatabaseIOException
public static Database create(URI fileURI,
DatabaseSecurityOptions securityOptions,
DatabaseOptions databaseOptions)
throws DatabaseIOException,
DatabasePathException
If the securityOptions argument is null then the database will be plaintext and accessible from any application.
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.
DatabasePathException
DatabaseIOException
public static Database open(URI fileURI)
throws ControlledAccessException,
DatabaseIOException,
DatabasePathException
If the database was encrypted then the caller's module is verified against the code signing key that was used during database creation.
fileURI - URI of the database file.
DatabaseIOException - On failure.
ControlledAccessException - If the caller does not have read permission.
DatabasePathException
public static Database open(URI fileURI,
DatabaseOptions databaseOptions)
throws ControlledAccessException,
DatabaseIOException,
DatabasePathException
If the database was encrypted then the caller's module is verified against the code signing key that was used during database creation.
fileURI - URI of the database file.databaseOptions - Defines optional database options, such as foreign key constraints.
DatabaseIOException - On failure.
ControlledAccessException - If the caller does not have read permission.
DatabasePathException
public static Database open(URI fileURI,
boolean readOnly)
throws ControlledAccessException,
DatabaseIOException,
DatabasePathException
If the database was encrypted then the caller's module is verified against the code signing key that was used during database creation.
fileURI - URI of the database file.readOnly - Open for read-only.
DatabaseIOException - On failure.
ControlledAccessException - If the caller does not have read permission.
DatabasePathException
public static Database open(URI fileURI,
boolean readOnly,
DatabaseOptions databaseOptions)
throws ControlledAccessException,
DatabaseIOException,
DatabasePathException
If the database was encrypted then the caller's module is verified against the code signing key that was used during database creation.
fileURI - URI of the database file.readOnly - Open for read-only.databaseOptions - Defines optional database options, such as foreign key constraints.
DatabaseIOException - On failure.
ControlledAccessException - If the caller does not have read permission.
DatabasePathException
public static Database open(URI fileURI,
boolean readOnly,
DatabaseSecurityOptions securityOptions,
DatabaseOptions databaseOptions)
throws ControlledAccessException,
DatabaseIOException,
DatabasePathException
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.
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.
DatabaseIOException - On failure.
ControlledAccessException - If the caller does not have read permission or database security attributes are different from what was specified
in the securityOptions method argument
DatabasePathException
public static Database open(String id)
throws ControlledAccessException,
DatabaseIOException,
DatabasePathException
id - Database filename using the default root.
DatabaseIOException - On failure.
ControlledAccessException - On access restriction.
DatabasePathException
public static Database open(String id,
DatabaseOptions databaseOptions)
throws ControlledAccessException,
DatabaseIOException,
DatabasePathException
id - Database filename using the default root.databaseOptions - Defines optional database options, such as foreign key constraints.
DatabaseIOException - On failure.
ControlledAccessException - On access restriction.
DatabasePathException
public static Database open(String id,
boolean readOnly)
throws ControlledAccessException,
DatabaseIOException,
DatabasePathException
id - Database filename using the default root.readOnly - Open for read-only.
DatabaseIOException - On failure.
ControlledAccessException - On access restriction.
DatabasePathException
public static Database open(String id,
boolean readOnly,
DatabaseOptions databaseOptions)
throws ControlledAccessException,
DatabaseIOException,
DatabasePathException
id - Database filename using the default root.readOnly - Open for read-only.databaseOptions - Defines optional database options, such as foreign key constraints.
DatabaseIOException - On failure.
ControlledAccessException - On access restriction.
DatabasePathException
public static Database open(String id,
boolean readOnly,
DatabaseSecurityOptions securityOptions,
DatabaseOptions databaseOptions)
throws ControlledAccessException,
DatabaseIOException,
DatabasePathException
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.
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.
DatabaseIOException - On failure.
ControlledAccessException - On access restriction.
DatabasePathException
public static Database openOrCreate(String id)
throws DatabaseIOException,
ControlledAccessException,
DatabasePathException
id - Database filename using the default root.
DatabaseIOException - On failure.
ControlledAccessException - On access restriction.
DatabasePathException
public static Database openOrCreate(String id,
DatabaseOptions databaseOptions)
throws DatabaseIOException,
ControlledAccessException,
DatabasePathException
id - Database filename using the default root.databaseOptions - Defines optional database options, such as foreign key constraints.
DatabaseIOException - On failure.
ControlledAccessException - On access restriction.
DatabasePathException
public static Database openOrCreate(URI fileURI)
throws DatabaseIOException,
ControlledAccessException,
DatabasePathException
fileURI - URI of the database file.
DatabaseIOException - On failure.
ControlledAccessException - On access restriction.
DatabasePathException
public static Database openOrCreate(URI fileURI,
DatabaseOptions databaseOptions)
throws DatabaseIOException,
ControlledAccessException,
DatabasePathException
fileURI - URI of the database file.databaseOptions - Defines optional database options, such as foreign key constraints.
DatabaseIOException - On failure.
ControlledAccessException - On access restriction.
DatabasePathException
public static Database openOrCreate(URI fileURI,
DatabaseSecurityOptions securityOptions)
throws DatabaseIOException,
ControlledAccessException,
DatabasePathException
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.
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.
DatabaseIOException - On failure.
ControlledAccessException - On access restriction.
DatabasePathException
IllegalArgumentException
public static Database openOrCreate(URI fileURI,
DatabaseSecurityOptions securityOptions,
DatabaseOptions databaseOptions)
throws DatabaseIOException,
ControlledAccessException,
DatabasePathException
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.
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
DatabaseIOException - On failure.
ControlledAccessException - On access restriction.
DatabasePathException
IllegalArgumentException
public static boolean exists(String id)
throws DatabasePathException,
DatabaseIOException
id - Database ID.
true if the database exists, false otherwise.
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.
public static boolean exists(URI uri)
throws DatabasePathException,
DatabaseIOException
uri - Database file URI.
true if the database exists, false otherwise.
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.
public static Database openOrCreate(String id,
DatabaseSecurityOptions securityOptions)
throws DatabaseIOException,
ControlledAccessException,
DatabasePathException
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.
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.
DatabaseIOException - On failure.
ControlledAccessException - On access restriction.
DatabasePathException
IllegalArgumentException
public static Database openOrCreate(String id,
DatabaseSecurityOptions securityOptions,
DatabaseOptions databaseOptions)
throws DatabaseIOException,
ControlledAccessException,
DatabasePathException
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.
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.
DatabaseIOException - On failure.
ControlledAccessException - On access restriction.
DatabasePathException
IllegalArgumentException
public static void delete(URI fileURI)
throws DatabaseIOException,
DatabasePathException
fileURI - URI of the database file.
DatabasePathException - If the path is invalid.
DatabaseIOException - If the database is not deleted.
public static void delete(String id)
throws DatabaseIOException,
DatabasePathException
id - Database filename using the default root.
DatabasePathException - If the path is invalid.
DatabaseIOException - If the database is not deleted.
public static void encrypt(String id,
DatabaseSecurityOptions securityOptions)
throws DatabaseIOException,
DatabasePathException
If content protection is turned ON then this operation will succeed only when the device is unlocked.
id - Existing database filename using the default root.securityOptions - Defines database security options, such as whether protection by code signing key is required.
DatabaseIOException
DatabasePathException
public static void encrypt(URI fileURI,
DatabaseSecurityOptions securityOptions)
throws DatabaseIOException,
DatabasePathException
If content protection is turned ON then this operation will succeed only when the device is unlocked.
fileURI - URI of the database file.securityOptions - Defines database security options, such as whether protection by code signing key is required.
DatabaseIOException
DatabasePathException
public static void decrypt(String id)
throws DatabaseIOException,
DatabasePathException
If content protection is turned ON then this operation will succeed only when the device is unlocked.
id - Existent database filename using the default root.key - The code signing key for this database.
DatabaseIOException
DatabasePathException
public static void decrypt(URI fileURI)
throws DatabaseIOException,
DatabasePathException
If content protection is turned ON then this operation will succeed only when the device is unlocked.
fileURI - URI of the database file.
DatabaseIOException
DatabasePathException
|
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||
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