From 542207464ff3034add4adeb9ae7f1968460489c7 Mon Sep 17 00:00:00 2001 From: Google Code Exporter Date: Tue, 17 Mar 2015 20:05:00 -0400 Subject: [PATCH] Migrating wiki contents from Google Code --- BuildingFromSource.md | 82 ++++++++++++++++++++++++++++ ChangeLog.md | 42 +++++++++++++++ ComparisonToOtherWrappers.md | 47 ++++++++++++++++ Downloads.md | 14 +++++ GettingStarted.md | 27 ++++++++++ JobQueue.md | 100 +++++++++++++++++++++++++++++++++++ ProjectHome.md | 50 ++++++++++++++++++ UsingWithMaven.md | 99 ++++++++++++++++++++++++++++++++++ 8 files changed, 461 insertions(+) create mode 100644 BuildingFromSource.md create mode 100644 ChangeLog.md create mode 100644 ComparisonToOtherWrappers.md create mode 100644 Downloads.md create mode 100644 GettingStarted.md create mode 100644 JobQueue.md create mode 100644 ProjectHome.md create mode 100644 UsingWithMaven.md diff --git a/BuildingFromSource.md b/BuildingFromSource.md new file mode 100644 index 0000000..d352c8e --- /dev/null +++ b/BuildingFromSource.md @@ -0,0 +1,82 @@ +# Building from Source # + +## Install Required SDKs and Libraries ## + +You will need: + * JDK 1.5+ + * In order to run tests, JRE matching target platform is needed; that is, to build and test sqlite4java for Windows x86 and x64, you'll need x86 and x64 versions of the JRE. It's possible to skip tests. + * Install system package, or + * Download Java SE + * Apache Ant version 1.7.0 or later. + * Install system package, or + * Download from Apache website + * Make sure you have ANT\_HOME environment variable set to the Ant installation directory + * If tests fail to start, try putting `junit.jar` from `lib/` folder in the source tree into the ANT\_HOME/lib folder. + * Gant version 1.6.1 or later (with Groovy 1.6.0 or later) + * Install system packages, or + * Get older (but known to work) version here: Groovy and Gant, or + * Get newer versions from Codehaus: Groovy and Gant. + * Make sure you have GROOVY\_HOME and GANT\_HOME environment variables set to the installation directories of Groovy and Gant, respectively. + * SWIG 1.3.32 or later + * Install system packages, or + * Download from SWIG website (Windows users should download `swigwin`) + * On Windows: Windows SDK with VC compiler + * If you don't have Windows SDK or Visual Studio installed, download Windows SDK from MSDN (free). + * On Linux and Mac OS X: GCC (optionally, with multi-platform support) + * Install system packages (including `gcc-multilib` if you're building for a different platform) + +## Check Out Sources ## + +Get sources with `svn checkout http://sqlite4java.googlecode.com/svn/trunk/ sqlite4java` + +The source tree contains the following directories: + * `ant` - build scripts and related files; + * `idea` - IntelliJ IDEA project files; + * `java` - Java sources; + * `lib` - libraries used during build; + * `native` - additional C code for the wrapper; + * `sqlite` - SQLite source files (amalgamation); + * `swig` - source files for SWIG, with the pre-generated sources; + * `test` - Java test sources. + +## Run Build Script ## + +Build script is `ant/build.gant`. You should run `gant` in the `ant/` subdirectory with at least one target and passing the required and maybe optional properties. Use target `all` if in doubt. + +| **Target** | **Effect** | +|:-----------|:-----------| +| `dist` | Builds distributable files in `build/dist` directory | +| `all` | Builds and tests the library, compiles `build/distzip/sqlite4java-OS-NNN.zip`, the distributable file for your operating system | +| `test` | Runs tests | +| `clean` | Clears `build/` directory | +| `debug` | Tells script to build native libraries in DEBUG configuration only | +| `release` | Tells script to build native libraries in RELEASE configuration only | + +Properties are passed with `-Dname=value` parameter. + +| **Property** | **When Required?** | **Value means** | +|:-------------|:-------------------|:----------------| +| `jdk.home` | Always | Home path of the JDK used to compile the Java code | +| `swig.home` | If on Windows, or if `swig` is not on the `$PATH` | Home path of the SWIG code generator | +| `wsdk.home` | On Windows | Home path of the Windows SDK. There should be a file `bin\SetEnv.Cmd` in that directory that sets up the environment for VC build. | +| `platforms` | Never | Used to override the default list of platforms built under the current operating systems. See default values in `ant/operatingSystem.properties`. | +| `jre.win32-x86` | On Windows, if building with tests for x86 platform | JRE or JDK home path with the x86 Java | +| `jre.win32-x64` | On Windows, if building with tests for x64 platform | JRE or JDK home path with the x64 Java | +| `jre.linux-i386` | On Linux, if building with tests for i386 platform | JRE or JDK home path with the i386 Java | +| `jre.linux-amd64` | On Linux, if building with tests for amd64 platform | JRE or JDK home path with the amd64 Java | +| `jre.osx` | On Mac OS X, if building with tests | JRE or JDK home path | + +## Sample Build Commands ## + +On Windows: + +> `gant -Djdk.home=C:\Dev\jdk16u17 -Dswig.home=C:\Dev\swigwin-1.3.32 -Dwsdk.home=C:\Dev\wsdk60 -Djre.win32-x86=C:\Dev\jdk16u17\jre -Djre.win32-x64=C:\Dev\jdk16u17x64\jre release all` + +On Linux: + +> `gant -Djdk.home=/opt/jdk -Djre.linux-i386=/opt/jdk/jre release all` + + + + + diff --git a/ChangeLog.md b/ChangeLog.md new file mode 100644 index 0000000..f499bea --- /dev/null +++ b/ChangeLog.md @@ -0,0 +1,42 @@ +### Build 392 ### + + * SQLite upgraded to 3.8.7 + * Improved support for Android, added binary for x86-based Android. + * Improved support for Mac OS X, fixed a number of issues with locating and loading binary. + * Added OSGi bundle. + * Added support for column metadata - see `SQLiteConnection.getTableColumnMetadata()` and `SQLiteColumnMetadata` class. + * Added method `SQLiteConnection.isReadOnly()` to check if the database is opened on a read-only medium or with read-only flag. + * Added support for non-ASCII characters in SQL (`exec`, `prepareStatement`). + * Added `SQLiteConnection.setLimit()` method. + * Added `SQLiteConnection.bind(...)` methods that take parameter names instead of parameter indexes. + +Backwards compatibility note: + + * Dropped support for Mac OS X 10.4 or earlier, and PowerPC-based Macs. + +### Build 282 ### + + * SQLite upgraded to 3.7.10 + * Added support for [SQLite Backup API](http://www.sqlite.org/backup.html) - see `SQLiteConnection.initializeBackup()` and `SQLiteBackup` class. + * Added support for android with the new binary sqlite4java-android-armv7.so (no need to rename the binary). + * Added support for extension loading - see `SQLiteConnection.setExtensionLoadingEnabled()` and `SQLiteConnection.loadExtension()`. + * R-Tree support in SQLite compiled in. + * Automatic searching for compatible binaries is rewritten and should be more stable. (It looks into sqlite4java.library.path, directory with sqlite4java.jar and java.library.path.) + * Fixed issues with searching Long Array virtual table for non-integer values. + +### Build 213 ### + + * SQLite upgraded to 3.7.4 + * SQLiteLongArray support in native code is completely rewritten. It is now reliable and optimized (you can specify that the numbers are sorted and/or unique to speed up lookups). + +### Build 201 ### + + * New `SQLiteQueue` and `SQLiteJob` classes - a job queue implementation for accessing single-threaded SQLite connection in a multi-threaded or GUI application ([#3](http://code.google.com/p/sqlite4java/issues/detail?id=3)). + * `SQLiteConnection.dispose()` method contract changed: it is now not allowed to call dispose from a different (non-confining) thread, due to possible JVM crash ([#18](http://code.google.com/p/sqlite4java/issues/detail?id=18)). If called from different thread, the method will fail softly. + * New `SQLiteConnection.getOpenFlags()` method return the flags that were used to open the connection. + * Updated contract for `SQLiteStatement.columnCount()`: now it can return the number of result columns before running the statement, or after statement has completed. However, the result in those cases is not stable (see javadocs)([#13](http://code.google.com/p/sqlite4java/issues/detail?id=13)). + * Added binaries for Mac OS X 10.4 (Intel and PPC) ([#6](http://code.google.com/p/sqlite4java/issues/detail?id=6)). + +Thanks to Olivier Monaco for patches and suggestions. + +### Change Log Started ### \ No newline at end of file diff --git a/ComparisonToOtherWrappers.md b/ComparisonToOtherWrappers.md new file mode 100644 index 0000000..7294c8c --- /dev/null +++ b/ComparisonToOtherWrappers.md @@ -0,0 +1,47 @@ +# Comparison to Other Java Wrappers for SQLite # +_As of 2010-06-01_ + +Current list of SQLite wrappers for Java can be found in [SQLite Wiki](http://www.sqlite.org/cvstrac/wiki?p=SqliteWrappers). + +**Note on JDBC drivers**: we specifically have created a wrapper for SQLite, not a JDBC driver, so that we can have features important for a GUI application -- good and **optimizable** performance (we can add performance hacks as needed), low garbage generation, predictable and responsive behavior. The tradeoff is that without JDBC, application loses independence from database vendor. But in many cases, this independence is very illusionary and you cannot easily migrate to a different database. + +For that reason, we don't compare sqlite4java with JDBC drivers here. You either need a JDBC driver, or a wrapper. + +### 1. Javasqlite Wrapper/JDBC driver from Christian Werner, http://www.ch-werner.de/javasqlite ### + +This is probably the most widely used library. We first tried to use it for our purposes, but dropped it for the following reasons: + * Little regard to how Java works, for example, by using `native finalize()` method as a destructor (!), which would generate exceptions, and theoretically can ruin the database; + * Very Java-unfriendly naming of classes and methods; + * Absense of bulk-load performance hacks, which makes loading queries with large results really slow. + +However, the library has certain advantages: + * Support for user-defined SQL functions via callbacks (yet, one wouldn't expect great performance from a JNI callback-supported SQL function); + * Support for authorizer and progress handler. + +### 2. SQLite JDBC Driver from Xerial, http://www.xerial.org/trac/Xerial/wiki/SQLiteJDBC ### + +Probably the best and most up-to-date JDBC driver for SQLite as of the time of this writing. + +### 3. Sqlite wrapper from TK-Software, http://tk-software.home.comcast.net/~tk-software/# ### + +Largely outdated, Java-unfriendly and lacks some basic functions, like `bind` methods. + +### 4. SqliteJDBC from David Crawshaw, http://www.zentus.com/sqlitejdbc/ ### + +This is a JDBC driver. Besides, pure java version is said to be much slower than the original SQLite. + +### 5. SQLite for Java from Rodolfo d'Ettorre, http://rodolfo_3.tripod.com/index.html ### + +Only for Windows, very basic functionality, outdated. + +### 6. SQLite JDBC Driver for Mysaifu JVM, http://sourceforge.jp/projects/sqlitejdbc ### + +Hard to get any information on this one. + +### 7. SQLJet from TMate Software, http://www.sqljet.com ### + +This is not a real SQLite wrapper, but a pure Java for working with SQLite databases on the low level. + +### 8. Android SDK, http://developer.android.com/reference/android/database/sqlite/package-summary.html ### + +Android SDK seems to have a good wrapper interfaces in package `android.database.sqlite`, yet it's not clear whether it can be used outside Android OS. \ No newline at end of file diff --git a/Downloads.md b/Downloads.md new file mode 100644 index 0000000..a950ae2 --- /dev/null +++ b/Downloads.md @@ -0,0 +1,14 @@ +# Downloads # + +**Latest version:** +| **File** | **Description** | **MD5** | +|:---------|:----------------|:--------| +| [sqlite4java-392.zip](https://d1.almworks.com/.files/sqlite4java/sqlite4java-392.zip) | sqlite4java-392 with **SQLite 3.8.7**, Windows/Linux/Mac OS X/Android binaries | `964d49c5da1b9666297db63314a6015d` | +| [com.almworks.sqlite4java-1.0.392.jar](https://d1.almworks.com/.files/sqlite4java/com.almworks.sqlite4java-1.0.392.jar) | OSGi bundle with sqlite4java-392 | `fd865eabb43934b62a5ae18a2c62a7f3` | + +## Older Files ## + +**Previous version:** + * [sqlite4java-282](http://code.google.com/p/sqlite4java/downloads/detail?name=sqlite4java-282.zip) with **SQLite 3.7.10** + +Older versions and contributions are available for download from [Google Code's Download Section](https://code.google.com/p/sqlite4java/downloads/list?can=1&q=) \ No newline at end of file diff --git a/GettingStarted.md b/GettingStarted.md new file mode 100644 index 0000000..1f8888d --- /dev/null +++ b/GettingStarted.md @@ -0,0 +1,27 @@ +# Getting Started # + + 1. Grab the latest build from the downloads. The file is named **`sqlite4java-NNN.zip`**, where NNN is the svn repository version used to build the library. + 1. The file contains: + * `sqlite4java.jar` - place it on your CLASSPATH; + * Native libraries (`*.dll, *.so, *.jnilib`) - place them in the same directory with `sqlite4java.jar`; + * `sqlite4java-src.zip` - Java sources, add this file as the library sources in your IDE; + * `sqlite4java-docs.zip` - javadocs for the reference (see also javadocs online). + 1. Run `java -jar sqlite4java.jar` to see the version of the library, the version of SQLite and compile-time options. This also verifies that native library loads normally on your platform. + 1. Get acquainted with classes SQLiteConnection and SQLiteStatement. Here's a short code sample: +``` + SQLiteConnection db = new SQLiteConnection(new File("/tmp/database")); + db.open(true); + ... + SQLiteStatement st = db.prepare("SELECT order_id FROM orders WHERE quantity >= ?"); + try { + st.bind(1, minimumQuantity); + while (st.step()) { + orders.add(st.columnLong(0)); + } + } finally { + st.dispose(); + } + ... + db.dispose(); +``` + 1. If you're doing a GUI application, create a separate thread for running SQLite and organize job queue. \ No newline at end of file diff --git a/JobQueue.md b/JobQueue.md new file mode 100644 index 0000000..69d5317 --- /dev/null +++ b/JobQueue.md @@ -0,0 +1,100 @@ +### About Job Queue ### + +The sqlite4java's job queue implementation helps in the following situations: + * You need shared access to the same SQLiteConnection from different threads (as opposed to each thread [a pool](in.md) having its own SQLiteConnection). + * You need to perform database operations in a GUI application, and you don't want to access the database in your GUI event queue thread (a very good idea). + +In sqlite4java, SQLiteConnection is confined to the thread that opens the connection, so you can't simply share it among threads. The job queue's function is to start a separate thread, which will host the connection, and queue job tasks from other threads for asynchronous execution. + +### Lifecycle ### + +1. Start database queue +``` + SQLiteQueue queue = new SQLiteQueue(databaseFile); + queue.start(); +``` + +2. Place a job in the queue for execution +``` + queue.execute(new SQLiteJob() { + protected Object job(SQLiteConnection connection) throws SQLiteException { + // this method is called from database thread and passed the connection + connection.exec(...); + return null; + } + }); +``` + +3. Stop the queue and wait until all pending jobs are finished executing +``` + queue.stop(true).join(); +``` + +### Blocking Read: Use SQLiteJob's Future Interface ### + +If you need to read something from SQLite and continue execution, you can use `get()` methods, provided by SQLiteJob's implementation of `java.util.concurrent.Future` interface. + +Or, if you don't want to catch all the exceptions thrown by the `Future.get()`, you can use convenience method called `complete`: +``` + final String tableName = ...; + int count = queue.execute(new SQLiteJob() { + protected Integer job(SQLiteConnection connection) throws SQLiteException { + SQLiteStatement st = connection.prepare("SELECT count(*) FROM " + tableName); + try { + return st.step() ? st.columnInt(0) : 0; + } finally { + st.dispose(); + } + } + }).complete(); +``` + +### Asynchronous Read: Override `jobFinished()` Method ### + +If you need to do a job and then use the result to update UI, you don't want to block the execution of UI thread with `complete()` method. Instead: + +``` + final String tableName = ...; + queue.execute(new SQLiteJob() { + protected Integer job(SQLiteConnection connection) throws SQLiteException { + SQLiteStatement st = connection.prepare("SELECT count(*) FROM " + tableName); + try { + return st.step() ? st.columnInt(0) : 0; + } finally { + st.dispose(); + } + } + + protected void jobFinished(Integer result) { + if (result != null) + callback.tableCount(tableName, result); + else + callback.problemHappened(); + } + }); +``` + +Wonder why you should override `jobFinished()` instead of simply calling `callback` at the end of `job()` method? + +Because `jobFinished()` is called **always**, whether job has finished successfully, or it has thrown an exception, even when the job has been cancelled and its `job()` method actually never ran. Ignoring errors and cancellation may leave your UI application in some intermediate state. + +There are also `jobCancelled()`, `jobError()` and `jobStarted()` methods, specifically designed for overriding. In all these methods you can inspect `this` instance of the `SQLiteJob` for its status. + +### Job Queue and Transactions ### + +Job queue implementation does not enforce any transaction policy - your jobs may start and commit/rollback transactions as needed. But it is strongly advised that transaction boundaries are kept within a single job, that is, if you `BEGIN TRANSACTION` in a job, you make sure you do `COMMIT` or `ROLLBACK` in the end. + +If you leave transaction unfinished at the end of the job, locks will remain held (which may prevent concurrent connections from working with database), and you possible wouldn't know which job will execute next in the context of this unfinished transaction. + +You can force transactions to rollback if they were not committed by overriding `afterExecute` method in the SQLiteQueue: +``` + SQLiteQueue queue = new SQLiteQueue(databaseFile) { + protected void afterExecute(SQLiteJob job) { + rollback(); + } + }; +``` + +### Extending Basic Implementation ### + +SQLiteQueue is written with possibility for extending in mind. If you need more functionality than is provided in the basic version, inspect the protected methods assortment and it may be possible to do what you need by overriding default implementation. \ No newline at end of file diff --git a/ProjectHome.md b/ProjectHome.md new file mode 100644 index 0000000..78f1de7 --- /dev/null +++ b/ProjectHome.md @@ -0,0 +1,50 @@ +**Download latest version:** + + * [sqlite4java-392](https://d1.almworks.com/.files/sqlite4java/sqlite4java-392.zip) with **SQLite 3.8.7**, Windows/Linux/Mac OS X/Android binaries + * [OSGi bundle 1.0.392](https://d1.almworks.com/.files/sqlite4java/com.almworks.sqlite4java-1.0.392.jar) with sqlite4java-392 + +Files for previous versions are available in the Downloads section. + + +--- + + +# About sqlite4java # + +sqlite4java is a minimalistic Java wrapper for SQLite. [SQLite](http://sqlite.org) is a free, compact, robust, embeddable SQL database engine. **sqlite4java** is built with the purpose to provide high-performance, low-garbage interface to SQLite for desktop Java applications. + +sqlite4java is not a JDBC driver. Access to the database is made through the custom interfaces of `com.almworks.sqlite4java` package. Tighter integration with SQLite offers better performance and features not available through JDBC interfaces. + +sqlite4java is built for use on Windows, Linux, Mac OS X and Android, although you can try to compile it on other platforms. Required JRE version is 1.5. SQLite is pre-compiled and distributed along with the Java classes as dynamic JNI libraries. + +sqlite4java is a stable library that we (ALM Works) use in our production applications. The API may not support some of the SQLite functions, but most functionality is covered. Feel free to request improvements or suggest patches. + + * [Getting Started](GettingStarted.md) + * [Comparison to Other Java Wrappers for SQLite](ComparisonToOtherWrappers.md) + * [Javadoc](http://almworks.com/sqlite4java/javadoc/index.html) + * [Using in a Maven 2 project](UsingWithMaven.md) + +# Supported Platforms # + + * Windows i386/x64 + * Linux i686/amd64 + * Mac OS X 10.5 or later (i686/x64) + * Android x86/armv7/armv5 + +# Features # + + * **Thin JNI-based wrapper** for SQLite C Interface. Most of SQLite's user functions (not extender functions) are either already provided by the library or can be easily added. + * **Single-threaded model** - each SQLite connection is confined to a single thread, all calls must come from that thread. Application may open several connections to the same database from different threads. Along with the Serializable isolation level from SQLite, this feature facilitates writing very clean and predictable code. + * **Bulk retrieval** from SELECT statements, greatly improving speed and garbage rate via minimizing the number of JNI calls to `step()` and `column...()` methods. See [SQLiteStatement.loadInts()](http://almworks.com/sqlite4java/javadoc/index.html) for example. + * **Interruptible statements** support allows to cancel a long-running query or update. See [SQLiteConnection.interrupt()](http://almworks.com/sqlite4java/javadoc/index.html). + * **Long array binding** allows to represent a `long[]` Java array as an SQL table. Table lookup is optimized if you specify that the array is sorted and/or has unique values. See [SQLiteLongArray](http://almworks.com/sqlite4java/javadoc/index.html). + * **Incremental BLOB I/O** maps to `sqlite3_blob...` methods, which provide means to read/write portions of a large BLOB. See [SQLiteBlob](http://almworks.com/sqlite4java/javadoc/index.html). + * **BLOBs as streams** - you can bind parameter as an `OutputStream` and read column value as `InputStream`. See [SQLiteStatement.bindStream()](http://almworks.com/sqlite4java/javadoc/index.html) for example. + * **Job queue implementation** lets you queue database jobs in a multi-threaded application, to be executed one-by-one in a dedicated database thread. See [JobQueue](JobQueue.md). + * **SQL Profiler** collects statistics on the executed SQL. + * **Backup API** support lets you use SQLite's hot backup feature. See [SQLiteConnection.initializeBackup()](http://almworks.com/sqlite4java/javadoc/index.html). + + +# License # + +**sqlite4java** is licensed under Apache License 2.0. Contact info@almworks.com if you'd like to have it licensed under different terms. \ No newline at end of file diff --git a/UsingWithMaven.md b/UsingWithMaven.md new file mode 100644 index 0000000..f3bcf2b --- /dev/null +++ b/UsingWithMaven.md @@ -0,0 +1,99 @@ +sqlite4java has a number of artifacts: the main artifact `com.almworks.sqlite4java:sqlite4java` is a jar file with Java classes, and one binary artifact for each target platform/architecture. You need to add dependency on the main artifact and at least one binary artifact. + +Furthermore, when sqlite4java initializes, it will not be able to automatically find binary artifacts in the Maven repository, so you either need to add goals to somehow place `sqlite4java-*.jar` in the same directory with `*.dll/*.so/*.jnilib` artifacts, or pass `sqlite4java.library.path` system property to the process using sqlite4java, or use `SQLite.setLibraryPath()` as the first method you call when working with sqlite4java. + +List of artifacts: +| **groupId** | **artifactId** | **type** | +|:------------|:---------------|:---------| +| com.almworks.sqlite4java | sqlite4java | jar | +| com.almworks.sqlite4java | libsqlite4java-linux-amd64 | so | +| com.almworks.sqlite4java | libsqlite4java-linux-i386 | so | +| com.almworks.sqlite4java | libsqlite4java-osx | jnilib | +| com.almworks.sqlite4java | libsqlite4java-osx-10.4 | jnilib | +| com.almworks.sqlite4java | libsqlite4java-osx-ppc | jnilib | +| com.almworks.sqlite4java | sqlite4java-win32-x64 | dll | +| com.almworks.sqlite4java | sqlite4java-win32-x86 | dll | + +Sample POM: +``` + + ... + + 1.0.392 + + + + + com.almworks.sqlite4java + sqlite4java + jar + ${sqlite4java.version} + + + com.almworks.sqlite4java + libsqlite4java-linux-i386 + so + ${sqlite4java.version} + + + + + + + org.apache.maven.plugins + maven-dependency-plugin + + + copy + compile + + copy + + + + + com.almworks.sqlite4java + libsqlite4java-linux-i386 + ${sqlite4java.version} + so + true + ${project.build.directory}/lib + + + + + + + + org.apache.maven.plugins + maven-surefire-plugin + + + + sqlite4java.library.path + ${project.build.directory}/lib + + + + + + org.codehaus.mojo + appassembler-maven-plugin + 1.0-alpha-2 + + + assemble + package + + assemble + + + -Dsqlite4java.library.path=lib + + + + + + + +``` \ No newline at end of file