lang/sql/jdbc/doc/overview.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN""http://www.w3.org/
   2 TR/REC-html40/loose.dtd>
   3 <!--NewPage-->
   4 <HTML>
   5 <HEAD>
   6 <TITLE>
   7 SQLite Java Wrapper/JDBC Driver
   8 </TITLE>
   9 </HEAD>
  10 <LINK REL="stylesheet" TYPE="text/css" HREF="stylesheet.css" TITLE="Style">
  11 <BODY BGCOLOR="white">
  12
  13 <A NAME="overview_description">
  14 This is a Java wrapper including a basic JDBC driver
  15 for the <A HREF="http://www.sqlite.org" TARGET="_blank">
  16 SQLite 2/3 database engine</A>.
  17 It is designed using JNI to interface to the SQLite API. That
  18 API is wrapped by methods in the <A HREF="SQLite/Database.html">
  19 SQLite.Database</A> class.
  20 Since June, 2002, it includes a small <A HREF="#jdbc_driver">JDBC driver</A>,
  21 which allows the most basic things to be carried out using the
  22 <TT>java.sql</TT> package.
  23 Since September, 2004, SQLite3 (minimum 3.0.7) is supported. The JNI part can
  24 be generated to include support for both SQLite 2.x and 3.x and detects at
  25 runtime the type of the database.
  26 <P>
  27 The current source tarball can be downloaded from
  28 <A HREF="http://www.ch-werner.de/javasqlite/javasqlite-20120209.tar.gz">
  29 javasqlite-20120209.tar.gz</A>.
  30 It has been tested on Linux, using SQLite 2.8.17 and 3.7.9,
  31 and JDK 1.4/1.5/1.6 from
  32 <A HREF="http://java.sun.com" TARGET="_blank">Sun</A>.
  33 The change log starting from August 2007 is <A HREF="ChangeLog">here</A>.
  34 <P>
  35
  36 For rebuilding the following requirements must be met:
  37 <UL>
  38 <LI TYPE="circle">SQLite 2.4.12 or higher
  39 <LI TYPE="circle">JDK 1.1 or higher
  40 <LI TYPE="circle">C compiler and make
  41 </UL>
  42 The source code uses GNU autoconf, thus the build process on UN*X like
  43 systems should look like:
  44 <P>
  45 <PRE>
  46    $ ./configure
  47    ...
  48    $ make
  49    ...
  50    $ su -c "make install"
  51    ...
  52 </PRE>
  53 <P>
  54 To override the directory where configure looks for SQLite and JDK the
  55 configure options <TT>--with-sqlite=DIR</TT>, <TT>--with-sqlite3=DIR</TT>,
  56 and <TT>--with-jdk=DIR</TT> can be used. To specify the place where the
  57 native library (the <TT>libsqlite_jni.so</TT> file) shall be
  58 installed, use the <TT>--prefix=DIR</TT> option. The default place is
  59 <TT>/usr/local/lib</TT>, i.e. the prefix defaults to <TT>/usr/local</TT>.
  60 To specify where the <TT>sqlite.jar</TT> file containing the high-level
  61 part and the JDBC driver shall be
  62 installed, use the <TT>--with-jardir=DIR</TT> option. The default is
  63 <TT>/usr/local/share/java</TT>.
  64 At runtime, it is necessary to tell the JVM both places with
  65 the <TT>-classpath</TT> and <TT>-Djava.library.path=..</TT>
  66 command line options. Optionally, the native part is searched
  67 using the path prefix specified in the <TT>-DSQLite.library.path=..</TT>
  68 property, which has precedence over <TT>-Djava.library.path=..</TT>.
  69 <P>
  70 For Win32 (NT4 or above) the makefiles <TT>javasqlite.mak</TT>,
  71 <TT>javasqlite23.mak</TT>, and <TT>javasqlite3.mak</TT> are provided
  72 in the source archive. These makefiles contain some build
  73 instructions and use the J2SE 1.4.2 from Sun and MS Visual C++ 6.0.
  74 <P>
  75 A DLL with the native JNI part (including SQLite 3.7.7.1)
  76 and the JAR file with the Java part can be downloaded from
  77 <A HREF="http://www.ch-werner.de/javasqlite/javasqlite-20110827-win32.zip">
  78 javasqlite-20110827-win32.zip</A>.
  79 <P>
  80 After successful build and installation a small
  81 <A HREF="test.java">test program</A> can be run by invoking the
  82 following commands (on OJEC replace the <TT>java</TT> command by
  83 <TT>cvm</TT>):
  84 <P>
  85 <PRE>
  86    $ make test
  87    ...
  88    $ java -classpath ... -Djava.library.path=... test
  89    version: 2.8.17
  90    ==== local callback ====
  91    #cols = 5
  92    col0: type
  93    col1: name
  94    ...
  95 </PRE>
  96 <P>
  97 For testing the newer features of SQLite3 (parameter binding with
  98 the help of the <A HREF="SQLite/Stmt.html">SQLite.Stmt</A> class
  99 and incremental blob I/O through <A HREF="SQLite/Blob.html">SQLite.Blob</A>
 100 class) refer to another <A HREF="test3.java">test program</A>.
 101 <P>
 102 A simple shell modelled after that of SQLite can be invoked as
 103 (on OJEC replace the <TT>java</TT> command by <TT>cvm</TT>):
 104 <PRE>
 105    $ java SQLite.Shell [options] database [sql string]
 106 </PRE>
 107 or using the JAR file
 108 <PRE>
 109    $ java -jar sqlite.jar [options] database [sql string]
 110 </PRE>
 111 <P>
 112 The native part of the Java SQLite wrapper takes the compile-time
 113 character encoding of the SQLite engine into account, and tries to
 114 map the Java unicode string representation into the system encoding
 115 and vice versa when SQLite has not been built with UTF-8 support.
 116 This can be overriden programatically or by specifying the
 117 <TT>-DSQLite.encoding=x</TT> command line option to the Java
 118 runtime, where <TT>x</TT> must be a charset name recognized
 119 by your Java environment. If the SQLite engine supports UTF-8,
 120 no special options are needed.
 121 <P>
 122 <A NAME="jdbc_driver">
 123 If you like to try the JDBC driver, use <TT>SQLite.JDBCDriver</TT>
 124 as the JDBC drivers's class name. Make sure that you have the
 125 <TT>sqlite.jar</TT> in your class path and the native
 126 library in your java library path. The JDBC URLs to connect to
 127 an SQLite database have the format <TT>jdbc:sqlite:/path</TT>,
 128 where <TT>path</TT> has to be specified as the path
 129 name to the SQLite database, for example
 130 <PRE>
 131     jdbc:sqlite://dirA/dirB/dbfile
 132     jdbc:sqlite:/DRIVE:/dirA/dirB/dbfile
 133     jdbc:sqlite:///COMPUTERNAME/shareA/dirB/dbfile
 134 </PRE>
 135 In order to deal with SQLite's in-memory databases, use a
 136 JDBC URL with this format:
 137 <PRE>
 138     jdbc:sqlite:/:memory:
 139 </PRE>
 140 For now, the only data types
 141 supported on SQLite tables are <TT>java.lang.String</TT>,
 142 <TT>short</TT>, <TT>int</TT>, <TT>float</TT>, and <TT>double</TT>.
 143
 144 The encoding of SQLite2 databases can be set per
 145 JDBC connection using the connect property <TT>encoding</TT>
 146 when creating the connection.
 147
 148 Partial support exists for <TT>java.sql.Date</TT>,
 149 <TT>java.sql.Time</TT>, and <TT>java.sql.Timestamp</TT>.
 150 For SQLite3 engines the connect property <TT>daterepr</TT>
 151 determines, how date/time/timestamp data is interpreted.
 152 If set to <TT>daterepr=julian</TT>, on INSERT/UPDATE these
 153 datatypes are converted to a floating point number
 154 expressing a julian day number as described in the
 155 <A href="http://www.sqlite.org/cvstrac/wiki?p=DateAndTimeFunctions" TARGET="_blank">
 156 SQLite Wiki</A>. On retrieval (SELECT), the floating point
 157 representation is preferred. All other values of the <TT>daterepr</TT>
 158 property use the string formats <TT>YYYY-mm-dd</TT> for date,
 159 <TT>HH:MM:SS</TT> for time, and <TT>YYYY-mm-dd HH:MM:SS.f</TT>
 160 for timestamp.
 161
 162 The data type mapping depends mostly on the availability of
 163 the SQLite <TT>PRAGMAs</TT> <TT>show_datatypes</TT> and <TT>table_info</TT>.
 164 Most basic database meta data methods are implemented,
 165 thus enough information is available to access SQLite
 166 databases with JDK >= 1.3 and the
 167 <A HREF="http://www.isqlviewer.com" TARGET="_blank">ISQLViewer</A>
 168 tool.
 169 <P>
 170 A JDBC based benchmark program is built into <TT>sqlite.jar</TT>.
 171 If using a non OJEC version of Java it can be invoked by
 172 <PRE>
 173    $ java -cp sqlite.jar SQLite.BenchmarkDriver ...
 174 </PRE>
 175 If using an OJEC version of Java it can be invoked by
 176 <PRE>
 177    $ cvm -cp sqlite.jar SQLite.BenchmarkDataSource ...
 178 </PRE>
 179 For further details see the usage information when invoked without
 180 arguments and consult the source code.
 181 <P>
 182 Other useful information to make this package work on
 183 ARM Linux can be found in
 184 <A HREF="http://www.kecher.de/howtos/SQLite-JDBC-Howto.html" TARGET="_blank">
 185 How To compile SQLite with JDBC for the iPAQ</A>.
 186 <P>
 187 Tim Anderson has some notes on compiling in his
 188 <A HREF="http://www.itwriting.com/sqlitenotes.php" TARGET="_blank">sqlitenotes</A>.
 189 <P>
 190 Stanislaw Ciszewski had also success on MacOSX, see his
 191 <A HREF="scnotes.txt">remarks here</A>.
 192 <P>
 193 Anton Johansson wrote a <A HREF="ajhowto.txt">howto</A> compile
 194 SQLite Java Wrapper for Windows, thanks Anton!
 195 <P>
 196 To find out the SQLite.Database instance of a JDBC connection,
 197 that code snippet can serve as a starting point:
 198 <PRE>
 199  Connection conn = null;
 200  SQLite.Database db = null;
 201  try {
 202    Class.forName("SQLite.JDBCDriver").newInstance();
 203    conn = DriverManager.getConnection("jdbc:sqlite:/blabla");
 204    java.lang.reflect.Method m =
 205      conn.getClass().getMethod("getSQLiteDatabase", null);
 206    db = (SQLite.Database) m.invoke(conn, null);
 207  } catch (Exception e) {
 208  }
 209 </PRE>
 210 <P>
 211 This software and accompanying documentation is released under
 212 a BSD-style license:
 213 <P>
 214 <TABLE ALIGN="center"BORDER="0" CELLPADDING="0" CELLSPACING="3">
 215 <TR><TD BGCOLOR="EEEEEE">
 216 <PRE>
 217 This software is copyrighted by Christian Werner &lt;chw@ch-werner.de&gt;
 218 and others. The following terms apply to all files associated with the
 219 software unless explicitly disclaimed in individual files.
 220
 221 The authors hereby grant permission to use, copy, modify, distribute,
 222 and license this software and its documentation for any purpose, provided
 223 that existing copyright notices are retained in all copies and that this
 224 notice is included verbatim in any distributions. No written agreement,
 225 license, or royalty fee is required for any of the authorized uses.
 226 Modifications to this software may be copyrighted by their authors
 227 and need not follow the licensing terms described here, provided that
 228 the new terms are clearly indicated on the first page of each file where
 229 they apply.
 230
 231 IN NO EVENT SHALL THE AUTHORS OR DISTRIBUTORS BE LIABLE TO ANY PARTY
 232 FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
 233 ARISING OUT OF THE USE OF THIS SOFTWARE, ITS DOCUMENTATION, OR ANY
 234 DERIVATIVES THEREOF, EVEN IF THE AUTHORS HAVE BEEN ADVISED OF THE
 235 POSSIBILITY OF SUCH DAMAGE.
 236
 237 THE AUTHORS AND DISTRIBUTORS SPECIFICALLY DISCLAIM ANY WARRANTIES,
 238 INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY,
 239 FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT.  THIS SOFTWARE
 240 IS PROVIDED ON AN "AS IS" BASIS, AND THE AUTHORS AND DISTRIBUTORS HAVE
 241 NO OBLIGATION TO PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR
 242 MODIFICATIONS.
 243 </PRE>
 244 </TD></TR>
 245 </TABLE>
 246
 247 </BODY>
 248 </HTML>