public interface FbStatement extends ExceptionListenable, java.lang.AutoCloseable
All methods defined in this interface are required to notify all SQLException
thrown from the methods
defined in this interface.
Modifier and Type | Method and Description |
---|---|
void |
addStatementListener(StatementListener statementListener)
Registers a
StatementListener . |
default void |
batchCancel()
Cancels the server side batch (that is, clear any rows batched on the server).
|
default BatchCompletion |
batchExecute()
Execute the batch on the server.
|
default void |
clearCursorFlag(CursorFlag flag)
Clears cursor flag.
|
void |
close()
Close and deallocate this statement.
|
void |
closeCursor()
Closes the cursor associated with this statement, leaving the
statement itself allocated.
|
void |
closeCursor(boolean transactionEnd)
Closes the cursor associated with this statement, leaving the statement itself allocated.
|
default BatchParameterBuffer |
createBatchParameterBuffer()
Creates a
BatchParameterBuffer instance compatible with this protocol version. |
default void |
deferredBatchCreate(FbBatchConfig batchConfig,
DeferredResponse<java.lang.Void> onResponse)
Sends batch create with deferred response processing.
|
default void |
deferredBatchRelease(DeferredResponse<java.lang.Void> onResponse)
Closes (releases) the batch on the server with deferred response processing.
|
default void |
deferredBatchSend(java.util.Collection<RowValue> rowValues,
DeferredResponse<java.lang.Void> onResponse)
Sends batch data with deferred response processing.
|
RowDescriptor |
emptyRowDescriptor() |
void |
ensureClosedCursor(boolean transactionEnd)
Ensures that the statement cursor is closed.
|
void |
execute(RowValue parameters)
Execute the statement.
|
void |
fetchRows(int fetchSize)
Requests this statement to fetch the next
fetchSize rows. |
default void |
fetchScroll(FetchType fetchType,
int fetchSize,
int position)
Requests this statement to fetch rows using the specified fetch type.
|
default byte[] |
getCursorInfo(byte[] requestItems,
int bufferLength)
Request cursor info.
|
default <T> T |
getCursorInfo(byte[] requestItems,
int bufferLength,
InfoProcessor<T> infoProcessor)
Request cursor info.
|
FbDatabase |
getDatabase() |
int |
getDefaultSqlInfoSize() |
java.lang.String |
getExecutionPlan() |
java.lang.String |
getExplainedExecutionPlan() |
int |
getHandle() |
int |
getMaxSqlInfoSize() |
RowDescriptor |
getParameterDescriptor() |
RowDescriptor |
getRowDescriptor() |
SqlCountHolder |
getSqlCounts()
Retrieves the SQL counts for the last execution of this statement.
|
byte[] |
getSqlInfo(byte[] requestItems,
int bufferLength)
Request statement info.
|
<T> T |
getSqlInfo(byte[] requestItems,
int bufferLength,
InfoProcessor<T> infoProcessor)
Request statement info.
|
StatementState |
getState() |
long |
getTimeout()
Gets the current statement timeout for this statement.
|
FbTransaction |
getTransaction() |
StatementType |
getType() |
boolean |
hasFetched()
Has at least one fetch been executed on the current cursor?
|
default boolean |
isCursorFlagSet(CursorFlag flag)
Reports whether a cursor flag is set.
|
void |
prepare(java.lang.String statementText)
Prepare the statement text.
|
void |
removeStatementListener(StatementListener statementListener)
Removes a
StatementListener . |
default void |
setCursorFlag(CursorFlag flag)
Set cursor flag.
|
void |
setCursorName(java.lang.String cursorName)
Sets the named cursor name for this statement.
|
void |
setTimeout(long timeoutMillis)
Sets the statement timeout.
|
void |
setTransaction(FbTransaction transaction)
Associates a transaction with this statement
|
default boolean |
supportBatchUpdates()
Reports whether this statement implementation supports server-side batch updates.
|
default boolean |
supportsCursorInfo()
Reports whether this statement implementation supports
getCursorInfo(byte[], int, InfoProcessor) and
getCursorInfo(byte[], int) . |
default boolean |
supportsFetchScroll()
Reports whether this statement implementation supports
fetchScroll(FetchType, int, int) with anything
other than FetchType.NEXT . |
void |
unprepare()
Attempts to unprepare the currently prepared statement.
|
void |
validateParameters(RowValue parameters)
Validates if the number of parameters matches the expected number and types, and if all values have been set.
|
LockCloseable |
withLock()
Locks the lock with
Lock.lock() (or equivalent). |
addExceptionListener, removeExceptionListener
FbTransaction getTransaction()
FbDatabase getDatabase()
void setTransaction(FbTransaction transaction) throws java.sql.SQLException
transaction
- The transactionjava.sql.SQLException
RowDescriptor getParameterDescriptor()
RowDescriptor getRowDescriptor()
StatementType getType()
StatementState getState()
int getHandle()
void close() throws java.sql.SQLException
close
in interface java.lang.AutoCloseable
java.sql.SQLException
void closeCursor() throws java.sql.SQLException
Equivalent to calling closeCursor(boolean)
with false
.
java.sql.SQLException
void closeCursor(boolean transactionEnd) throws java.sql.SQLException
When this method is called in preparation of a commit, rollback or another operation which will close the cursor
(see transactionEnd
), then implementations may opt to not close the cursor on the server as the server
closes the cursor automatically, or the statement as a whole is closed by the implementation.
transactionEnd
- close is in response to a transaction end or another operation which will close the cursorjava.sql.SQLException
void prepare(java.lang.String statementText) throws java.sql.SQLException
If this handle is in state StatementState.NEW
then it will first allocate the statement.
statementText
- Statement textjava.sql.SQLException
- If a database access error occurs, or this statement is currently executing a query.void unprepare() throws java.sql.SQLException
For Firebird versions that do not support DSQL_unprepare
, the implementation should attempt to close the
cursor (using closeCursor()
).
java.sql.SQLException
- If a database access error occursvoid validateParameters(RowValue parameters) throws java.sql.SQLException
parameters
- Parameter values to validatejava.sql.SQLException
- When the number or type of parameters does not match getParameterDescriptor()
, or when a
parameter has not been set.void execute(RowValue parameters) throws java.sql.SQLException
parameters
- The list of parameter values to use for execution.java.sql.SQLException
- When the number of type of parameters does not match the types returned by getParameterDescriptor()
,
a parameter value was not set, or when an error occurred executing this statement.void fetchRows(int fetchSize) throws java.sql.SQLException
fetchSize
rows.
Fetched rows are not returned from this method, but sent to the registered StatementListener
instances.
fetchSize
- Number of rows to fetch (must be greater than 0
)java.sql.SQLException
- For database access errors, when called on a closed statement, when no cursor is open or when the fetch
size is not greater than 0
.default void fetchScroll(FetchType fetchType, int fetchSize, int position) throws java.sql.SQLException
The default implementation only supports FetchType.NEXT
by redirecting to fetchRows(int)
and
throws an SQLFeatureNotSupported
for other types.
The caller is responsible for tracking and correcting for server-side positional state, taking into account any
rows already fetched. For example, if 100 rows have been fetched with NEXT
or PRIOR
, and 80
rows are still in the local buffer, the server-side position is actually 80 rows ahead (or behind). The next
fetch with RELATIVE
will need to correct this in position
, and a PRIOR
after
a NEXT
or a NEXT
after a PRIOR
will need to reposition with RELATIVE
or
ABSOLUTE
, or know how many rows to ignore from the fetched batch.
fetchType
- Fetch typefetchSize
- Number of rows to fetch (must be > 0
) (ignored by server for types other than
FetchType.NEXT
and FetchType.PRIOR
)position
- Absolute or relative position for the row to fetch (ignored by server for types other than
FetchType.ABSOLUTE
and FetchType.RELATIVE
)java.sql.SQLFeatureNotSupportedException
- For types other than FetchType.NEXT
if the protocol version or the implementation does not
support scroll fetchjava.sql.SQLException
- For database access errors, when called on a closed statement, when no cursor is open or for server-side
error conditionssupportsFetchScroll()
boolean hasFetched()
true
if at least one fetch has been executed on the current cursor, false
otherwise
(including if nothing has been executed, or the current statement has no cursor)default boolean supportsFetchScroll()
fetchScroll(FetchType, int, int)
with anything
other than FetchType.NEXT
.true
fetchScroll
supported, false
if not supported (default implementation
returns false
)void addStatementListener(StatementListener statementListener)
StatementListener
.statementListener
- The row listenervoid removeStatementListener(StatementListener statementListener)
StatementListener
.statementListener
- The row listener<T> T getSqlInfo(byte[] requestItems, int bufferLength, InfoProcessor<T> infoProcessor) throws java.sql.SQLException
requestItems
- Array of info items to requestbufferLength
- Response buffer length to useinfoProcessor
- Implementation of InfoProcessor
to transform
the info responsejava.sql.SQLException
- For errors retrieving or transforming the response.byte[] getSqlInfo(byte[] requestItems, int bufferLength) throws java.sql.SQLException
requestItems
- Array of info items to requestbufferLength
- Response buffer length to usejava.sql.SQLException
- For errors retrieving or transforming the response.default <T> T getCursorInfo(byte[] requestItems, int bufferLength, InfoProcessor<T> infoProcessor) throws java.sql.SQLException
requestItems
- Array of info items to requestbufferLength
- Response buffer length to useinfoProcessor
- Implementation of InfoProcessor
to transform
the info responsejava.sql.SQLException
- For errors retrieving or transforming the responsejava.sql.SQLFeatureNotSupportedException
- If requesting cursor info is not supported (Firebird 4.0 or earlier, or native implementation)supportsCursorInfo()
default byte[] getCursorInfo(byte[] requestItems, int bufferLength) throws java.sql.SQLException
requestItems
- Array of info items to requestbufferLength
- Response buffer length to usejava.sql.SQLException
- For errors retrieving or transforming the responsejava.sql.SQLFeatureNotSupportedException
- If requesting cursor info is not supported (Firebird 4.0 or earlier, or native implementation)default boolean supportsCursorInfo()
getCursorInfo(byte[], int, InfoProcessor)
and
getCursorInfo(byte[], int)
.true
getCursorInfo
supported, false
if not supported (default implementation
returns false
)int getDefaultSqlInfoSize()
int getMaxSqlInfoSize()
java.lang.String getExecutionPlan() throws java.sql.SQLException
java.sql.SQLException
- If this statement is closed.java.lang.String getExplainedExecutionPlan() throws java.sql.SQLException
java.sql.SQLException
- If this statement is closed.SqlCountHolder getSqlCounts() throws java.sql.SQLException
The retrieved SQL counts are also notified to all registered StatementListener
s.
In general the FbStatement
will (should) retrieve and notify listeners of the SQL counts automatically
at times where it is relevant (eg after executing a statement that does not produce multiple rows, or after
fetching all rows).
java.sql.SQLException
- If this statement is closed, or if this statement is in state StatementState.CURSOR_OPEN
and not
all rows have been fetched.void setCursorName(java.lang.String cursorName) throws java.sql.SQLException
cursorName
- Name of the cursorjava.sql.SQLException
- If this statement is closed, TODO: Other reasons (eg cursor open)?RowDescriptor emptyRowDescriptor()
void ensureClosedCursor(boolean transactionEnd) throws java.sql.SQLException
transactionEnd
- Close is in response to a transaction endjava.sql.SQLException
- If this statement is closed or the cursor could not be closed.void setTimeout(long timeoutMillis) throws java.sql.SQLException
The statement timeout value is ignored in implementations that do not support timeouts. If the provided
timeout value is greater than supported (eg greater than 4294967295 milliseconds on Firebird 4), the
implementation should behave as if zero (0
) was set, but still report the original value.
The configured timeout only affects subsequent executes on this statement. The timeout includes time spent between reading from the result set.
timeoutMillis
- Timeout value in millisecondsjava.sql.SQLException
- If the value is less than zero, this statement is closed, or a database access error occurslong getTimeout() throws java.sql.SQLException
This method will only return the current statement timeout value for this method, it will not consider attachment or connection level timeouts. This is an implementation decision that might change in a point release.
setTimeout(long)
java.sql.SQLException
- If this statement is closed, or a database access error occurssetTimeout(long)
default void setCursorFlag(CursorFlag flag)
If a protocol version does not support cursor flags, this is silently ignored.
flag
- Cursor flag to setdefault void clearCursorFlag(CursorFlag flag)
Setting a cursor flag only affects subsequent executes. A currently open cursor will not be affected.
If a protocol version does not support cursor flags, this is silently ignored.
flag
- Cursor flag to cleardefault boolean isCursorFlagSet(CursorFlag flag)
If a protocol version does not support cursor flags, false
should be returned.
flag
- Cursor flagtrue
when set, false
otherwisedefault boolean supportBatchUpdates()
true
server-side batch updates supported, false
if not supported (default implementation
returns false
)default void deferredBatchCreate(FbBatchConfig batchConfig, DeferredResponse<java.lang.Void> onResponse) throws java.sql.SQLException
Implementations that do not supported deferred or async response processing should call
DeferredResponse.onResponse(Object)
and - optionally - DeferredResponse.onException(Exception)
synchronously. If the response is deferred, but the implementation is not capable of connecting the response
back, it should call onResponse
before method return, and any exceptions generated by deferred processing
should then be thrown from the method that causes the response to be received.
batchConfig
- batch configurationonResponse
- deferred action to call when response is receivedjava.sql.SQLException
- for database access errors (I/O errors)java.sql.SQLFeatureNotSupportedException
- when this statement implementation does not support batch updatessupportBatchUpdates()
default void deferredBatchSend(java.util.Collection<RowValue> rowValues, DeferredResponse<java.lang.Void> onResponse) throws java.sql.SQLException
For implementations that do not supported deferred or async response processing, see
deferredBatchCreate(FbBatchConfig, DeferredResponse)
for expected behaviour.
rowValues
- collection of row valuesonResponse
- deferred action to call when response is receivedjava.sql.SQLException
- for database access errors (I/O errors)java.sql.SQLFeatureNotSupportedException
- when this statement implementation does not support batch updatessupportBatchUpdates()
default BatchCompletion batchExecute() throws java.sql.SQLException
java.sql.SQLException
- for database access errorsjava.sql.SQLFeatureNotSupportedException
- when this statement implementation does not support batch updatessupportBatchUpdates()
default void batchCancel() throws java.sql.SQLException
java.sql.SQLException
- for database access errorsjava.sql.SQLFeatureNotSupportedException
- when this statement implementation does not support batch updatessupportBatchUpdates()
default void deferredBatchRelease(DeferredResponse<java.lang.Void> onResponse) throws java.sql.SQLException
For implementations that do not supported deferred or async response processing, see
deferredBatchCreate(FbBatchConfig, DeferredResponse)
for expected behaviour.
onResponse
- deferred action to call when response is receivedjava.sql.SQLException
- for database access errorsjava.sql.SQLFeatureNotSupportedException
- when this statement implementation does not support batch updatessupportBatchUpdates()
default BatchParameterBuffer createBatchParameterBuffer() throws java.sql.SQLException
BatchParameterBuffer
instance compatible with this protocol version.java.sql.SQLException
- if this statement is closed, or a database access error occurs, or when the parameter buffer could not be
created for other reasonsjava.sql.SQLFeatureNotSupportedException
- when this statement implementation does not support batch updatessupportBatchUpdates()
LockCloseable withLock()
Lock.lock()
(or equivalent).
Implementations are expected to apply the same lock as FbAttachment.withLock()
.
FbAttachment.withLock()
Copyright © 2001-2023 Jaybird (Firebird JDBC) team. All rights reserved.