Add some documentation about the thread safety of Cursor and some of the SQLite* classes. (f3ca9a5c) · Commits · e / os / android_frameworks_base

core/java/android/database/Cursor.java

+3 −0

Original line number	Diff line number	Diff line
		@@ -25,6 +25,9 @@ import java.util.Map;
		/**
		* This interface provides random read-write access to the result set returned
		* by a database query.
		*
		* Cursor implementations are not required to be synchronized so code using a Cursor from multiple
		* threads should perform its own synchronization when using the Cursor.
		*/
		public interface Cursor {
		/**

core/java/android/database/sqlite/SQLiteCursor.java

+3 −0

Original line number	Diff line number	Diff line
		@@ -36,6 +36,9 @@ import java.util.concurrent.locks.ReentrantLock;
		/**
		* A Cursor implementation that exposes results from a query on a
		* {@link SQLiteDatabase}.
		*
		* SQLiteCursor is not internally synchronized so code using a SQLiteCursor from multiple
		* threads should perform its own synchronization when using the SQLiteCursor.
		*/
		public class SQLiteCursor extends AbstractWindowedCursor {
		static final String TAG = "Cursor";

core/java/android/database/sqlite/SQLiteDatabase.java

+16 −8

Original line number	Diff line number	Diff line
		@@ -1019,7 +1019,8 @@ public class SQLiteDatabase extends SQLiteClosable {
		*
		* @param sql The raw SQL statement, may contain ? for unknown values to be
		* bound later.
		* @return a pre-compiled statement object.
		* @return A pre-compiled {@link SQLiteStatement} object. Note that
		* {@link SQLiteStatement}s are not synchronized, see the documentation for more details.
		*/
		public SQLiteStatement compileStatement(String sql) throws SQLException {
		lock();
		@@ -1057,7 +1058,8 @@ public class SQLiteDatabase extends SQLiteClosable {
		* default sort order, which may be unordered.
		* @param limit Limits the number of rows returned by the query,
		* formatted as LIMIT clause. Passing null denotes no LIMIT clause.
		* @return A Cursor object, which is positioned before the first entry
		* @return A {@link Cursor} object, which is positioned before the first entry. Note that
		* {@link Cursor}s are not synchronized, see the documentation for more details.
		* @see Cursor
		*/
		public Cursor query(boolean distinct, String table, String[] columns,
		@@ -1095,7 +1097,8 @@ public class SQLiteDatabase extends SQLiteClosable {
		* default sort order, which may be unordered.
		* @param limit Limits the number of rows returned by the query,
		* formatted as LIMIT clause. Passing null denotes no LIMIT clause.
		* @return A Cursor object, which is positioned before the first entry
		* @return A {@link Cursor} object, which is positioned before the first entry. Note that
		* {@link Cursor}s are not synchronized, see the documentation for more details.
		* @see Cursor
		*/
		public Cursor queryWithFactory(CursorFactory cursorFactory,
		@@ -1133,7 +1136,8 @@ public class SQLiteDatabase extends SQLiteClosable {
		* @param orderBy How to order the rows, formatted as an SQL ORDER BY clause
		* (excluding the ORDER BY itself). Passing null will use the
		* default sort order, which may be unordered.
		* @return A {@link Cursor} object, which is positioned before the first entry
		* @return A {@link Cursor} object, which is positioned before the first entry. Note that
		* {@link Cursor}s are not synchronized, see the documentation for more details.
		* @see Cursor
		*/
		public Cursor query(String table, String[] columns, String selection,
		@@ -1170,7 +1174,8 @@ public class SQLiteDatabase extends SQLiteClosable {
		* default sort order, which may be unordered.
		* @param limit Limits the number of rows returned by the query,
		* formatted as LIMIT clause. Passing null denotes no LIMIT clause.
		* @return A {@link Cursor} object, which is positioned before the first entry
		* @return A {@link Cursor} object, which is positioned before the first entry. Note that
		* {@link Cursor}s are not synchronized, see the documentation for more details.
		* @see Cursor
		*/
		public Cursor query(String table, String[] columns, String selection,
		@@ -1188,7 +1193,8 @@ public class SQLiteDatabase extends SQLiteClosable {
		* @param selectionArgs You may include ?s in where clause in the query,
		* which will be replaced by the values from selectionArgs. The
		* values will be bound as Strings.
		* @return A {@link Cursor} object, which is positioned before the first entry
		* @return A {@link Cursor} object, which is positioned before the first entry. Note that
		* {@link Cursor}s are not synchronized, see the documentation for more details.
		*/
		public Cursor rawQuery(String sql, String[] selectionArgs) {
		return rawQueryWithFactory(null, sql, selectionArgs, null);
		@@ -1203,7 +1209,8 @@ public class SQLiteDatabase extends SQLiteClosable {
		* which will be replaced by the values from selectionArgs. The
		* values will be bound as Strings.
		* @param editTable the name of the first table, which is editable
		* @return A {@link Cursor} object, which is positioned before the first entry
		* @return A {@link Cursor} object, which is positioned before the first entry. Note that
		* {@link Cursor}s are not synchronized, see the documentation for more details.
		*/
		public Cursor rawQueryWithFactory(
		CursorFactory cursorFactory, String sql, String[] selectionArgs,
		@@ -1255,7 +1262,8 @@ public class SQLiteDatabase extends SQLiteClosable {
		* values will be bound as Strings.
		* @param initialRead set the initial count of items to read from the cursor
		* @param maxRead set the count of items to read on each iteration after the first
		* @return A {@link Cursor} object, which is positioned before the first entry
		* @return A {@link Cursor} object, which is positioned before the first entry. Note that
		* {@link Cursor}s are not synchronized, see the documentation for more details.
		*
		* This work is incomplete and not fully tested or reviewed, so currently
		* hidden.

core/java/android/database/sqlite/SQLiteProgram.java

+3 −0

Original line number	Diff line number	Diff line
		@@ -20,6 +20,9 @@ import android.util.Log;

		/**
		* A base class for compiled SQLite programs.
		*
		* SQLiteProgram is not internally synchronized so code using a SQLiteProgram from multiple
		* threads should perform its own synchronization when using the SQLiteProgram.
		*/
		public abstract class SQLiteProgram extends SQLiteClosable {
		private static final String TAG = "SQLiteProgram";

core/java/android/database/sqlite/SQLiteQuery.java

+3 −0

Original line number	Diff line number	Diff line
		@@ -23,6 +23,9 @@ import android.util.Log;
		/**
		* A SQLite program that represents a query that reads the resulting rows into a CursorWindow.
		* This class is used by SQLiteCursor and isn't useful itself.
		*
		* SQLiteQuery is not internally synchronized so code using a SQLiteQuery from multiple
		* threads should perform its own synchronization when using the SQLiteQuery.
		*/
		public class SQLiteQuery extends SQLiteProgram {
		private static final String TAG = "Cursor";