SQLite Android Bindings
Check-in [67c837ca6c]
Not logged in

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview
Comment:Add some documentation files.
Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1: 67c837ca6c01fcdb0727957b6abfe5beac265733
User & Date: dan 2013-12-25 17:50:15
Context
2013-12-25
18:56
Add a mising link to index.wiki. check-in: 8b4072a7db user: dan tags: trunk
17:50
Add some documentation files. check-in: 67c837ca6c user: dan tags: trunk
2013-12-24
19:16
Add a test to check that SQLiteOpenHelper works with SEE. check-in: 60c548bff9 user: dan tags: trunk
Changes
Hide Diffs Unified Diffs Ignore Whitespace Patch

Added www/index.wiki.

































































































































































































































































































































































































>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
<h1> 
SQLite Android Bindings 
</h1>

<p> The SQLite library is a core part of the Android environment. Java
applications and content providers access SQLite using the interface in
the 
<a href="http://developer.android.com/reference/android/database/sqlite/SQLiteDatabase.html">android.database.sqlite</a> namespace.

<p> One disadvantage of using Android's built-in SQLite support is that the
application is forced to use the version of SQLite that the current version of
Android happened to ship with. If your application happens to require a newer
version of SQLite, or a build with a custom extension or 
<a href=http://www.sqlite.org/vfs.html>VFS</a> installed, you're out of luck.

<p>The code in this project allows an application to use the 
<a href=http://developer.android.com/tools/sdk/ndk/index.html>Android NDK</a>
to build a custom version of SQLite to be shipped with the application while
still continuing to use the standard Java interface.

<h2>Normal Usage</h2>

<h3>Installation</h3>

<p>
  Copy the following files from this project into the equivalent locations in
  the application project.

<pre>
    jni/Android.mk
    jni/Application.mk
    jni/sqlite/*                       (copy contents of directory recursively)
    src/org/sqlite/database/*          (copy contents of directory recursively)
</pre>

<p>
  Following this, the directory structures should contain 
  <a href=tree.wiki>these files</a>.

<p>
  Directory "jni/sqlite/" contains copies of the sqlite3.h and sqlite3.c 
  source files. Between them, they contain the
  <a href=http://www.sqlite.org/amalgamation.html>source code for the SQLite
  library</a>. If necessary, replace these with the source for the specific 
  version of SQLite required. If SQLite is to be compiled with any special
  pre-processor macros defined, add them to the "jni/sqlite/Android.mk" file
  (not jni/Android.mk).

<p>
  Once the files have been added to the project, run the command "ndk-build"
  in the root directory of the project. This compiles the native code in
  the jni/ directory (including the custom SQLite version) to shared libraries
  that will be deployed to the device along with the application. Assuming
  it is successful, unless you modify the sources or makefiles within the
  jni/ directory structure, you should not need to run "ndk-build" again.

<h3>Application Programming</h3>

<p>
  The classes that make up the built-in Android SQLite interface reside in
  the "android.database.sqlite" namespace. This interface provides all of
  the same classes, except within the "org.sqlite.database.sqlite" namespace.
  This means that to modify an application to use the custom version of 
  SQLite, all that is usually required is to replace all occurrences
  "android.database.sqlite" within the source code with
  "org.sqlite.database.sqlite". For example, the following:

<verbatim>
  import android.database.sqlite.SQLiteDatabase;
</verbatim>

<p>should be replaced with:

<verbatim>
  import org.sqlite.database.sqlite.SQLiteDatabase;
</verbatim>

<p>
  As well as replacing all uses of the classes in the 
  android.database.sqlite.* namespace, the application must also be sure 
  to use the following two:

<verbatim>
  org.sqlite.database.SQLException
  org.sqlite.database.DatabaseErrorHandler
</verbatim>

<p>instead of:

<verbatim>
  android.database.SQLException
  android.database.DatabaseErrorHandler
</verbatim>
  
<p>Aside from namespace differences, there are only two differences from the
stock Android interface that applications need to be aware of:

<ol>
  <li> The SQLiteStatement.<a href="http://developer.android.com/reference/android/database/sqlite/SQLiteStatement.html#simpleQueryForBlobFileDescriptor()">simpleQueryForBlobFileDescriptor()</a> 
       API is not available.

  <li> The collation sequence "UNICODE" is not available. Additionally, the
       collation sequence "LOCALIZED", which normally changes with the 
       system's current locale, is always equivalent to SQLite's built
       in collation BINARY.
</ol>


<h2>Using The Simple Encryption Extension</h2>

<p>
  To use the <a href=http://www.sqlite.org/see/doc/trunk/www/readme.wiki>
  Simple Encryption Extension</a> (SEE) on Android, replace the sqlite3.c
  file at "jni/sqlite/sqlite3.c" with a SEE-enabled version (i.e. the
  concatenation of sqlite3.c and see.c - refer to the link above for
  details). Next, open the file jni/sqlite/Android.mk and locate the
  following two lines:

<verbatim>
  # If using SEE, uncomment the following:
  # LOCAL_CFLAGS += -DSQLITE_HAS_CODEC
</verbatim>

<p>
  Uncomment the second of them, then run "ndk-build" as described above to
  generate the shared libraries. 

<p>
  After opening or creating an encrypted database, the application must
  immediately execute a PRAGMA to configure the encryption key. This must
  be done before any other database methods are called. For example:

<verbatim>
  import org.sqlite.database.sqlite.SQLiteDatabase;

    ...

  SQLiteDatabase db = SQLiteDatabase.openOrCreateDatabase("my.db", null);
  db.execSQL("PRAGMA key = 'secretkey'");
</verbatim>

<p>
  Or, if you are using the
  <a href=http://developer.android.com/reference/android/database/sqlite/SQLiteOpenHelper.html>SQLiteOpenHelper</a>
  helper class, the PRAGMA must be the first thing executed within the
  onConfigure() callback. For example:

<verbatim>
  import org.sqlite.database.sqlite.SQLiteDatabase;
  import org.sqlite.database.sqlite.SQLiteHelper;

    ...

  class MyHelper extends SQLiteOpenHelper {
    ...
    void onConfigure(SQLiteDatabase db){
      db.execSQL("PRAGMA key = 'secretkey'");
    }
    ...
  }
</verbatim>

<p>
  Refer to the <a href=http://www.sqlite.org/see/doc/trunk/www/readme.wiki>
  SEE documentation</a> for further details regarding encryption keys.

<p>Aside from supporting encrypted databases, SEE-enabled builds behave
differently in two more respects:

<ol>
  <li> <p>The SQLiteDatabase.enableWriteAheadLogging() method does not enable
       connection pooling. It is not possible for connection pooling to be
       used with a SEE-enabled build (even if the database is unencrypted).

  <li> <p>In Android, if database corruption is encountered, or if an attempt is
       made to open a file that is not an SQLite database, the default
       behaviour is to delete the file and create an empty database file in 
       its place. In a SEE-enabled build, the default behaviour is to throw
       an exception.<br><br>
       The reason for this is that supplying an incorrect encryption key
       is indistinguishable from opening a file that is not a database file.
       And it seems too dangerous to simply delete the file in this case.
       <br><br>
       The default behaviour can be overriden using the
       <a href="http://developer.android.com/reference/android/database/DatabaseErrorHandler.html">DatabaseErrorHandler</a> interface.

</ol>





Added www/tree.wiki.























































































































































>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
<pre>
.
├── jni
│   ├── Android.mk
│   ├── Application.mk
│   └── sqlite
│       ├── ALog-priv.h
│       ├── android_database_SQLiteCommon.cpp
│       ├── android_database_SQLiteCommon.h
│       ├── android_database_SQLiteConnection.cpp
│       ├── android_database_SQLiteDebug.cpp
│       ├── android_database_SQLiteGlobal.cpp
│       ├── Android.mk
│       ├── JniConstants.cpp
│       ├── JNIHelp.cpp
│       ├── nativehelper
│       │   ├── JniConstants.h
│       │   ├── jni.h
│       │   ├── JNIHelp.h
│       │   └── ScopedLocalRef.h
│       ├── README
│       ├── sqlite3.c
│       ├── sqlite3.h
├── src
    └── org
        └── sqlite
            └── database
                ├── DatabaseErrorHandler.java
                ├── DefaultDatabaseErrorHandler.java
                ├── package.html
                ├── SQLException.java
                └── sqlite
                    ├── CloseGuard.java
                    ├── DatabaseObjectNotClosedException.java
                    ├── ExtraUtils.java
                    ├── package.html
                    ├── SQLiteAbortException.java
                    ├── SQLiteAccessPermException.java
                    ├── SQLiteBindOrColumnIndexOutOfRangeException.java
                    ├── SQLiteBlobTooBigException.java
                    ├── SQLiteCantOpenDatabaseException.java
                    ├── SQLiteClosable.java
                    ├── SQLiteConnection.java
                    ├── SQLiteConnectionPool.java
                    ├── SQLiteConstraintException.java
                    ├── SQLiteCursorDriver.java
                    ├── SQLiteCursor.java
                    ├── SQLiteCustomFunction.java
                    ├── SQLiteDatabaseConfiguration.java
                    ├── SQLiteDatabaseCorruptException.java
                    ├── SQLiteDatabase.java
                    ├── SQLiteDatabaseLockedException.java
                    ├── SQLiteDatatypeMismatchException.java
                    ├── SQLiteDebug.java
                    ├── SQLiteDirectCursorDriver.java
                    ├── SQLiteDiskIOException.java
                    ├── SQLiteDoneException.java
                    ├── SQLiteException.java
                    ├── SQLiteFullException.java
                    ├── SQLiteGlobal.java
                    ├── SQLiteMisuseException.java
                    ├── SQLiteOpenHelper.java
                    ├── SQLiteOutOfMemoryException.java
                    ├── SQLiteProgram.java
                    ├── SQLiteQueryBuilder.java
                    ├── SQLiteQuery.java
                    ├── SQLiteReadOnlyDatabaseException.java
                    ├── SQLiteSession.java
                    ├── SQLiteStatementInfo.java
                    ├── SQLiteStatement.java
                    ├── SQLiteTableLockedException.java
                    ├── SQLiteTransactionListener.java
                    ├── SqliteWrapper.java

</pre>