greg/libdb
1
0
Fork 0
mirror of https://github.com/berkeleydb/libdb.git synced 2024-11-17 01:26:25 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions
libdb/lang/sql/jdbc/doc/overview-summary.html

390 lines
14 KiB
HTML
Raw Normal View History

Release 5.2.28 on 6/10/2011
2011-09-13 17:44:24 +00:00
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<!--NewPage-->
<HTML>
<HEAD>
<!-- Generated by javadoc (build 1.4.2_03) on Sat Apr 30 14:01:26 CEST 2011 -->
<TITLE>
Overview (SQLite Java Wrapper)
</TITLE>
<META NAME="keywords" CONTENT="Overview, SQLite Java Wrapper/JDBC Driver
<br><small>
2011-04-30
</small>">
<LINK REL ="stylesheet" TYPE="text/css" HREF="stylesheet.css" TITLE="Style">
<SCRIPT type="text/javascript">
function windowTitle()
{
parent.document.title="Overview (SQLite Java Wrapper)";
}
</SCRIPT>
</HEAD>
<BODY BGCOLOR="white" onload="windowTitle();">
<!-- ========= START OF TOP NAVBAR ======= -->
<A NAME="navbar_top"><!-- --></A>
<A HREF="#skip-navbar_top" title="Skip navigation links"></A>
<TABLE BORDER="0" WIDTH="100%" CELLPADDING="1" CELLSPACING="0" SUMMARY="">
<TR>
<TD COLSPAN=3 BGCOLOR="#EEEEFF" CLASS="NavBarCell1">
<A NAME="navbar_top_firstrow"><!-- --></A>
<TABLE BORDER="0" CELLPADDING="0" CELLSPACING="3" SUMMARY="">
<TR ALIGN="center" VALIGN="top">
<TD BGCOLOR="#FFFFFF" CLASS="NavBarCell1Rev"> &nbsp;<FONT CLASS="NavBarFont1Rev"><B>Overview</B></FONT>&nbsp;</TD>
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <FONT CLASS="NavBarFont1">Package</FONT>&nbsp;</TD>
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <FONT CLASS="NavBarFont1">Class</FONT>&nbsp;</TD>
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="overview-tree.html"><FONT CLASS="NavBarFont1"><B>Tree</B></FONT></A>&nbsp;</TD>
</TR>
</TABLE>
</TD>
<TD ALIGN="right" VALIGN="top" ROWSPAN=3><EM>
</EM>
</TD>
</TR>
<TR>
<TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2">
&nbsp;PREV&nbsp;
&nbsp;NEXT</FONT></TD>
<TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2">
<A HREF="index.html" target="_top"><B>FRAMES</B></A> &nbsp;
&nbsp;<A HREF="overview-summary.html" target="_top"><B>NO FRAMES</B></A> &nbsp;
&nbsp;<SCRIPT type="text/javascript">
<!--
if(window==top) {
document.writeln('<A HREF="allclasses-noframe.html"><B>All Classes</B></A>');
}
//-->
</SCRIPT>
<NOSCRIPT>
<A HREF="allclasses-noframe.html"><B>All Classes</B></A>
</NOSCRIPT>
</FONT></TD>
</TR>
</TABLE>
<A NAME="skip-navbar_top"></A>
<!-- ========= END OF TOP NAVBAR ========= -->
<HR>
<CENTER>
<H1>
SQLite Java Wrapper/JDBC Driver
<br><small>
2011-04-30
</small>
</H1>
</CENTER>
<A NAME="overview_description">
This is a Java wrapper including a basic JDBC driver
for the <A HREF="http://www.sqlite.org" TARGET="_blank">
SQLite 2/3 database engine</A>.
<P>
<B>See:</B>
<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<A HREF="#overview_description"><B>Description</B></A>
<P>
<TABLE BORDER="1" WIDTH="100%" CELLPADDING="3" CELLSPACING="0" SUMMARY="">
<TR BGCOLOR="#CCCCFF" CLASS="TableHeadingColor">
<TD COLSPAN=2><FONT SIZE="+2">
<B>Packages</B></FONT></TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD WIDTH="20%"><B><A HREF="SQLite/package-summary.html">SQLite</A></B></TD>
<TD>&nbsp;</TD>
</TR>
</TABLE>
<P>
&nbsp;<A NAME="overview_description"><!-- --></A>
<P>
<A NAME="overview_description">
This is a Java wrapper including a basic JDBC driver
for the <A HREF="http://www.sqlite.org" TARGET="_blank">
SQLite 2/3 database engine</A>.
It is designed using JNI to interface to the SQLite API. That
API is wrapped by methods in the <A HREF="SQLite/Database.html">
SQLite.Database</A> class.
Since June, 2002, it includes a small <A HREF="#jdbc_driver">JDBC driver</A>,
which allows the most basic things to be carried out using the
<TT>java.sql</TT> package.
Since September, 2004, SQLite3 (minimum 3.0.7) is supported which
is rather experimental. The JNI part can be generated to include support
for both SQLite 2.x and 3.x and detects at runtime the type of the
database.
<P>
The current source tarball can be downloaded from
<A HREF="http://www.ch-werner.de/javasqlite/javasqlite-20110430.tar.gz">
javasqlite-20110430.tar.gz</A>.
It has been tested on Linux, using SQLite 2.8.17 and 3.7.0,
and JDK 1.4/1.5/1.6 from
<A HREF="http://java.sun.com" TARGET="_blank">Sun</A>.
The change log starting from August 2007 is <A HREF="ChangeLog">here</A>.
<P>
For rebuilding the following requirements must be met:
<UL>
<LI TYPE="circle">SQLite 2.4.12 or higher
<LI TYPE="circle">JDK 1.1 or higher
<LI TYPE="circle">C compiler and make
</UL>
The source code uses GNU autoconf, thus the build process on UN*X like
systems should look like:
<P>
<PRE>
$ ./configure
...
$ make
...
$ su -c "make install"
...
</PRE>
<P>
To override the directory where configure looks for SQLite and JDK the
configure options <TT>--with-sqlite=DIR</TT>, <TT>--with-sqlite3=DIR</TT>,
and <TT>--with-jdk=DIR</TT> can be used. To specify the place where the
native library (the <TT>libsqlite_jni.so</TT> file) shall be
installed, use the <TT>--prefix=DIR</TT> option. The default place is
<TT>/usr/local/lib</TT>, i.e. the prefix defaults to <TT>/usr/local</TT>.
To specify where the <TT>sqlite.jar</TT> file containing the high-level
part and the JDBC driver shall be
installed, use the <TT>--with-jardir=DIR</TT> option. The default is
<TT>/usr/local/share/java</TT>.
At runtime, it is necessary to tell the JVM both places with
the <TT>-classpath</TT> and <TT>-Djava.library.path=..</TT>
command line options. Optionally, the native part is searched
using the path prefix specified in the <TT>-DSQLite.library.path=..</TT>
property, which has precedence over <TT>-Djava.library.path=..</TT>.
<P>
For Win32 (NT4 or above) the makefiles <TT>javasqlite.mak</TT>,
<TT>javasqlite23.mak</TT>, and <TT>javasqlite3.mak</TT> are provided
in the source archive. These makefiles contain some build
instructions and use the J2SE 1.4.2 from Sun and MS Visual C++ 6.0.
<P>
A DLL with the native JNI part (including SQLite 3.7.6.2)
and the JAR file with the Java part can be downloaded from
<A HREF="http://www.ch-werner.de/javasqlite/javasqlite-20110430-win32.zip">
javasqlite-20110430-win32.zip</A>.
<P>
After successful build and installation a small
<A HREF="test.java">test program</A> can be run by invoking the
following commands:
<P>
<PRE>
$ make test
...
$ java -classpath ... -Djava.library.path=... test
version: 2.8.17
==== local callback ====
#cols = 5
col0: type
col1: name
...
</PRE>
<P>
For testing the newer features of SQLite3 (parameter binding with
the help of the <A HREF="SQLite/Stmt.html">SQLite.Stmt</A> class
and incremental blob I/O through <A HREF="SQLite/Blob.html">SQLite.Blob</A>
class) refer to another <A HREF="test3.java">test program</A>.
<P>
A simple shell modelled after that of SQLite can be invoked as
<PRE>
$ java SQLite.Shell [options] database [sql string]
</PRE>
or using the JAR file
<PRE>
$ java -jar sqlite.jar [options] database [sql string]
</PRE>
<P>
The native part of the Java SQLite wrapper takes the compile-time
character encoding of the SQLite engine into account, and tries to
map the Java unicode string representation into the system encoding
and vice versa when SQLite has not been built with UTF-8 support.
This can be overriden programatically or by specifying the
<TT>-DSQLite.encoding=x</TT> command line option to the Java
runtime, where <TT>x</TT> must be a charset name recognized
by your Java environment. If the SQLite engine supports UTF-8,
no special options are needed.
<P>
<A NAME="jdbc_driver">
If you like to try the JDBC driver, use <TT>SQLite.JDBCDriver</TT>
as the JDBC drivers's class name. Make sure that you have the
<TT>sqlite.jar</TT> in your class path and the native
library in your java library path. The JDBC URLs to connect to
an SQLite database have the format <TT>jdbc:sqlite:/path</TT>,
where <TT>path</TT> has to be specified as the path
name to the SQLite database, for example
<PRE>
jdbc:sqlite://dirA/dirB/dbfile
jdbc:sqlite:/DRIVE:/dirA/dirB/dbfile
jdbc:sqlite:///COMPUTERNAME/shareA/dirB/dbfile
</PRE>
In order to deal with SQLite's in-memory databases, use a
JDBC URL with this format:
<PRE>
jdbc:sqlite:/:memory:
</PRE>
For now, the only data types
supported on SQLite tables are <TT>java.lang.String</TT>,
<TT>short</TT>, <TT>int</TT>, <TT>float</TT>, and <TT>double</TT>.
The encoding of SQLite2 databases can be set per
JDBC connection using the connect property <TT>encoding</TT>
when creating the connection.
Partial support exists for <TT>java.sql.Date</TT>,
<TT>java.sql.Time</TT>, and <TT>java.sql.Timestamp</TT>.
For SQLite3 engines the connect property <TT>daterepr</TT>
determines, how date/time/timestamp data is interpreted.
If set to <TT>daterepr=julian</TT>, on INSERT/UPDATE these
datatypes are converted to a floating point number
expressing a julian day number as described in the
<A href="http://www.sqlite.org/cvstrac/wiki?p=DateAndTimeFunctions">
SQLite Wiki</A>. On retrieval (SELECT), the floating point
representation is preferred. All other values of the <TT>daterepr</TT>
property use the string formats <TT>YYYY-mm-dd</TT> for date,
<TT>HH:MM:SS</TT> for time, and <TT>YYYY-mm-dd HH:MM:SS.f</TT>
for timestamp.
The data type mapping depends mostly on the availability of
the SQLite <TT>PRAGMAs</TT> <TT>show_datatypes</TT> and <TT>table_info</TT>.
Most basic database meta data methods are implemented,
thus enough information is available to access SQLite
databases with JDK >= 1.3 and the
<A HREF="http://www.isqlviewer.com" TARGET="_blank">ISQLViewer</A>
tool.
<P>
A JDBC based benchmark program is built into <TT>sqlite.jar</TT>.
It can be invoked by
<PRE>
$ java -cp sqlite.jar SQLite.Benchmark ...
</PRE>
For further details see the usage information when invoked without
arguments and consult the source code.
<P>
Other useful information to make this package work on
ARM Linux can be found in
<A HREF="http://www.kecher.de/howtos/SQLite-JDBC-Howto.html" TARGET="_blank">
How To compile SQLite with JDBC for the iPAQ</A>.
<P>
Tim Anderson has some notes on compiling in his
<A HREF="http://www.itwriting.com/sqlitenotes.php">sqlitenotes</A>.
<P>
Stanislaw Ciszewski had also success on MacOSX, see his
<A HREF="scnotes.txt">remarks here</A>.
<P>
Anton Johansson wrote a <A HREF="ajhowto.txt">howto</A> compile
SQLite Java Wrapper for Windows, thanks Anton!
<P>
To find out the SQLite.Database instance of a JDBC connection,
that code snippet can serve as a starting point:
<PRE>
Connection conn = null;
SQLite.Database db = null;
try {
Class.forName("SQLite.JDBCDriver").newInstance();
conn = DriverManager.getConnection("jdbc:sqlite:/blabla");
java.lang.reflect.Method m =
conn.getClass().getMethod("getSQLiteDatabase", null);
db = (SQLite.Database) m.invoke(conn, null);
} catch (Exception e) {
}
</PRE>
<P>
This software and accompanying documentation is released under
a BSD-style license:
<P>
<TABLE ALIGN="center"BORDER="0" CELLPADDING="0" CELLSPACING="3">
<TR><TD BGCOLOR="EEEEEE">
<PRE>
This software is copyrighted by Christian Werner &lt;chw@ch-werner.de&gt;
and others. The following terms apply to all files associated with the
software unless explicitly disclaimed in individual files.
The authors hereby grant permission to use, copy, modify, distribute,
and license this software and its documentation for any purpose, provided
that existing copyright notices are retained in all copies and that this
notice is included verbatim in any distributions. No written agreement,
license, or royalty fee is required for any of the authorized uses.
Modifications to this software may be copyrighted by their authors
and need not follow the licensing terms described here, provided that
the new terms are clearly indicated on the first page of each file where
they apply.
IN NO EVENT SHALL THE AUTHORS OR DISTRIBUTORS BE LIABLE TO ANY PARTY
FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
ARISING OUT OF THE USE OF THIS SOFTWARE, ITS DOCUMENTATION, OR ANY
DERIVATIVES THEREOF, EVEN IF THE AUTHORS HAVE BEEN ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.
THE AUTHORS AND DISTRIBUTORS SPECIFICALLY DISCLAIM ANY WARRANTIES,
INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT. THIS SOFTWARE
IS PROVIDED ON AN "AS IS" BASIS, AND THE AUTHORS AND DISTRIBUTORS HAVE
NO OBLIGATION TO PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR
MODIFICATIONS.
</PRE>
</TD></TR>
</TABLE>
<P>
<P>
<HR>
<!-- ======= START OF BOTTOM NAVBAR ====== -->
<A NAME="navbar_bottom"><!-- --></A>
<A HREF="#skip-navbar_bottom" title="Skip navigation links"></A>
<TABLE BORDER="0" WIDTH="100%" CELLPADDING="1" CELLSPACING="0" SUMMARY="">
<TR>
<TD COLSPAN=3 BGCOLOR="#EEEEFF" CLASS="NavBarCell1">
<A NAME="navbar_bottom_firstrow"><!-- --></A>
<TABLE BORDER="0" CELLPADDING="0" CELLSPACING="3" SUMMARY="">
<TR ALIGN="center" VALIGN="top">
<TD BGCOLOR="#FFFFFF" CLASS="NavBarCell1Rev"> &nbsp;<FONT CLASS="NavBarFont1Rev"><B>Overview</B></FONT>&nbsp;</TD>
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <FONT CLASS="NavBarFont1">Package</FONT>&nbsp;</TD>
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <FONT CLASS="NavBarFont1">Class</FONT>&nbsp;</TD>
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="overview-tree.html"><FONT CLASS="NavBarFont1"><B>Tree</B></FONT></A>&nbsp;</TD>
</TR>
</TABLE>
</TD>
<TD ALIGN="right" VALIGN="top" ROWSPAN=3><EM>
</EM>
</TD>
</TR>
<TR>
<TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2">
&nbsp;PREV&nbsp;
&nbsp;NEXT</FONT></TD>
<TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2">
<A HREF="index.html" target="_top"><B>FRAMES</B></A> &nbsp;
&nbsp;<A HREF="overview-summary.html" target="_top"><B>NO FRAMES</B></A> &nbsp;
&nbsp;<SCRIPT type="text/javascript">
<!--
if(window==top) {
document.writeln('<A HREF="allclasses-noframe.html"><B>All Classes</B></A>');
}
//-->
</SCRIPT>
<NOSCRIPT>
<A HREF="allclasses-noframe.html"><B>All Classes</B></A>
</NOSCRIPT>
</FONT></TD>
</TR>
</TABLE>
<A NAME="skip-navbar_bottom"></A>
<!-- ======== END OF BOTTOM NAVBAR ======= -->
<HR>
<small>Contact: <a HREF="mailto:chw@ch-werner.de">Christian Werner</a></small>
</BODY>
</HTML>
Reference in a new issue Copy permalink