|
||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectcom.almworks.sqlite4java.SQLiteConnection
public final class SQLiteConnection
SQLiteConnection is a single connection to sqlite database. It wraps the sqlite3*
database handle from SQLite C Interface.
dispose()
, the connection cannot be reused and the instance
should be forgotten.
Several connections to the same database can be opened by creating several instances of SQLiteConnection.
SQLiteConnection tracks all statements it had prepared. When connection is disposed,
it first tries to dispose all prepared statements. If there's an active transaction, it is rolled
back.
SQLiteStatement
,
sqlite3*Constructor Summary | |
---|---|
SQLiteConnection()
Creates a connection to an in-memory temporary database. |
|
SQLiteConnection(java.io.File dbfile)
Creates a connection to the database located in the specified file. |
Method Summary | |
---|---|
SQLiteBlob |
blob(java.lang.String table,
java.lang.String column,
long rowid,
boolean writeAccess)
Convenience method for calling blob() on the currently selected database. |
SQLiteBlob |
blob(java.lang.String dbname,
java.lang.String table,
java.lang.String column,
long rowid,
boolean writeAccess)
Opens a BLOB for reading or writing. |
SQLiteLongArray |
createArray()
Creates a virtual table within the current session, to represent an array of long values (functionality provided by test_intarray module from SQLite sources). |
SQLiteLongArray |
createArray(java.lang.String name,
boolean cached)
Creates a virtual table within the current session, to represent an array of long values (functionality provided by test_intarray module from SQLite sources). |
java.lang.String |
debug(java.lang.String sql)
Runs SQL and returns formatted result. |
void |
dispose()
Closes this connection and disposes all related resources. |
SQLiteConnection |
exec(java.lang.String sql)
Executes SQL. |
protected void |
finalize()
The finalize() method is used to warn about a non-closed connection being forgotten. |
boolean |
getAutoCommit()
Checks if the database is in the auto-commit mode. |
int |
getChanges()
This method returns the number of database rows that were changed or inserted or deleted by the most recently completed SQL statement in this connection. |
java.io.File |
getDatabaseFile()
Returns the database file. |
int |
getErrorCode()
This method returns the error code of the most recently failed operation. |
java.lang.String |
getErrorMessage()
This method returns the English error message that describes the error returned by getErrorCode() . |
long |
getLastInsertId()
Returns the ROWID of the row, last inserted in this connection (regardless of which statement was used). |
int |
getOpenFlags()
Returns the flags that were used to open this connection. |
int |
getTotalChanges()
This method returns the total number of database rows that were changed or inserted or deleted since this connection was opened. |
void |
interrupt()
This method can be called to interrupt a currently long-running SQL statement, causing it to fail with an exception. |
boolean |
isDisposed()
Checks if the connection has been disposed. |
boolean |
isMemoryDatabase()
Checks whether this connection is to an in-memory database. |
boolean |
isOpen()
Tells whether connection is open. |
SQLiteConnection |
open()
Opens the connection, creating database if needed. |
SQLiteConnection |
open(boolean allowCreate)
Opens the connection, optionally creating the database. |
SQLiteConnection |
openReadonly()
Opens the connection is read-only mode. |
SQLiteConnection |
openV2(int flags)
Opens the connection with the specified flags for the sqlite3_open_v2 method. |
SQLiteStatement |
prepare(SQLParts sql)
Convenience method that prepares a cached statement for the given SQL. |
SQLiteStatement |
prepare(SQLParts sql,
boolean cached)
Prepares an SQL statement. |
SQLiteStatement |
prepare(java.lang.String sql)
Convenience method that prepares a cached statement for the given SQL. |
SQLiteStatement |
prepare(java.lang.String sql,
boolean cached)
Convenience method that prepares a statement for the given String-based SQL. |
SQLiteProfiler |
profile()
Starts SQL profiling and returns the profiler class. |
SQLiteConnection |
setBusyTimeout(long millis)
Sets "busy timeout" for this connection. |
void |
setStepsPerCallback(int stepsPerCallback)
Sets the frequency of database callbacks during long-running SQL statements. |
SQLiteProfiler |
stopProfiling()
Stops the profiling and returns the profiler instance with data. |
java.lang.String |
toString()
|
Methods inherited from class java.lang.Object |
---|
clone, equals, getClass, hashCode, notify, notifyAll, wait, wait, wait |
Constructor Detail |
---|
public SQLiteConnection(java.io.File dbfile)
dbfile
- database file, or null to create an in-memory databasepublic SQLiteConnection()
SQLiteConnection(java.io.File)
Method Detail |
---|
public java.io.File getDatabaseFile()
public boolean isMemoryDatabase()
public void setStepsPerCallback(int stepsPerCallback)
stepsPerCallback
- the number of internal SQLite cycles in between calls to the progress callback (default 1)public SQLiteConnection open(boolean allowCreate) throws SQLiteException
allowCreate
- if true, database file may be created. For an in-memory database, this parameter must
be true.
SQLiteException
- if SQLite returns an error, or if the call violates the contract of this classpublic SQLiteConnection open() throws SQLiteException
open(boolean)
for a full description.
SQLiteException
- if SQLite returns an error, or if the call violates the contract of this classpublic SQLiteConnection openReadonly() throws SQLiteException
open(boolean)
for a full description.
SQLiteException
- if SQLite returns an error, or if the call violates the contract of this classpublic SQLiteConnection openV2(int flags) throws SQLiteException
SQLiteConstants
and can be ORed together.
This method is provided for future versions compatibility and for open options not otherwise supported by
sqlite4java. Use this method only if other open() methods are not sufficient.
In all other respects, this method works exactly like open(boolean)
, consult documentation to that method
for details.
flags
- integer flags as defined by sqlite3_open_v2 function
SQLiteException
- if SQLite returns an error, or if the call violates the contract of this classpublic boolean isOpen()
public boolean isDisposed()
public int getOpenFlags()
public void dispose()
public SQLiteConnection exec(java.lang.String sql) throws SQLiteException
prepare(com.almworks.sqlite4java.SQLParts, boolean)
.
Several statements, delimited by a semicolon, can be executed with a single call.
Do not use this method if your SQL contains non-ASCII characters!
sql
- an SQL statement
SQLiteException
- if SQLite returns an error, or if the call violates the contract of this classpublic SQLiteStatement prepare(SQLParts sql, boolean cached) throws SQLiteException
cached
parameter
to false. Because parsing SQL is costly, caching should be used in cases where a single SQL can be
executed more than once.
Cached statements are cleared of state before or after they are used.
SQLParts is used to contains the SQL query, yet there are convenience methods that accept String.
Returned statement must be disposed when the calling code is done with it, whether it was cached or not.
sql
- the SQL statement, not nullcached
- if true, the statement handle will be cached by the connection
SQLiteStatement
SQLiteException
- if SQLite returns an error, or if the call violates the contract of this classpublic SQLiteStatement prepare(java.lang.String sql) throws SQLiteException
prepare(SQLParts, boolean)
for details.
sql
- an SQL statement, not null
SQLiteStatement
SQLiteException
- if SQLite returns an error, or if the call violates the contract of this classpublic SQLiteStatement prepare(java.lang.String sql, boolean cached) throws SQLiteException
prepare(SQLParts, boolean)
for details.
sql
- the SQL statement, not nullcached
- if true, the statement handle will be cached by the connection
SQLiteStatement
SQLiteException
- if SQLite returns an error, or if the call violates the contract of this classpublic SQLiteStatement prepare(SQLParts sql) throws SQLiteException
prepare(SQLParts, boolean)
for details.
sql
- the SQL statement, not null
SQLiteStatement
SQLiteException
- if SQLite returns an error, or if the call violates the contract of this classpublic SQLiteBlob blob(java.lang.String dbname, java.lang.String table, java.lang.String column, long rowid, boolean writeAccess) throws SQLiteException
SQLiteBlob
, which can
be used to read or write a single table cell with a BLOB value. After operations are done, the blob should
be disposed.
See SQLite documentation about transactional behavior of the corresponding methods.
dbname
- database name, or null for the current databasetable
- table name, not nullcolumn
- column name, not nullrowid
- row idwriteAccess
- if true, write access is requested
SQLiteException
- if SQLite returns an error, or if the call violates the contract of this classpublic SQLiteBlob blob(java.lang.String table, java.lang.String column, long rowid, boolean writeAccess) throws SQLiteException
blob(String, String, String, long, boolean)
for detailed description.
table
- table name, not nullcolumn
- column name, not nullrowid
- row idwriteAccess
- if true, write access is requested
SQLiteException
- if SQLite returns an error, or if the call violates the contract of this classpublic SQLiteConnection setBusyTimeout(long millis) throws SQLiteException
millis
- number of milliseconds for the busy timeout, or 0 to disable the timeout
SQLiteException
- if SQLite returns an error, or if the call violates the contract of this classpublic boolean getAutoCommit() throws SQLiteException
SQLiteException
- if SQLite returns an error, or if the call violates the contract of this classpublic long getLastInsertId() throws SQLiteException
SQLiteException
- if SQLite returns an error, or if the call violates the contract of this classpublic int getChanges() throws SQLiteException
SQLiteException
- if SQLite returns an error, or if the call violates the contract of this classpublic int getTotalChanges() throws SQLiteException
SQLiteException
- if SQLite returns an error, or if the call violates the contract of this classpublic void interrupt() throws SQLiteException
SQLiteException
- if SQLite returns an error, or if the call violates the contract of this classpublic int getErrorCode() throws SQLiteException
SQLiteException.getErrorCode()
.
SQLiteException
- if SQLite returns an error, or if the call violates the contract of this classpublic java.lang.String getErrorMessage() throws SQLiteException
getErrorCode()
.
SQLiteException
- if SQLite returns an error, or if the call violates the contract of this classpublic SQLiteProfiler profile()
stopProfiling()
is called.public SQLiteProfiler stopProfiling()
public SQLiteLongArray createArray(java.lang.String name, boolean cached) throws SQLiteException
long[] itemIds = ...; SQLiteLongArray array = connection.createArray(); SQLiteStatement st = connection.prepare("SELECT * FROM items WHERE itemId IN " + array.getName()); array.bind(itemIds); while (st.step()) { // read values } st.dispose(); array.dispose(); The array contents is bound usingSQLiteLongArray.bind(long[], int, int, boolean, boolean)
methods. Binding an array is not a transactional operation; it does not start or stop a transaction, and contents of the array is not affected by ROLLBACK. You can execute any SQL using array's name (SQLiteLongArray.getName()
) as the table name. The actual table is a VIRTUAL TABLE, residing in TEMP database. (Because of that, temp database may be created on disk - you can change that using PRAGMA TEMP_STORE.) It is possible to execute an SQL that contains several virtual array tables. Note that the virtual array table does not have a primary key (bound values may have duplicates and come in random order), so be careful about performance. SQLiteLongArray are cached by the SQLiteConnection, unlesscached
parameter is set tofalse
. When cached SQLiteLongArray is disposed, it is kept by the connection for further reuse. When a non-cached SQLiteLongArray is disposed, its table is deleted from the TEMP database. Caution: It's possible to use DROP TABLE on the array virtual table; doing that will make SQL statements that use the table invalid.
name
- the name of the table, must be a correct SQL table name, and contains only ASCII characters. If null,
a temporary name will be provided automatically (can be later retrieved via SQLiteLongArray.getName()
.cached
- if true, then a cached array will be used, thus reducing the number of virtual tables and schema
changes. If cached is true and a name is given and there's no free array with that name, a new array will be created.
If cached is true and name is null, then any free array will be allocated.
SQLiteException
- if name is already in use, or if other problem happenspublic SQLiteLongArray createArray() throws SQLiteException
createArray(null, true)
. See createArray(String, boolean)
for details.
SQLiteException
- in case any problem is reported by SQLite, or general contract is brokenpublic java.lang.String toString()
toString
in class java.lang.Object
protected void finalize() throws java.lang.Throwable
finalize
in class java.lang.Object
java.lang.Throwable
public java.lang.String debug(java.lang.String sql)
sql
- SQL to execute
|
||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |