Many hyperlinks are disabled.
Use anonymous login
to enable hyperlinks.
Overview
Comment: | Documentation updates to take the changes on this branch into account. |
---|---|
Downloads: | Tarball | ZIP archive |
Timelines: | family | ancestors | descendants | both | android-studio |
Files: | files | file ages | folders |
SHA1: |
546c6014891fba2d6afc590d898cde45 |
User & Date: | dan 2016-05-20 17:27:16.058 |
Context
2016-05-20
| ||
17:31 | Update the SQLite version bundled with this module to 3.13.0. (Closed-Leaf check-in: c44bb26627 user: dan tags: android-studio) | |
17:27 | Documentation updates to take the changes on this branch into account. (check-in: 546c601489 user: dan tags: android-studio) | |
2016-05-19
| ||
18:01 | Remove the "project" directory from this module. The root of the source tree is now the root of the android studio project. (check-in: 89726d7811 user: dan tags: android-studio) | |
Changes
Changes to www/index.wiki.
1 2 3 4 5 6 7 8 9 | <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. | < < < < < | < < < < | < | < | < < < < < | < < < | < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < | < | < < < < | < < < | < < < < | < < < < < < < < | < < < < < < < < < < < < < < < < < < < < | < < < < | < < | < < < | < | < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < | < < < < < | < < < | < < < < < < < < < | < < < | < < < < < < < < < < < < < < < < < < < < | 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 | <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> For most applications, this is convenient and works well. However, it means that applications must be content with the SQLite version and build installed on the target device as part of the operating system. 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> One solution is to bundle the SQLite library directly into the application, bypassing the version built-in to Android. This project, the <i>SQLite Android bindings</i>, provides an easy way to do just that. This allows an application to use a custom build or version of SQLite, regardless of the Android version to which it is deployed, while continuing to use the standard Android interface. Available User Documentation: * [./install.wiki | Installation Guide ] - this page describes the various ways the the SQLite Android bindings may be integrated with an application. * [./usage.wiki | Application Programming ] - this page describes the very minor code modifications required to use the SQLite Android bindings instead of Android's built-in SQLite support. * [./see.wiki | Using the Simple Encryption Extension (SEE) ] - extra notes regarding the use of the proprietary encryption extension SEE. |
Added www/install.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 | <h1>Installation</h1> <p> There are three ways to add the SQLite Android bindings to an application: <ol> <li> By adding a pre-built aar file to the applications <a href=https://developer.android.com/studio/index.html>Android Studio</a> project. <li> By building an aar file, then adding it to the applications Android Studio project as in (1). <li> By adding the SQLite Android bindings source code to and building it along with the other application code. </ol> <p> By default, the SQLite Android bindings support Android API levels 16 and greater (Android versions 4.1 and up). There is also a separate version that supports Android API levels 15 and greater (Android version 4.0.2 and up). Please note the extra step involved in [#obtaincode|obtaining the code] if you wish to use the version compatible with API level 15. <h2> <a name=prebuilt></a> 1. Using a Pre-Built aar File</h2> <p> This is the most straightforward option. An "aar" file is similar to a jar file, except that it may contain both compiled java classes and native code. An aar file for the latest SQLite release usable with API levels 16 and up is available from <a href=http://sqlite.org/download.html>this page</a>. <p> There are two steps involved in adding an aar file to an Android Studio project: <p> <ol> <li> <b>Import the module</b>. In Android Studio 2.1 this is accomplished by selecting the <code>"File" -> "New" -> "New Module..."</code> menu and then choosing <code>"Import JAR/AAR Package"</code>. <li> <b>Add a dependency on the new module to the main application</b> module (or to all modules that will use the SQLite Android bindings). In Android Studio 2.1 the dependency may be created using the project structure dialog (select <code>"File" -> "Project Structure..."</code>) or by adding code similar to the following to the application modules <code>build.gradle</code> file: <verbatim> dependencies { <i>// Change "sqlite3-release" to the name of the new module!</i> compile project(':sqlite3-release') }</verbatim> </ol> <p> At time of writing, aar files may only be used directly in Android Studio projects, not projects created using other IDEs (e.g. Eclipse, IntelliJ IDEA). However, an aar is just a zip archive containing a <code>classes.jar</code> file that in turn contains the SQLite Android binding java classes and a <code>jni/</code> directory that contains the native library for each platform. By extracting these two things from the aar file and adding them to the project separately it is often possible to use an aar file in non-Android Studio projects. <h2>2. <a name=customaar></a> Building a Custom aar File</h2> <p> Building a custom aar file requires both the Android SDK and NDK. <ol> <li><a name=obtaincode></a><b>Obtain the code</b>. The code for the SQLite Android bindings may be obtained either by checking out the <a href=http://fossil-scm.org>fossil</a> repository, or by downloading a zip file. <p> To obtain the code using fossil, use the following series of commands. In this case, the "project directory" refered to in subsequent steps is the <code>sqlite</code> directory created by the second command below: <p> <verbatim> $ fossil clone http://www.sqlite.org/android android.fossil $ mkdir sqlite $ cd sqlite $ fossil open ../android.fossil</verbatim> <p> Alternatively, the latest code may be downloaded as a <a href=http://www.sqlite.org/android/zip/SQLite+Android+Bindings.zip?uuid=trunk>zip archive</a>. In this case, the "project directory" is the <code>SQLite_Android_Bindings/</code> directory created by unzipping the downloaded archive. <p> <i>API level 15 users:</i> The code for the version that is compatible with Android API level 15 may be obtained as a zip file <a href=http://www.sqlite.org/android/zip/SQLite+Android+Bindings.zip?uuid=api-level-15>from here</a>. Or, if using fossil, the <code>fossil open</code> command above should be replaced with: <verbatim> $ fossil open ../android.fossil api-level-15</verbatim> <li><a name=buildnative></a> <b>Build the native libraries.</b> <p> To build the native libraries, navigate to the <code>sqlite3/src/main/</code> directory of the project directory and run the <code>ndk-build</code> command. For example, on Linux if Android Studio and the NDK are installed using their default paths: <verbatim> $ cd sqlite3/src/main $ ~/Android/Sdks/ndk-bundle/ndk-build</verbatim> <p> On modern hardware, this command takes roughly 2 minutes to build the native libraries for all Android architectures. <p> The latest release of the public domain SQLite library comes bundled with the SQLite Android bindings code downloaded in step 1. If you wish to use a different version of SQLite, for example one that contains the proprietry [./see.wiki | SEE extension], then replace the <code>sqlite3.c</code> and <code>sqlite3.h</code> files at the following locations before running the <code>ndk-build</code> command: <verbatim> sqlite3/src/main/jni/sqlite/sqlite3.c sqlite3/src/main/jni/sqlite/sqlite3.h</verbatim> <p> If you wish to build the SQLite library with non-standard command line switches, for example the -DSQLITE_ENABLE_FTS5 switch used to enable <a href=http://www.sqlite.org/fts5.html>FTS5</a>, they should be added to the <code>Android.mk</code> file at this location: <verbatim> sqlite3/src/main/jni/sqlite/Android.mk</verbatim> <p> If the <code>Android.mk</code> or <code>sqlite3.&lsp;ch&rsp;</code> files are edited after <code>ndk-build</code> is run, it may be necessary to run the <code>ndk-build clean</code> command before rerunning <code>ndk-build</code> to ensure a correct build. <p> Once <code>ndk-build</code> has been run successfully, unless you modify the <code>Android.mk</code> or <code>sqlite3.&lsp;ch&rsp;</code> files, it should not be necessary to run it again. It <i>does not</i> have to be run each time the application is rebuilt. <li> <b>Assemble the aar file</b>. To assemble the aar file using the command line, first set environment variable ANDROID_HOME to the SDK directory, then run the gradle "assembleRelease" target from within the "sqlite3" sub-directory of the project directory. For example: <verbatim> $ export ANDROID_HOME=~/Android/Sdk/ $ cd sqlite3 $ ../gradlew assembleRelease</verbatim> <p> Assembling an aar file using Android Studio is similar. Open the SQLite Android bindings project using Android Studio, run a "gradle sync", then run the "assembleRelease" gradle task within the "sqlite3" module. <p> Using either the command line or Android Studio to run the gradle task causes the aar file to be created at: <code>sqlite3/build/outputs/aar/sqlite3-release.aar</code>. <p> Once the custom aar file has been created, it may be used in an Android Studio application as described above. The aar file should be roughly 3MB in size. If it is much smaller than this (closer to 100KB), this indicates that the aar file is missing the native libraries. The usual cause of this is an unnoticed error while building the native libraries (step 2 above). </ol> <h2> <a name=directint></a> 3. Adding Source Code Directly to the Application</h2> <p> The SQLite Android bindings code may also be added directly to the application project, so that it is built and deployed in the same way as all other application code. <p> To copy the SQLite Android bindings code into an application: <ol> <li> Obtain the code in the same way as [#obtaincode | described above]. <li> Recursively copy the contents of the <code>sqlite3/main/src/jni/</code> directory into the application or application modules <code>jni/</code> directory. Then, from the parent of the <code>jni/</code> directory, run the <code>ndk-build</code> command, as [#buildnative | described here]. <li> Recursively copy the contents of the <code>sqlite3/main/src/java/</code> directory to whereever the application java code is. </ol> |
Added www/see.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 | <h1>Using The SQLite Encryption Extension</h1> <p> The <a href=http://www.sqlite.org/see/doc/trunk/www/readme.wiki>The SQLite Encryption Extension</a> provides an easy way to create, read and write encrypted database files. It may be used with the SQLite Android bindings to add encrypted database capability to any application. <h2> Building a SEE Enabled Version </h2> <p> Unless you are using a [./install.wiki#prebuilt | pre-built aar file] to use the SEE extension with the SQLite Android bindings you will need to build a custom version, either as a [./install.wiki#customaar | custom aar file] or by [./install.wiki#directint|directly integrating] the code with the application. <p> To do this, follow the instructions linked above. Except, before running the <code>ndk-build</code> command to build the native libraries: <ol> <li> Replace the <code>sqlite3.c</code> and <code>sqlite3.h</code> files with the SEE enable versions (i.e. the concatenation of sqlite3.c and see.c - refer to the link above for details). <li> Edit the Android.mk file so as to uncomment the second of the two lines reproduced below: <verbatim> # If using SEE, uncomment the following: # LOCAL_CFLAGS += -DSQLITE_HAS_CODEC </verbatim> </ol> <h2> Application Code Notes </h2> <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.<a href="http://developer.android.com/reference/android/database/sqlite/SQLiteDatabase.html#enableWriteAheadLogging()">enableWriteAheadLogging()</a> 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/usage.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 | <h1>Application Programming</h1> <h2>Loading the Shared Library</h2> <p> Before using any SQLite related methods or objects, the native SQLite library must be loaded into the application using the following code: <verbatim> System.loadLibrary("sqliteX"); </verbatim> <p> One way to ensure that the shared library is loaded early enough is to add it to a "static" block within the declaration of the application's main Activity class. <h2>Using the SQLite Android bindings classes</h2> <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> <h2>Differences From the Built-in SQLite Support</h2> <p>Aside from namespace changes, there are other 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. <li> The collation sequence "LOCALIZED", which normally changes with the system's current locale, is always equivalent to SQLite's built in collation BINARY. </ol> |