Skip to content

Commit 6c1ac4c

Browse files
committed
Improve README and javadoc.
1 parent 85dcb11 commit 6c1ac4c

File tree

4 files changed

+44
-105
lines changed

4 files changed

+44
-105
lines changed

README.md

+5-2
Original file line numberDiff line numberDiff line change
@@ -128,7 +128,8 @@ method.
128128
### Build WCDB Android with Prebuilt Dependencies
129129

130130
WCDB itself can be built apart from its dependencies using Gradle or Android Studio.
131-
To build WCDB Android library, run Gradle on `android` directory:
131+
To build WCDB Android library, import Gradle project or run Gradle wrapper on
132+
`android` directory:
132133

133134
```bash
134135
$ cd android
@@ -144,7 +145,9 @@ sdk.dir=path/to/sdk
144145
ndk.dir=path/to/ndk
145146
```
146147

147-
Android Studio will do this for you when the project is imported.
148+
Android Studio will do this for you when the project is imported. If you have
149+
*"Failed to notify project evaluation listener"* error, double check your `ndk.dir`
150+
property.
148151

149152
### Build Dependencies from Sources
150153

android/wcdb/src/com/tencent/wcdb/database/SQLiteDatabase.java

+21-97
Original file line numberDiff line numberDiff line change
@@ -2373,7 +2373,20 @@ public boolean isDatabaseIntegrityOk() {
23732373
return true;
23742374
}
23752375

