am 1a3b3d48: merge from open-source master

Merge commit '1a3b3d48413d9134738c9b457292fb2b71a5dfe4' into kraken

* commit '1a3b3d48413d9134738c9b457292fb2b71a5dfe4':
  Add some documentation about the thread safety of Cursor and some of the SQLite* classes.

core/java/android/database/Cursor.java

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

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

@@ -1134,7 +1134,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();
@@ -1175,7 +1176,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,
@@ -1213,7 +1215,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,
@@ -1254,7 +1257,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,
@@ -1291,7 +1295,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,
@@ -1309,7 +1314,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);
@@ -1324,7 +1330,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,
@@ -1379,7 +1386,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

@@ -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 {
 

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

@@ -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";

core/java/android/database/sqlite/SQLiteStatement.java

@@ -23,6 +23,9 @@ import android.os.SystemClock;
  * The statement cannot return multiple rows, but 1x1 result sets are allowed.
  * Don't use SQLiteStatement constructor directly, please use
  * {@link SQLiteDatabase#compileStatement(String)}
+ *
+ * SQLiteStatement is not internally synchronized so code using a SQLiteStatement from multiple
+ * threads should perform its own synchronization when using the SQLiteStatement.
  */
 public class SQLiteStatement extends SQLiteProgram
 {