com.almworks.sqlite4java.SQLiteStatement
|
||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||
java.lang.Object
public final class SQLiteStatement
SQLiteStatement wraps an instance of compiled SQL statement, represented as sqlite3_stmt*
handle in SQLite C Interface.
SQLiteConnection.prepare(com.almworks.sqlite4java.SQLParts, boolean) methods. After you've done using
the statement, you have to free it using dispose() method. Statements are usually cached, so until
you release the statement, prepare calls for the same SQL will result in needless compilation.
Typical use includes binding parameters, then executing steps and reading columns. Most methods directly
correspond to the sqlite3 C interface methods.
SQLiteStatement statement = connection.prepare(".....");
try {
statement.bind(....).bind(....);
while (statement.step()) {
statement.columnXXX(...);
}
} finally {
statement.dispose();
}
Unless a method is marked as thread-safe, it is confined to the thread that has opened the connection. Calling
a confined method from a different thread will result in exception.
| Field Summary | |
|---|---|
static SQLiteStatement |
DISPOSED
Public instance of initially disposed, dummy statement. |
| Method Summary | |
|---|---|
SQLiteStatement |
bind(int index,
byte[] value)
Binds SQL parameter to a BLOB value, represented by a byte array. |
SQLiteStatement |
bind(int index,
byte[] value,
int offset,
int length)
Binds SQL parameter to a BLOB value, represented by a range within byte array. |
SQLiteStatement |
bind(int index,
double value)
Binds SQL parameter to a value of type double. |
SQLiteStatement |
bind(int index,
int value)
Binds SQL parameter to a value of type int. |
SQLiteStatement |
bind(int index,
long value)
Binds SQL parameter to a value of type long. |
SQLiteStatement |
bind(int index,
java.lang.String value)
Binds SQL parameter to a value of type String. |
SQLiteStatement |
bind(java.lang.String name,
byte[] value)
Binds SQL parameter to a BLOB value, represented by a byte array. |
SQLiteStatement |
bind(java.lang.String name,
byte[] value,
int offset,
int length)
Binds SQL parameter to a BLOB value, represented by a range within byte array. |
SQLiteStatement |
bind(java.lang.String name,
double value)
Binds SQL parameter to a value of type double. |
SQLiteStatement |
bind(java.lang.String name,
int value)
Binds SQL parameter to a value of type int. |
SQLiteStatement |
bind(java.lang.String name,
long value)
Binds SQL parameter to a value of type long. |
SQLiteStatement |
bind(java.lang.String name,
java.lang.String value)
Binds SQL parameter to a value of type String. |
SQLiteStatement |
bindNull(int index)
Binds SQL parameter to a NULL value. |
SQLiteStatement |
bindNull(java.lang.String name)
Binds SQL parameter to a NULL value. |
java.io.OutputStream |
bindStream(int index)
Binds SQL parameter to a BLOB value, represented by a stream. |
java.io.OutputStream |
bindStream(int index,
int bufferSize)
Binds SQL parameter to a BLOB value, represented by a stream. |
java.io.OutputStream |
bindStream(java.lang.String name)
Binds SQL parameter to a BLOB value, represented by a stream. |
java.io.OutputStream |
bindStream(java.lang.String name,
int bufferSize)
Binds SQL parameter to a BLOB value, represented by a stream. |
SQLiteStatement |
bindZeroBlob(int index,
int length)
Binds SQL parameter to a BLOB value, consiting of a given number of zero bytes. |
SQLiteStatement |
bindZeroBlob(java.lang.String name,
int length)
Binds SQL parameter to a BLOB value, consiting of a given number of zero bytes. |
void |
cancel()
Cancels the currently running statement. |
SQLiteStatement |
clearBindings()
Clears parameter bindings, if there are any. |
byte[] |
columnBlob(int column)
Gets a column value after step has returned a row of the result set. |
int |
columnCount()
Gets the number of columns in the result set. |
double |
columnDouble(int column)
Gets a column value after step has returned a row of the result set. |
int |
columnInt(int column)
Gets a column value after step has returned a row of the result set. |
long |
columnLong(int column)
Gets a column value after step has returned a row of the result set. |
boolean |
columnNull(int column)
Checks if the value returned in the given column is null. |
java.io.InputStream |
columnStream(int column)
Gets an InputStream for reading a BLOB column value after step has returned a row of the result set. |
java.lang.String |
columnString(int column)
Gets a column value after step has returned a row of the result set. |
int |
columnType(int column)
Gets a type of a column after step() has returned a row. |
java.lang.Object |
columnValue(int column)
Gets a column value after step has returned a row of the result set. |
void |
dispose()
Disposes this statement and frees allocated resources. |
int |
getBindParameterCount()
Returns the number of parameters that can be bound. |
int |
getBindParameterIndex(java.lang.String name)
Returns the index of a bind parameter with a given name, as defined in the SQL. |
java.lang.String |
getBindParameterName(int index)
Returns the name of a given bind parameter, as defined in the SQL. |
java.lang.String |
getColumnDatabaseName(int column)
Gets a name of the column's table's database in the result set. |
java.lang.String |
getColumnName(int column)
Gets a name of the column in the result set. |
java.lang.String |
getColumnOriginName(int column)
Gets the original name of the column that is behind the given column in the result set. |
java.lang.String |
getColumnTableName(int column)
Gets a name of the column's table in the result set. |
SQLParts |
getSqlParts()
Returns the immutable SQLParts object that was used to create this instance. |
boolean |
hasBindings()
Checks if some parameters were bound |
boolean |
hasRow()
Checks whether there's data to be read with columnXYZ methods. |
boolean |
hasStepped()
Checks if the statement has been evaluated |
boolean |
isDisposed()
|
boolean |
isReadOnly()
Check if the underlying statement is a SELECT. |
int |
loadInts(int column,
int[] buffer,
int offset,
int length)
Loads int values returned from a query into a buffer. |
int |
loadLongs(int column,
long[] buffer,
int offset,
int length)
Loads long values returned from a query into a buffer. |
SQLiteStatement |
reset()
Convenience method that resets the statement and clears bindings. |
SQLiteStatement |
reset(boolean clearBindings)
Resets the statement if it has been stepped, allowing SQL to be run again. |
boolean |
step()
Evaluates SQL statement until either there's data to be read, an error occurs, or the statement completes. |
SQLiteStatement |
stepThrough()
Convenience method that ignores the available data and steps through the SQL statement until evaluation is completed. |
java.lang.String |
toString()
|
| Methods inherited from class java.lang.Object |
|---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait |
| Field Detail |
|---|
public static final SQLiteStatement DISPOSED
| Method Detail |
|---|
public boolean isDisposed()
public SQLParts getSqlParts()
public void dispose()
prepare
Calling this method on an already disposed instance has no effect.
After SQLiteStatement instance is disposed, it is no longer usable and holds no references to its originating
connection or SQLite database.
public SQLiteStatement reset(boolean clearBindings)
throws SQLiteException
clearBinding parameter is false, then all preceding bindings remain in place. You can change
some or none of them and run statement again.
clearBindings - if true, all parameters will be set to NULL
SQLiteException - if SQLite returns an error, or if the call violates the contract of this class
public SQLiteStatement reset()
throws SQLiteException
reset(boolean) for a detailed
description.
SQLiteException - if SQLite returns an error, or if the call violates the contract of this class
public SQLiteStatement clearBindings()
throws SQLiteException
SQLiteException - if SQLite returns an error, or if the call violates the contract of this class
public boolean step()
throws SQLiteException
step runs that program
until there's a "break point".
Note that since SQlite 3.7, reset(boolean) method is called by step() automatically if anything other than
SQLITE_ROW is returned.
This method can produce one of the three results:
columnXYZ methods;
reset(boolean) is called;
SQLiteException - if result code from sqlite3_step was neither SQLITE_ROW nor SQLITE_DONE, or if any other problem occurs
public SQLiteStatement stepThrough()
throws SQLiteException
step() for details.
Most often it's used to chain calls.
SQLiteException - if SQLite returns an error, or if the call violates the contract of this classpublic void cancel()
stepsPerCallback parameter
is set to large values, the reaction to this call may be far from immediate.
If execution is cancelled, the step() method will throw SQLiteInterruptedException, and transaction
will be rolled back.
This method is thread-safe.
SQLiteConnection.setStepsPerCallback(int),
sqlite3_progress_callbackpublic boolean hasRow()
columnXYZ methods.
step() has returned truepublic boolean hasBindings()
public boolean hasStepped()
public int loadInts(int column,
int[] buffer,
int offset,
int length)
throws SQLiteException
step() and columnInt().
If result set contains NULL value, it's replaced with 0.
This method may be called iteratively with a fixed-size buffer. For example:
SQLiteStatement st = connection.prepare("SELECT id FROM articles WHERE text LIKE '%whatever%'");
try {
int[] buffer = new int[1000];
while (!st.hasStepped() || st.hasRow()) {
int loaded = st.loadInts(0, buffer, 0, buffer.length);
processResult(buffer, 0, loaded);
}
} finally {
st.dispose();
}
After method finishes, the number of rows loaded is returned and statement's hasRow() method indicates
whether more rows are available.
column - column index, as used in columnInt(int)buffer - buffer for accepting loaded integersoffset - offset in the buffer to start writinglength - maximum number of integers to load from the database
SQLiteException - if SQLite returns an error, or if the call violates the contract of this class
public int loadLongs(int column,
long[] buffer,
int offset,
int length)
throws SQLiteException
step() and columnLong().
If result set contains NULL value, it's replaced with 0.
This method may be called iteratively with a fixed-size buffer. For example:
SQLiteStatement st = connection.prepare("SELECT id FROM articles WHERE text LIKE '%whatever%'");
try {
long[] buffer = new long[1000];
while (!st.hasStepped() || st.hasRow()) {
int loaded = st.loadInts(0, buffer, 0, buffer.length);
processResult(buffer, 0, loaded);
}
} finally {
st.dispose();
}
After method finishes, the number of rows loaded is returned and statement's hasRow() method indicates
whether more rows are available.
column - column index, as used in columnInt(int)buffer - buffer for accepting loaded longsoffset - offset in the buffer to start writinglength - maximum number of integers to load from the database
SQLiteException - if SQLite returns an error, or if the call violates the contract of this class
public int getBindParameterCount()
throws SQLiteException
SQLiteException - if SQLite returns an error, or if the call violates the contract of this class
public java.lang.String getBindParameterName(int index)
throws SQLiteException
index - the index of a bindable parameter, starting with 1
SQLiteException - if SQLite returns an error, or if the call violates the contract of this class
public int getBindParameterIndex(java.lang.String name)
throws SQLiteException
name - parameter name
SQLiteException - if SQLite returns an error, or if the call violates the contract of this class
public SQLiteStatement bind(int index,
double value)
throws SQLiteException
index - the index of the boundable parameter, starting with 1value - non-null double value
SQLiteException - if SQLite returns an error, or if the call violates the contract of this class
public SQLiteStatement bind(java.lang.String name,
double value)
throws SQLiteException
name - parameter namevalue - non-null double value
SQLiteException - if SQLite returns an error,
or if parameter with specified name was not found,
or if the call violates the contract of this class
public SQLiteStatement bind(int index,
int value)
throws SQLiteException
index - the index of the boundable parameter, starting with 1value - non-null int value
SQLiteException - if SQLite returns an error, or if the call violates the contract of this class
public SQLiteStatement bind(java.lang.String name,
int value)
throws SQLiteException
name - parameter namevalue - non-null int value
SQLiteException - if SQLite returns an error,
or if parameter with specified name was not found,
or if the call violates the contract of this class
public SQLiteStatement bind(int index,
long value)
throws SQLiteException
index - the index of the boundable parameter, starting with 1value - non-null long value
SQLiteException - if SQLite returns an error, or if the call violates the contract of this class
public SQLiteStatement bind(java.lang.String name,
long value)
throws SQLiteException
name - parameter namevalue - non-null long value
SQLiteException - if SQLite returns an error,
or if parameter with specified name was not found,
or if the call violates the contract of this class
public SQLiteStatement bind(int index,
java.lang.String value)
throws SQLiteException
index - the index of the boundable parameter, starting with 1value - String value, if null then bindNull(int) will be called
SQLiteException - if SQLite returns an error, or if the call violates the contract of this class
public SQLiteStatement bind(java.lang.String name,
java.lang.String value)
throws SQLiteException
name - parameter namevalue - String value, if null then bindNull(int) will be called
SQLiteException - if SQLite returns an error,
or if parameter with specified name was not found,
or if the call violates the contract of this class
public SQLiteStatement bind(int index,
byte[] value)
throws SQLiteException
index - the index of the boundable parameter, starting with 1value - an array of bytes to be used as the blob value; if null, bindNull(int) is called
SQLiteException - if SQLite returns an error, or if the call violates the contract of this class
public SQLiteStatement bind(java.lang.String name,
byte[] value)
throws SQLiteException
name - parameter namevalue - an array of bytes to be used as the blob value; if null, bindNull(int) is called
SQLiteException - if SQLite returns an error,
or if parameter with specified name was not found,
or if the call violates the contract of this class
public SQLiteStatement bind(int index,
byte[] value,
int offset,
int length)
throws SQLiteException
index - the index of the boundable parameter, starting with 1value - an array of bytes; if null, bindNull(int) is calledoffset - position in the byte array to start reading value fromlength - number of bytes to read from value
SQLiteException - if SQLite returns an error, or if the call violates the contract of this class
public SQLiteStatement bind(java.lang.String name,
byte[] value,
int offset,
int length)
throws SQLiteException
name - parameter namevalue - an array of bytes; if null, bindNull(int) is calledoffset - position in the byte array to start reading value fromlength - number of bytes to read from value
SQLiteException - if SQLite returns an error,
or if parameter with specified name was not found,
or if the call violates the contract of this class
public SQLiteStatement bindZeroBlob(int index,
int length)
throws SQLiteException
index - the index of the boundable parameter, starting with 1length - number of zero bytes to use as a parameter
SQLiteException - if SQLite returns an error, or if the call violates the contract of this class
public SQLiteStatement bindZeroBlob(java.lang.String name,
int length)
throws SQLiteException
name - parameter namelength - number of zero bytes to use as a parameter
SQLiteException - if SQLite returns an error,
or if parameter with specified name was not found,
or if the call violates the contract of this class
public SQLiteStatement bindNull(int index)
throws SQLiteException
index - the index of the boundable parameter, starting with 1
SQLiteException - if SQLite returns an error, or if the call violates the contract of this class
public SQLiteStatement bindNull(java.lang.String name)
throws SQLiteException
name - parameter name
SQLiteException - if SQLite returns an error,
or if parameter with specified name was not found,
or if the call violates the contract of this class
public java.io.OutputStream bindStream(int index)
throws SQLiteException
step().
After the application is done writing to the parameter stream, it should be closed.
If statement is executed before the stream is closed, the value will not be set for the parameter.
index - the index of the boundable parameter, starting with 1
SQLiteException - if SQLite returns an error, or if the call violates the contract of this class
public java.io.OutputStream bindStream(java.lang.String name)
throws SQLiteException
step().
After the application is done writing to the parameter stream, it should be closed.
If statement is executed before the stream is closed, the value will not be set for the parameter.
name - parameter name
SQLiteException - if SQLite returns an error,
or if parameter with specified name was not found,
or if the call violates the contract of this class
public java.io.OutputStream bindStream(int index,
int bufferSize)
throws SQLiteException
step().
After the application is done writing to the parameter stream, it should be closed.
If statement is executed before the stream is closed, the value will not be set for the parameter.
index - the index of the boundable parameter, starting with 1bufferSize - the number of bytes to be allocated for the buffer (the buffer will grow as needed)
SQLiteException - if SQLite returns an error, or if the call violates the contract of this class
public java.io.OutputStream bindStream(java.lang.String name,
int bufferSize)
throws SQLiteException
step().
After the application is done writing to the parameter stream, it should be closed.
If statement is executed before the stream is closed, the value will not be set for the parameter.
name - parameter namebufferSize - the number of bytes to be allocated for the buffer (the buffer will grow as needed)
SQLiteException - if SQLite returns an error,
or if parameter with specified name was not found,
or if the call violates the contract of this class
public java.lang.String columnString(int column)
throws SQLiteException
step() has returned true.
column - the index of the column, starting with 0
SQLiteException - if SQLite returns an error, or if the call violates the contract of this class
public int columnInt(int column)
throws SQLiteException
step() has returned true.
column - the index of the column, starting with 0
SQLiteException - if SQLite returns an error, or if the call violates the contract of this class
public double columnDouble(int column)
throws SQLiteException
step() has returned true.
column - the index of the column, starting with 0
SQLiteException - if SQLite returns an error, or if the call violates the contract of this class
public long columnLong(int column)
throws SQLiteException
step() has returned true.
column - the index of the column, starting with 0
SQLiteException - if SQLite returns an error, or if the call violates the contract of this class
public byte[] columnBlob(int column)
throws SQLiteException
step() has returned true.
column - the index of the column, starting with 0
SQLiteException - if SQLite returns an error, or if the call violates the contract of this class
public java.io.InputStream columnStream(int column)
throws SQLiteException
step() has returned true.
The stream should be read and closed before next call to step or reset. Otherwise, the stream is automatically
closed and disposed, and the following attempts to read from it result in IOException.
column - the index of the column, starting with 0
SQLiteException - if SQLite returns an error, or if the call violates the contract of this class
public boolean columnNull(int column)
throws SQLiteException
column - the index of the column, starting with 0
SQLiteException - if SQLite returns an error, or if the call violates the contract of this class
public int columnCount()
throws SQLiteException
step() returned false).
However, for some statements where the number of columns may vary - such as
"SELECT * FROM ..." - the correct result is guaranteed only if method is called during statement execution,
when step() has returned true. (That is so because sqlite3_column_count function does not
force statement recompilation if database schema has changed, but sqlite3_step does.)
SQLiteException - if SQLite returns an error, or if the call violates the contract of this class
public java.lang.Object columnValue(int column)
throws SQLiteException
step() has returned true.
The class of the object returned depends on the value and the type of value reported by SQLite. It can be:
null if the value is NULL
String if the value has type SQLITE_TEXT
Integer or Long if the value has type SQLITE_INTEGER (depending on the value)
Double if the value has type SQLITE_FLOAT
byte[] if the value has type SQLITE_BLOB
column - the index of the column, starting with 0
SQLiteException - if SQLite returns an error, or if the call violates the contract of this class
public int columnType(int column)
throws SQLiteException
step() has returned true.
Note that SQLite has dynamic typing, so this method returns the affinity of the specified column.
See dynamic typing for details.
This method returns an integer constant, defined in SQLiteConstants: SQLITE_NULL,
SQLITE_INTEGER, SQLITE_TEXT, SQLITE_BLOB or SQLITE_FLOAT.
The value returned by this method is only meaningful if
no type conversions have occurred as the result of calling columnNNN() methods.
column - the index of the column, starting with 0
SQLiteException - if SQLite returns an error, or if the call violates the contract of this class
public java.lang.String getColumnName(int column)
throws SQLiteException
column - the index of the column, starting with 0
SQLiteException - if SQLite returns an error, or if the call violates the contract of this class
public java.lang.String getColumnTableName(int column)
throws SQLiteException
column - the index of the column, starting with 0
SQLiteException - if SQLite returns an error, or if the call violates the contract of this class
public java.lang.String getColumnDatabaseName(int column)
throws SQLiteException
column - the index of the column, starting with 0
SQLiteException - if SQLite returns an error, or if the call violates the contract of this class
public java.lang.String getColumnOriginName(int column)
throws SQLiteException
column - the index of the column, starting with 0
SQLiteException - if SQLite returns an error, or if the call violates the contract of this class
public boolean isReadOnly()
throws SQLiteException
SQLiteException - if SQLite returns an error, or if the call violates the contract of this classpublic java.lang.String toString()
toString in class java.lang.Object
|
||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||