com.codename1.db

Class Database

java.lang.Object

com.codename1.db.Database

Direct Known Subclasses:

ThreadSafeDatabase

public abstract class Database
extends Object

Allows access to SQLite specifically connecting to a database and executing sql queries on the data. There is more thorough coverage of the Database API here.

The Database class abstracts the underlying SQLite of the device if available.
Notice that this might not be supported on all platforms in which case the Database will be null.

SQLite should be used for very large data handling, for small storage refer to Storage which is more portable.

The sample code below presents a Database Explorer tool that allows executing arbitrary SQL and viewing the tabular results:

Constructor Summary

Constructors

Constructor and Description
Database()

Method Summary

Modifier and Type	Method and Description
abstract void	beginTransaction() Starts a transaction
abstract void	close() Closes the database
abstract void	commitTransaction() Commits current transaction
static void	delete(String databaseName) Deletes database
abstract void	execute(String sql) Execute an update query.
void	execute(String sql, Object... params) Execute an update query with params.
abstract void	execute(String sql, String[] params) Execute an update query with params.
abstract Cursor	executeQuery(String sql) This method should be called with SELECT type statements that return row set.
Cursor	executeQuery(String sql, Object... params) This method should be called with SELECT type statements that return row set it accepts object with params.
abstract Cursor	executeQuery(String sql, String[] params) This method should be called with SELECT type statements that return row set.
static boolean	exists(String databaseName) Indicates weather a database exists
static String	getDatabasePath(String databaseName) Returns the file path of the Database if exists and if supported on the platform.
static boolean	isCustomPathSupported() Checks if this platform supports custom database paths.
static Database	openOrCreate(String databaseName) Opens a database or create one if not exists.
abstract void	rollbackTransaction() Rolls back current transaction
static boolean	supportsWasNull(Row row) Checks to see if the given row supports wasNull(com.codename1.db.Row).
static boolean	wasNull(Row row) Checks if the last value accessed from a given row was null.

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Database

public Database()

Method Detail

isCustomPathSupported

public static boolean isCustomPathSupported()

Checks if this platform supports custom database paths. On platforms that support this, you can pass a file path to openOrCreate(java.lang.String), exists(java.lang.String), delete(java.lang.String), and getDatabasePath(java.lang.String).

Returns:

True on platorms that support custom database paths.

openOrCreate

public static Database openOrCreate(String databaseName)
                             throws IOException

Opens a database or create one if not exists.

Parameters:

databaseName - the name of the database. Platforms that support custom database paths (i.e. isCustomPathSupported() return true), will also accept a file path here.

Returns:

Database Object or null if not supported on the platform

Throws:

IOException - if database cannot be created

exists

public static boolean exists(String databaseName)

Indicates weather a database exists

NOTE: Not supported in the Javascript port. Will always return false.

Parameters:

databaseName - the name of the database. Platforms that support custom database paths (i.e. isCustomPathSupported() return true), will also accept a file path here.

Returns:

true if database exists

delete

public static void delete(String databaseName)
                   throws IOException

Deletes database

NOTE: This method is not supported in the Javascript port. Will silently fail.

Parameters:

databaseName - the name of the database. Platforms that support custom database paths (i.e. isCustomPathSupported() return true), will also accept a file path here.

Throws:

IOException - if database cannot be deleted

getDatabasePath

public static String getDatabasePath(String databaseName)

Returns the file path of the Database if exists and if supported on the platform.

Parameters:

databaseName - The name of the database. Platforms that support custom database paths (i.e. isCustomPathSupported() return true), will also accept a file path here.

NOTE: This method will return null in the Javascript port.

Returns:

the file path of the database

beginTransaction

public abstract void beginTransaction()
                               throws IOException

Starts a transaction

NOTE: Not supported in Javascript port. This method will do nothing when running in Javascript.

Throws:

IOException - if database is not opened

commitTransaction

public abstract void commitTransaction()
                                throws IOException

Commits current transaction

NOTE: Not supported in Javascript port. This method will do nothing when running in Javascript.

Throws:

IOException - if database is not opened or transaction was not started

rollbackTransaction

public abstract void rollbackTransaction()
                                  throws IOException

Rolls back current transaction

NOTE: Not supported in Javascript port. This method will do nothing when running in Javascript.

Throws:

IOException - if database is not opened or transaction was not started

close

public abstract void close()
                    throws IOException

Closes the database

Throws:

IOException

execute

public abstract void execute(String sql)
                      throws IOException

Execute an update query. Used for INSERT, UPDATE, DELETE and similar sql statements.

Parameters:

sql - the sql to execute

Throws:

IOException

execute

public abstract void execute(String sql,
                             String[] params)
                      throws IOException

Execute an update query with params. Used for INSERT, UPDATE, DELETE and similar sql statements. The sql can be constructed with '?' and the params will be binded to the query

Parameters:

sql - the sql to execute

params - to bind to the query where the '?' exists

Throws:

IOException

execute

public void execute(String sql,
                    Object... params)
             throws IOException

Execute an update query with params. Used for INSERT, UPDATE, DELETE and similar sql statements. The sql can be constructed with '?' and the params will be binded to the query

Parameters:

sql - the sql to execute

params - to bind to the query where the '?' exists, supported object types are String, byte[], Double, Long and null

Throws:

IOException

executeQuery

public abstract Cursor executeQuery(String sql,
                                    String[] params)
                             throws IOException

This method should be called with SELECT type statements that return row set.

Parameters:

sql - the sql to execute

params - to bind to the query where the '?' exists

Returns:

a cursor to iterate over the results

Throws:

IOException

executeQuery

public Cursor executeQuery(String sql,
                           Object... params)
                    throws IOException

This method should be called with SELECT type statements that return row set it accepts object with params.

Parameters:

sql - the sql to execute

params - to bind to the query where the '?' exists, supported object types are String, byte[], Double, Long and null

Returns:

a cursor to iterate over the results

Throws:

IOException

executeQuery

public abstract Cursor executeQuery(String sql)
                             throws IOException

This method should be called with SELECT type statements that return row set.

Parameters:

sql - the sql to execute

Returns:

a cursor to iterate over the results

Throws:

IOException

wasNull

public static boolean wasNull(Row row)
                       throws IOException

Checks if the last value accessed from a given row was null. Not all platforms support wasNull(). If the platform does not support it, this will just return false.

Check supportsWasNull(com.codename1.db.Row) to see if the platform supports wasNull().

Currently wasNull() is supported on UWP, iOS, Android, and JavaSE (Simulator).

Parameters:

row - The row to check.

Returns:

True if the last value accessed was null.

Throws:

IOException

Since:

7.0

See Also:

RowExt.wasNull(), supportsWasNull(com.codename1.db.Row)

supportsWasNull

public static boolean supportsWasNull(Row row)
                               throws IOException

Checks to see if the given row supports wasNull(com.codename1.db.Row).

Parameters:

row - The row to check.

Returns:

True if the row supports wasNull().

Throws:

IOException

Since:

7.0

See Also:

wasNull(com.codename1.db.Row), RowExt.wasNull()