com.almworks.sqlite4java
Class SQLite

java.lang.Object
  com.almworks.sqlite4java.SQLite

public final class SQLite
extends java.lang.Object

SQLite class has several utility methods that are applicable to the whole instance of SQLite library within the current process. It is not needed for basic operations.

All methods in this class are thread-safe.

Author:

Igor Sereda

Field Summary

static java.lang.String

LIBRARY_PATH_PROPERTY System property that, if set, defines where to look for native sqlite4java libraries.

Method Summary

static java.lang.String	getLibraryVersion() Gets the version of sqlite4java library.
static long	getMemoryHighwater(boolean reset) Returns the maximum amount of memory that was used by SQLite since the last time the highwater was reset.
static long	getMemoryUsed() Gets the amount of memory currently used by SQLite library.
static java.lang.String	getSQLiteCompileOptions() Gets the compile-time options used to compile the used library.
static java.lang.String	getSQLiteVersion() Gets the version of SQLite database.
static int	getSQLiteVersionNumber() Gets the numeric representation of the SQLite version.
static boolean	isComplete(java.lang.String sql) Checks if the given SQL is complete.
static boolean	isDebugBinaryPreferred() Used to check whether DEBUG binary is preferred over RELEASE binary when SQLite native code is loaded.
static boolean	isThreadSafe() Checks if SQLite has been compiled with the THREADSAFE option.
static void	loadLibrary() Tries to load the native library.
static void	main(java.lang.String[] args) Main method is called when you run java -jar sqlite4java.jar, and it prints out the version of the library, the version of the SQLite and the compile-time options the binaries were built with
static int	releaseMemory(int bytes) Requests SQLite to try to release some memory from its heap.
static void	setDebugBinaryPreferred(boolean debug) Native sqlite4java code, including SQLite itself, is compiled in DEBUG and RELEASE configurations.
static void	setLibraryPath(java.lang.String path) Sets the path where sqlite4java should look for the native library, by modifying sqlite4java.library.path system property.
static void	setSharedCache(boolean enabled) Sets whether shared cache mode will be used for the connections that are opened after this call.
static void	setSoftHeapLimit(int limit) Sets the "soft limit" on the amount of memory allocated before SQLite starts trying to free some memory before allocating more memory.
static long	softHeapLimit(long limit) Sets the "soft limit" on the amount of memory allocated before SQLite starts trying to free some memory before allocating more memory.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

LIBRARY_PATH_PROPERTY

public static final java.lang.String LIBRARY_PATH_PROPERTY

System property that, if set, defines where to look for native sqlite4java libraries.

See Also:

Constant Field Values

Method Detail

setDebugBinaryPreferred

public static void setDebugBinaryPreferred(boolean debug)

Native sqlite4java code, including SQLite itself, is compiled in DEBUG and RELEASE configurations. Binaries compiled with debug configurations have -d suffix, and can be placed in the same directory with release binaries.

sqlite4java will load any available binary that suits the platform, but in case both RELEASE and DEBUG binaries are available, it will load RELEASE binary by default.

You can use this method to change the preference and load DEBUG binary by default.

This method must be called before the first call to SQLiteConnection.open(boolean) or any other methods that require library loading.

You can also change the default by setting sqlite4java.debug.binary.preferred system property to true.

Parameters:

debug - if true, choose DEBUG binary in case both DEBUG and RELEASE binaries are available

isDebugBinaryPreferred

public static boolean isDebugBinaryPreferred()

Used to check whether DEBUG binary is preferred over RELEASE binary when SQLite native code is loaded.

Returns:

true if DEBUG library is preferred

See Also:

setDebugBinaryPreferred(boolean)

loadLibrary

public static void loadLibrary()
                        throws SQLiteException

Tries to load the native library. If unsuccessful, throws an exception, otherwise just exits.

If native library is already loaded, just exits.

Throws:

SQLiteException - if library loading fails

getSQLiteVersion

public static java.lang.String getSQLiteVersion()
                                         throws SQLiteException

Gets the version of SQLite database.

Returns:

SQLite version

Throws:

SQLiteException - if native library cannot be loaded

See Also:

sqlite3_libversion

getSQLiteCompileOptions

public static java.lang.String getSQLiteCompileOptions()
                                                throws SQLiteException

Gets the compile-time options used to compile the used library.

Returns:

a string with all compile-time options delimited by a space

Throws:

SQLiteException - if native library cannot be loaded

See Also:

sqlite3_compileoption_get

getSQLiteVersionNumber

public static int getSQLiteVersionNumber()
                                  throws SQLiteException

Gets the numeric representation of the SQLite version.

Returns:

a number representing the version; example: version "3.6.23.1" is represented as 3006023.

