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, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    Modifier and Type
    Method
    Description
    protected Object
    clone()
     
    boolean
    equals(Object obj)
    Indicates whether some other object is "equal to" this one.
    final Class
    getClass()
    Returns the runtime class of an object.
    int
    hashCode()
    Returns a hash code value for the object.
    final void
    notify()
    Wakes up a single thread that is waiting on this object's monitor.
    final void
    notifyAll()
    Wakes up all threads that are waiting on this object's monitor.
    String
    toString()
    Returns a string representation of the object.
    final void
    wait()
    Causes current thread to wait until another thread invokes the method or the method for this object.
    final void
    wait(long timeout)
    Causes current thread to wait until either another thread invokes the method or the method for this object, or a specified amount of time has elapsed.
    final void
    wait(long timeout, int nanos)
    Causes current thread to wait until another thread invokes the method or the method for this object, or some other thread interrupts the current thread, or a certain amount of real time has elapsed.

  • 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