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 com.codename1.io.Storage which is more portable.

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

Toolbar.setGlobalToolbar(true);
Style s = UIManager.getInstance().getComponentStyle("TitleCommand");
FontImage icon = FontImage.createMaterial(FontImage.MATERIAL_QUERY_BUILDER, s);
Form hi = new Form("SQL Explorer", new BorderLayout());
hi.getToolbar().addCommandToRightBar("", icon, (e) -> {
    TextArea query = new TextArea(3, 80);
    Command ok = new Command("Execute");
    Command cancel = new Command("Cancel");
    if(Dialog.show("Query", query, ok, cancel) == ok) {
        Database db = null;
        Cursor cur = null;
        try {
            db = Display.getInstance().openOrCreate("MyDB.db");
            if(query.getText().startsWith("select")) {
                cur = db.executeQuery(query.getText());
                int columns = cur.getColumnCount();
                hi.removeAll();
                if(columns > 0) {
                    boolean next = cur.next();
                    if(next) {
                        ArrayList data = new ArrayList<>();
                        String[] columnNames = new String[columns];
                        for(int iter = 0 ; iter

@author Chen

Constructor Summary

Constructors

Constructor	Description
Database()

Method Summary

Modifier and Type	Method	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 Object

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

Constructor Details

Database

public Database()

Method Details

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: @param 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

Throws:

IOException

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: @param 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: @param 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

Throws:

IOException

getDatabasePath

public static String getDatabasePath(String databaseName)

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

Parameters

• databaseName: @param 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

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)

Throws:

IOException

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()

Throws:

IOException

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

Throws:

IOException

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

Throws:

IOException

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

Throws:

IOException

close

public abstract void close()
                    throws IOException

Closes the database

Throws

• IOException

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

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

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: @param params to bind to the query where the '?' exists, supported object types are String, byte[], Double, Long and null

Throws

• IOException

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

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: @param 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

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

Throws:

IOException