Throws:

SQLiteException - if native library cannot be loaded

See Also:

sqlite3_version

isThreadSafe

public static boolean isThreadSafe()
                            throws SQLiteException

Checks if SQLite has been compiled with the THREADSAFE option.

Returns:

true if SQLite has been compiled with THREADSAFE option

Throws:

SQLiteException - if native library cannot be loaded

See Also:

sqlite3_threadsafe

isComplete

public static boolean isComplete(java.lang.String sql)
                          throws SQLiteException

Checks if the given SQL is complete.

Parameters:

sql - the SQL

Returns:

true if sql is a complete statement

Throws:

SQLiteException - if native library cannot be loaded

See Also:

sqlite3_complete

getMemoryUsed

public static long getMemoryUsed()
                          throws SQLiteException

Gets the amount of memory currently used by SQLite library. The returned value shows the amount of non-heap "native" memory taken up by SQLite caches and anything else allocated with sqlite3_malloc.

This value does not include any heap or other JVM-allocated memory taken up by sqlite4java objects and classes.

Returns:

the number of bytes used by SQLite library in this process (for all connections)

Throws:

SQLiteException - if native library cannot be loaded

See Also:

sqlite3_memory_used

getMemoryHighwater

public static long getMemoryHighwater(boolean reset)
                               throws SQLiteException

Returns the maximum amount of memory that was used by SQLite since the last time the highwater was reset.

Parameters:

reset - if true, the highwatermark is reset after this call

Returns:

the maximum number of bytes ever used by SQLite library since the start of the application or the last reset of the highwatermark.

Throws:

SQLiteException - if native library cannot be loaded

See Also:

sqlite3_memory_highwater

releaseMemory

public static int releaseMemory(int bytes)
                         throws SQLiteException

Requests SQLite to try to release some memory from its heap. This could be called to clear cache.

Parameters:

bytes - the number of bytes requested to be released

Returns:

the number of bytes actually released

Throws:

SQLiteException - if native library cannot be loaded

See Also:

sqlite3_release_memory

setSoftHeapLimit

public static void setSoftHeapLimit(int limit)
                             throws SQLiteException

Sets the "soft limit" on the amount of memory allocated before SQLite starts trying to free some memory before allocating more memory.

Parameters:

limit - the number of bytes to set the soft memory limit to

Throws:

SQLiteException - if native library cannot be loaded

See Also:

sqlite3_soft_heap_limit

softHeapLimit

public static long softHeapLimit(long limit)
                          throws SQLiteException

Sets the "soft limit" on the amount of memory allocated before SQLite starts trying to free some memory before allocating more memory.

Parameters:

limit - the number of bytes to set the soft memory limit to

Returns:

size of the soft heap limit prior to the call

Throws:

SQLiteException - if native library cannot be loaded

See Also:

sqlite3_soft_heap_limit64

setSharedCache

public static void setSharedCache(boolean enabled)
                           throws SQLiteException

Sets whether shared cache mode will be used for the connections that are opened after this call. All existing connections are not affected.

sqlite4java explicitly disables shared cache on start. This is also the default declared by SQLite, but it may change in the future, so sqlite4java enforces consistency.

Parameters:

enabled - if true, the following calls to SQLiteConnection.open(boolean) will used shared-cache mode

Throws:

SQLiteException - if native library cannot be loaded, or if call returns an error

See Also:

sqlite3_enable_shared_cache

getLibraryVersion

public static java.lang.String getLibraryVersion()

Gets the version of sqlite4java library. The library version equals to the svn version of the sources it's built from (trunk code only). If the version ends in '+', then the library has been built from dirty (uncommitted) sources.

The version string is read from the sqlite4java.jar's manifest.

Returns:

sqlite4java version, or null if version cannot be read

setLibraryPath

public static void setLibraryPath(java.lang.String path)

Sets the path where sqlite4java should look for the native library, by modifying sqlite4java.library.path system property.

By default, sqlite4java looks for native libraries in the same directory where sqlite4java.jar is located, and it also tries to use System.loadLibrary(java.lang.String) method, which uses java.library.path system property.

Use this method (or explicitly set sqlite4java.library.path) system property when the native library is located in the non-default location, and changing java.library.path may not have the desired effect.

When sqlite4java.library.path property is set, the library will be loaded only from that directory. Default directories will not be tried.

Calling this method when native library has been already loaded has no effect.

This method is thread-safe.

Parameters:

path - local directory that sqlite4java should use to load native libraries from, or null to disable the setting

main

public static void main(java.lang.String[] args)

Main method is called when you run java -jar sqlite4java.jar, and it prints out the version of the library, the version of the SQLite and the compile-time options the binaries were built with

Parameters:

args - command line