Package android.database

Class DatabaseUtils

  • public class DatabaseUtils
extends Object
    Static utility methods for dealing with databases and Cursors.

    • Constructor Detail

      • DatabaseUtils

        public DatabaseUtils()

    • Method Detail

      • writeExceptionToParcel

        public static final void writeExceptionToParcel​(Parcel reply,
                                                Exception e)
        Special function for writing an exception result at the header of a parcel, to be used when returning an exception from a transaction. exception will be re-thrown by the function in another process
        Parameters:
        reply - Parcel to write to
        e - The Exception to be written.
        See Also:
        Parcel.writeNoException(), Parcel.writeException(java.lang.Exception)

      • readExceptionFromParcel

        public static final void readExceptionFromParcel​(Parcel reply)
        Special function for reading an exception result from the header of a parcel, to be used after receiving the result of a transaction. This will throw the exception for you if it had been written to the Parcel, otherwise return and let you read the normal result data from the Parcel.
        Parameters:
        reply - Parcel to read from
        See Also:
        Parcel.writeNoException(), Parcel.readException()

      • bindObjectToProgram

        public static void bindObjectToProgram​(SQLiteProgram prog,
                                       int index,
                                       Object value)
        Binds the given Object to the given SQLiteProgram using the proper typing. For example, bind numbers as longs/doubles, and everything else as a string by call toString() on it.
        Parameters:
        prog - the program to bind the object to
        index - the 1-based index to bind at
        value - the value to bind

      • cursorFillWindow

        public static void cursorFillWindow​(Cursor cursor,
                                    int position,
                                    CursorWindow window)
        Fills the specified cursor window by iterating over the contents of the cursor. The window is filled until the cursor is exhausted or the window runs out of space. The original position of the cursor is left unchanged by this operation.
        Parameters:
        cursor - The cursor that contains the data to put in the window.
        position - The start position for filling the window.
        window - The window to fill.

      • appendEscapedSQLString

        public static void appendEscapedSQLString​(StringBuilder sb,
                                          String sqlString)
        Appends an SQL string to the given StringBuilder, including the opening and closing single quotes. Any single quotes internal to sqlString will be escaped. This method is deprecated because we want to encourage everyone to use the "?" binding form. However, when implementing a ContentProvider, one may want to add WHERE clauses that were not provided by the caller. Since "?" is a positional form, using it in this case could break the caller because the indexes would be shifted to accomodate the ContentProvider's internal bindings. In that case, it may be necessary to construct a WHERE clause manually. This method is useful for those cases.
        Parameters:
        sb - the StringBuilder that the SQL string will be appended to
        sqlString - the raw string to be appended, which may contain single quotes

      • sqlEscapeString

        public static String sqlEscapeString​(String value)
        SQL-escape a string.

      • appendValueToSql

        public static final void appendValueToSql​(StringBuilder sql,
                                          Object value)
        Appends an Object to an SQL string with the proper escaping, etc.

      • concatenateWhere

        public static String concatenateWhere​(String a,
                                      String b)
        Concatenates two SQL WHERE clauses, handling empty or null values.

      • getCollationKey

        public static String getCollationKey​(String name)
        return the collation key
        Parameters:
        name -
        Returns:
        the collation key

      • getHexCollationKey

        public static String getHexCollationKey​(String name)
        return the collation key in hex format
        Parameters:
        name -
        Returns:
        the collation key in hex format

      • dumpCursor

        public static void dumpCursor​(Cursor cursor)
        Prints the contents of a Cursor to System.out. The position is restored after printing.
        Parameters:
        cursor - the cursor to print

      • dumpCursor

        public static void dumpCursor​(Cursor cursor,
                              PrintStream stream)
        Prints the contents of a Cursor to a PrintSteam. The position is restored after printing.
        Parameters:
        cursor - the cursor to print
        stream - the stream to print to

      • dumpCursor

        public static void dumpCursor​(Cursor cursor,
                              StringBuilder sb)
        Prints the contents of a Cursor to a StringBuilder. The position is restored after printing.
        Parameters:
        cursor - the cursor to print
        sb - the StringBuilder to print to

      • dumpCursorToString

        public static String dumpCursorToString​(Cursor cursor)
        Prints the contents of a Cursor to a String. The position is restored after printing.
        Parameters:
        cursor - the cursor to print
        Returns:
        a String that contains the dumped cursor

      • dumpCurrentRow

        public static void dumpCurrentRow​(Cursor cursor)
        Prints the contents of a Cursor's current row to System.out.
        Parameters:
        cursor - the cursor to print from

      • dumpCurrentRow

        public static void dumpCurrentRow​(Cursor cursor,
                                  PrintStream stream)
        Prints the contents of a Cursor's current row to a PrintSteam.
        Parameters:
        cursor - the cursor to print
        stream - the stream to print to

      • dumpCurrentRow

        public static void dumpCurrentRow​(Cursor cursor,
                                  StringBuilder sb)
        Prints the contents of a Cursor's current row to a StringBuilder.
        Parameters:
        cursor - the cursor to print
        sb - the StringBuilder to print to

      • dumpCurrentRowToString

        public static String dumpCurrentRowToString​(Cursor cursor)
        Dump the contents of a Cursor's current row to a String.
        Parameters:
        cursor - the cursor to print
        Returns:
        a String that contains the dumped cursor row

      • cursorStringToContentValues

        public static void cursorStringToContentValues​(Cursor cursor,
                                               String field,
                                               ContentValues values)
        Reads a String out of a field in a Cursor and writes it to a Map.
        Parameters:
        cursor - The cursor to read from
        field - The TEXT field to read
        values - The ContentValues to put the value into, with the field as the key

      • cursorStringToInsertHelper

        public static void cursorStringToInsertHelper​(Cursor cursor,
                                              String field,
                                              DatabaseUtils.InsertHelper inserter,
                                              int index)
        Reads a String out of a field in a Cursor and writes it to an InsertHelper.
        Parameters:
        cursor - The cursor to read from
        field - The TEXT field to read
        inserter - The InsertHelper to bind into
        index - the index of the bind entry in the InsertHelper

      • cursorStringToContentValues

        public static void cursorStringToContentValues​(Cursor cursor,
                                               String field,
                                               ContentValues values,
                                               String key)
        Reads a String out of a field in a Cursor and writes it to a Map.
        Parameters:
        cursor - The cursor to read from
        field - The TEXT field to read
        values - The ContentValues to put the value into, with the field as the key
        key - The key to store the value with in the map

      • cursorIntToContentValues

        public static void cursorIntToContentValues​(Cursor cursor,
                                            String field,
                                            ContentValues values)
        Reads an Integer out of a field in a Cursor and writes it to a Map.
        Parameters:
        cursor - The cursor to read from
        field - The INTEGER field to read
        values - The ContentValues to put the value into, with the field as the key

      • cursorIntToContentValues

        public static void cursorIntToContentValues​(Cursor cursor,
                                            String field,
                                            ContentValues values,
                                            String key)
        Reads a Integer out of a field in a Cursor and writes it to a Map.
        Parameters:
        cursor - The cursor to read from
        field - The INTEGER field to read
        values - The ContentValues to put the value into, with the field as the key
        key - The key to store the value with in the map

      • cursorLongToContentValues

        public static void cursorLongToContentValues​(Cursor cursor,
                                             String field,
                                             ContentValues values)
        Reads a Long out of a field in a Cursor and writes it to a Map.
        Parameters:
        cursor - The cursor to read from
        field - The INTEGER field to read
        values - The ContentValues to put the value into, with the field as the key

      • cursorLongToContentValues

        public static void cursorLongToContentValues​(Cursor cursor,
                                             String field,
                                             ContentValues values,
                                             String key)
        Reads a Long out of a field in a Cursor and writes it to a Map.
        Parameters:
        cursor - The cursor to read from
        field - The INTEGER field to read
        values - The ContentValues to put the value into
        key - The key to store the value with in the map

      • cursorDoubleToCursorValues

        public static void cursorDoubleToCursorValues​(Cursor cursor,
                                              String field,
                                              ContentValues values)
        Reads a Double out of a field in a Cursor and writes it to a Map.
        Parameters:
        cursor - The cursor to read from
        field - The REAL field to read
        values - The ContentValues to put the value into

      • cursorDoubleToContentValues

        public static void cursorDoubleToContentValues​(Cursor cursor,
                                               String field,
                                               ContentValues values,
                                               String key)
        Reads a Double out of a field in a Cursor and writes it to a Map.
        Parameters:
        cursor - The cursor to read from
        field - The REAL field to read
        values - The ContentValues to put the value into
        key - The key to store the value with in the map

      • cursorRowToContentValues

        public static void cursorRowToContentValues​(Cursor cursor,
                                            ContentValues values)
        Read the entire contents of a cursor row and store them in a ContentValues.
        Parameters:
        cursor - the cursor to read from.
        values - the ContentValues to put the row into.

      • cursorPickFillWindowStartPosition

        public static int cursorPickFillWindowStartPosition​(int cursorPosition,
                                                    int cursorWindowCapacity)
        Picks a start position for Cursor#fillWindow such that the window will contain the requested row and a useful range of rows around it. When the data set is too large to fit in a cursor window, seeking the cursor can become a very expensive operation since we have to run the query again when we move outside the bounds of the current window. We try to choose a start position for the cursor window such that 1/3 of the window's capacity is used to hold rows before the requested position and 2/3 of the window's capacity is used to hold rows after the requested position.
        Parameters:
        cursorPosition - The row index of the row we want to get.
        cursorWindowCapacity - The estimated number of rows that can fit in a cursor window, or 0 if unknown.
        Returns:
        The recommended start position, always less than or equal to the requested row.

      • queryNumEntries

        public static long queryNumEntries​(SQLiteDatabase db,
                                   String table)
        Query the table for the number of rows in the table.
        Parameters:
        db - the database the table is in
        table - the name of the table to query
        Returns:
        the number of rows in the table

      • queryNumEntries

        public static long queryNumEntries​(SQLiteDatabase db,
                                   String table,
                                   String selection)
        Query the table for the number of rows in the table.
        Parameters:
        db - the database the table is in
        table - the name of the table to query
        selection - A filter declaring which rows to return, formatted as an SQL WHERE clause (excluding the WHERE itself). Passing null will count all rows for the given table
        Returns:
        the number of rows in the table filtered by the selection

      • queryNumEntries

        public static long queryNumEntries​(SQLiteDatabase db,
                                   String table,
                                   String selection,
                                   String[] selectionArgs)
        Query the table for the number of rows in the table.
        Parameters:
        db - the database the table is in
        table - the name of the table to query
        selection - A filter declaring which rows to return, formatted as an SQL WHERE clause (excluding the WHERE itself). Passing null will count all rows for the given table
        selectionArgs - You may include ?s in selection, which will be replaced by the values from selectionArgs, in order that they appear in the selection. The values will be bound as Strings.
        Returns:
        the number of rows in the table filtered by the selection

      • queryIsEmpty

        public static boolean queryIsEmpty​(SQLiteDatabase db,
                                   String table)
        Query the table to check whether a table is empty or not
        Parameters:
        db - the database the table is in
        table - the name of the table to query
        Returns:
        True if the table is empty

      • longForQuery

        public static long longForQuery​(SQLiteDatabase db,
                                String query,
                                String[] selectionArgs)
        Utility method to run the query on the db and return the value in the first column of the first row.

      • longForQuery

        public static long longForQuery​(SQLiteStatement prog,
                                String[] selectionArgs)
        Utility method to run the pre-compiled query and return the value in the first column of the first row.

      • stringForQuery

        public static String stringForQuery​(SQLiteDatabase db,
                                    String query,
                                    String[] selectionArgs)
        Utility method to run the query on the db and return the value in the first column of the first row.

      • stringForQuery

        public static String stringForQuery​(SQLiteStatement prog,
                                    String[] selectionArgs)
        Utility method to run the pre-compiled query and return the value in the first column of the first row.

      • blobFileDescriptorForQuery

        public static ParcelFileDescriptor blobFileDescriptorForQuery​(SQLiteDatabase db,
                                                              String query,
                                                              String[] selectionArgs)
        Utility method to run the query on the db and return the blob value in the first column of the first row.
        Returns:
        A read-only file descriptor for a copy of the blob value.

      • blobFileDescriptorForQuery

        public static ParcelFileDescriptor blobFileDescriptorForQuery​(SQLiteStatement prog,
                                                              String[] selectionArgs)
        Utility method to run the pre-compiled query and return the blob value in the first column of the first row.
        Returns:
        A read-only file descriptor for a copy of the blob value.

      • cursorStringToContentValuesIfPresent

        public static void cursorStringToContentValuesIfPresent​(Cursor cursor,
                                                        ContentValues values,
                                                        String column)
        Reads a String out of a column in a Cursor and writes it to a ContentValues. Adds nothing to the ContentValues if the column isn't present or if its value is null.
        Parameters:
        cursor - The cursor to read from
        column - The column to read
        values - The ContentValues to put the value into

      • cursorLongToContentValuesIfPresent

        public static void cursorLongToContentValuesIfPresent​(Cursor cursor,
                                                      ContentValues values,
                                                      String column)
        Reads a Long out of a column in a Cursor and writes it to a ContentValues. Adds nothing to the ContentValues if the column isn't present or if its value is null.
        Parameters:
        cursor - The cursor to read from
        column - The column to read
        values - The ContentValues to put the value into

      • cursorShortToContentValuesIfPresent

        public static void cursorShortToContentValuesIfPresent​(Cursor cursor,
                                                       ContentValues values,
                                                       String column)
        Reads a Short out of a column in a Cursor and writes it to a ContentValues. Adds nothing to the ContentValues if the column isn't present or if its value is null.
        Parameters:
        cursor - The cursor to read from
        column - The column to read
        values - The ContentValues to put the value into

      • cursorIntToContentValuesIfPresent

        public static void cursorIntToContentValuesIfPresent​(Cursor cursor,
                                                     ContentValues values,
                                                     String column)
        Reads a Integer out of a column in a Cursor and writes it to a ContentValues. Adds nothing to the ContentValues if the column isn't present or if its value is null.
        Parameters:
        cursor - The cursor to read from
        column - The column to read
        values - The ContentValues to put the value into

      • cursorFloatToContentValuesIfPresent

        public static void cursorFloatToContentValuesIfPresent​(Cursor cursor,
                                                       ContentValues values,
                                                       String column)
        Reads a Float out of a column in a Cursor and writes it to a ContentValues. Adds nothing to the ContentValues if the column isn't present or if its value is null.
        Parameters:
        cursor - The cursor to read from
        column - The column to read
        values - The ContentValues to put the value into

      • cursorDoubleToContentValuesIfPresent

        public static void cursorDoubleToContentValuesIfPresent​(Cursor cursor,
                                                        ContentValues values,
                                                        String column)
        Reads a Double out of a column in a Cursor and writes it to a ContentValues. Adds nothing to the ContentValues if the column isn't present or if its value is null.
        Parameters:
        cursor - The cursor to read from
        column - The column to read
        values - The ContentValues to put the value into

      • appendSelectionArgs

        public static String[] appendSelectionArgs​(String[] originalValues,
                                           String[] newValues)
        Appends one set of selection args to another. This is useful when adding a selection argument to a user provided set.

      • findRowIdColumnIndex

        public static int findRowIdColumnIndex​(String[] columnNames)
        Returns column index of "_id" column, or -1 if not found.