2376-
2376+
/**
2377+
* Acquire database connection from connection pool and return its native handle
2378+
* (a.k.a {@code sqlite3 *}).
2379+
*
2380+
* <p>The caller must release the returned handle when finished with it by calling
2381+
* {@link #releaseNativeConnection(long, Exception)} <strong>within the same thread</strong>.
2382+
* Failed to release the returned handle will cause connection leakage and probably
2383+
* ANR.</p>
2384+
*
2385+
* @param operation string describing usage of the connection, for logging
2386+
* @param readOnly whether operations on returned connection is read-only
2387+
* @param interactive whether operations on returned connection is for interactive
2388+
* @return {@code sqlite3 *} handle casted to {@code long}
2389+
*/
23772390
public long acquireNativeConnectionHandle(String operation, boolean readOnly, boolean interactive) {
23782391
if (operation == null)
23792392
operation = "unnamedNative";
@@ -2387,6 +2400,13 @@ public long acquireNativeConnectionHandle(String operation, boolean readOnly, bo
23872400
.getNativeHandle(operation);
23882401
}
23892402

2403+
/**
2404+
* Release connection returned by {@link #acquireNativeConnectionHandle(String, boolean, boolean)}.
2405+
*
2406+
* @param nativePtr {@code sqlite3 *} handle to release
2407+
* @param ex exception occurred during operations on the native handle,
2408+
* or null for successful operations
2409+
*/
23902410
public void releaseNativeConnection(long nativePtr, Exception ex) {
23912411
getThreadSession().releaseConnectionForNativeHandle(ex);
23922412
}
@@ -2429,100 +2449,4 @@ SQLiteProgram newQuery(SQLiteDatabase db, String query,
24292449
public interface CustomFunction {
24302450
public void callback(String[] args);
24312451
}
2432-
2433-
public static boolean copyTables(SQLiteDatabase OrgDb, SQLiteDatabase CipDb) {
2434-
boolean status = false;
2435-
2436-
HashSet<String> sysTables = new HashSet<String>();
2437-
//sysTables.add("android_metadata");
2438-
sysTables.add("sqlite_sequence");
2439-
2440-
StringBuilder sql = new StringBuilder("select DISTINCT tbl_name from sqlite_master");
2441-
Cursor cursorTableName = OrgDb.rawQuery(sql.toString(), null);
2442-
if (cursorTableName != null) {
2443-
int tblCount = cursorTableName.getCount();
2444-
while (cursorTableName.moveToNext()) {
2445-
tblCount--;
2446-
String tableName = cursorTableName.getString(0);
2447-
2448-
sql.setLength(0);
2449-
sql.append("select sql from sqlite_master where tbl_name = '").append(tableName).append("'");
2450-
android.database.Cursor cursorTableDesc = OrgDb.rawQuery(sql.toString(), null);
2451-
if (cursorTableDesc != null) {
2452-
if (cursorTableDesc.moveToNext()) {
2453-
if (sysTables.contains(tableName)) {
2454-
cursorTableDesc.close();
2455-
continue;
2456-
}
2457-
CipDb.execSQL(cursorTableDesc.getString(0));
2458-
2459-
Cursor cursorTableText = OrgDb.rawQuery("select * from " + tableName, null);
2460-
if (cursorTableText != null && cursorTableText.getCount() > 0) {
2461-
sql.setLength(0);
2462-
sql.append("insert into ").append(tableName).append("(");
2463-
if (cursorTableText.getColumnCount() > 0) {
2464-
StringBuilder value = new StringBuilder(" values(");
2465-
for (String columnName : cursorTableText.getColumnNames()) {
2466-
sql.append(columnName).append(",");
2467-
value.append("?,");
2468-
}
2469-
value.deleteCharAt(value.length() - 1);
2470-
sql.deleteCharAt(sql.length() - 1);
2471-
sql.append(")").append(value).append(")");
2472-
}
2473-
2474-
SQLiteStatement stat = CipDb.compileStatement(sql.toString());
2475-
CipDb.beginTransaction();
2476-
2477-
int columnCount = cursorTableText.getColumnCount();
2478-
int[] columnTypes = new int[columnCount];
2479-
cursorTableText.moveToFirst();
2480-
for (int i = 0; i < columnCount; i++)
2481-
columnTypes[i] = cursorTableText.getType(i);
2482-
do {
2483-
for (int i = 0; i < columnCount; i++) {
2484-
switch (columnTypes[i]) {
2485-
case Cursor.FIELD_TYPE_STRING: {
2486-
String s = cursorTableText.getString(i);
2487-
if (s != null) stat.bindString(i + 1, s);
2488-
else stat.bindNull(i + 1);
2489-
break;
2490-
}
2491-
case Cursor.FIELD_TYPE_INTEGER: {
2492-
stat.bindLong(i + 1, cursorTableText.getLong(i));
2493-
break;
2494-
}
2495-
case Cursor.FIELD_TYPE_BLOB: {
2496-
byte[] b = cursorTableText.getBlob(i);
2497-
if (b != null) stat.bindBlob(i + 1, b);
2498-
else stat.bindNull(i + 1);
2499-
break;
2500-
}
2501-
case Cursor.FIELD_TYPE_FLOAT: {
2502-
stat.bindDouble(i + 1, cursorTableText.getDouble(i));
2503-
break;
2504-
}
2505-
case Cursor.FIELD_TYPE_NULL: {
2506-
stat.bindNull(i + 1);
2507-
break;
2508-
}
2509-
default: {
2510-
}
2511-
}
2512-
}
2513-
stat.executeInsert();
2514-
} while (cursorTableText.moveToNext());
2515-
CipDb.setTransactionSuccessful();
2516-
CipDb.endTransaction();
2517-
cursorTableText.close();
2518-
}
2519-
}
2520-
cursorTableDesc.close();
2521-
}
2522-
}
2523-
cursorTableName.close();
2524-
if (tblCount == 0) status = true;
2525-
}
2526-
return status;
2527-
}
25282452
}

android/wcdb/src/com/tencent/wcdb/database/SQLiteDirectCursor.java

+10-1
Original file line numberDiff line numberDiff line change
@@ -46,7 +46,16 @@ public class SQLiteDirectCursor extends AbstractCursor {
4646
private int mCount;
4747
private boolean mCountFinished;
4848

49-
49+
/**
50+
* Execute a query and provide access to its result set through a Cursor
51+
* interface. For a query such as: {@code SELECT name, birth, phone FROM
52+
* myTable WHERE ... LIMIT 1,20 ORDER BY...} the column names (name, birth,
53+
* phone) would be in the projection argument and everything from
54+
* {@code FROM} onward would be in the params argument.
55+
*
56+
* @param editTable the name of the table used for this query
57+
* @param query the {@link SQLiteDirectQuery} object associated with this cursor object.
58+
*/
5059
public SQLiteDirectCursor(SQLiteCursorDriver driver, String editTable, SQLiteDirectQuery query) {
5160
if (query == null) {
5261
throw new IllegalArgumentException("query object cannot be null");

android/wcdb/src/com/tencent/wcdb/database/SQLiteMisuseException.java

+8-5
Original file line numberDiff line numberDiff line change
@@ -19,14 +19,17 @@
1919
/**
2020
* This error can occur if the application creates a SQLiteStatement object and allows multiple
2121
* threads in the application use it at the same time.
22-
* Sqlite returns this error if bind and execute methods on this object occur at the same time
23-
* from multiple threads, like so:
24-
* thread # 1: in execute() method of the SQLiteStatement object
25-
* while thread # 2: is in bind..() on the same object.
22+
* <p>
23+
* SQLite returns this error if bind and execute methods on this object occur at the same time
24+
* from multiple threads, like so:<br>
25+
* thread # 1: in {@code execute()} method of the {@link SQLiteStatement} object<br>
26+
* while thread # 2: is in bind..() on the same object.<br>
2627
*</p>
27-
* FIX this by NEVER sharing the same SQLiteStatement object between threads.
28+
* <p>
29+
* FIX this by NEVER sharing the same {@link SQLiteStatement} object between threads.
2830
* Create a local instance of the SQLiteStatement whenever it is needed, use it and close it ASAP.
2931
* NEVER make it globally available.
32+
* </p>
3033
*/
3134
@SuppressWarnings("serial")
3235
public class SQLiteMisuseException extends SQLiteException {

0 commit comments

Comments
 (0)