root/XerialJ/trunk/sqlite-jdbc/sqlitejdbc/README

---------------------------------------------------------------------
What:  SQLite 3.3.x JDBC Driver
Who:   David Crawshaw <david@zentus.com>
When:  2006
Why:   Because Derby is bloated, HSQLDB has too many capital letters
       in its name and I don't have the time to maintain a full Java
       port of SQLite.
How:   BSD License (dig in)
---------------------------------------------------------------------


-- USING ------------------------------------------------------------
This driver comes in two flavours: Pure Java and native library. The
Pure Java driver works by running a MIPS version of SQLite inside the
JVM with NestedVM. To use, download sqlitejdbc-*version*-nested.tgz,
extract sqlitejdbc-*version*-nested.jar and include in the classpath
of your project. You can then invoke SQLite using the standard JDBC
interface:

    Class.forName("org.sqlite.JDBC");
    Connection conn = DriverManager.getConnection(
        "jdbc:sqlite:filename");
    // ... use the database ...
    conn.close();

The native library version is faster, but requires a platform and
operating system specific binary. Place the file
sqlitejdbc-*version*-native.jar on the classpath and the native
library sqlitejdbc.dll or libsqlitejdbc.jnilib on the Java library
path. To do this from the command line:

    java -cp sqlitejdbc.jar -Djava.library.path=. yourprog.Main

Alternatively, if you wish to load the native library at runtime,
set the system property "org.sqlite.lib.path" to the directory
containing the library. For bundling several binaries, the property
"org.sqlite.lib.name" can be used if the path property is set. This
is used as the name of the native library to load.

For a memory database, use a URL without a file name:
    Connection conn = DriverManager.getConnection("jdbc:sqlite:");


-- NOT YET IMPLEMENTED ----------------------------------------------
Most aspects of JDBC that are unsupported are done so because SQLite
doesn't lend itself that way, or I haven't got around to it yet.

- getBlob() / setBlob(): these functions require constantly creating
  instances of java.sql.Blob, which I do not like. The features of
  these functions, such as Stream access cannot be implemented
  efficiently on SQLite anyhow. The only thing that is important is
  retrieving the length of a blob without reading the contents into
  memory. I hope to provide non-JDBC access to this through the API
  mentioned for user-defined functions.
- ResultSet.isLast(): the only truly evil function in the JDBC spec.
  Even the JavaDoc's accept this:
     Calling the method isLast may be expensive because the JDBC
     driver might need to fetch ahead one row in order to determine
     whether the current row is the last row in the result set.

  Supporting this function would bring all the pain of determining
  types, terribly bloat the code and mean a performance hit. It
  will probably always throw an SQLException. Use next() instead.


-- COMPILING --------------------------------------------------------
Install gcc, gnu make, a JDK, set your $JAVA_HOME and type:
    $ make

On a Unix system, this should compile the driver for your
architecture and run the test suite. On cygwin you may be lucky and
only have to rename libsqlitejdbc.so to sqlitejdbc.dll, or other
problems may appear.

To pass the tests an sqlite binary is needed on the path.