Interface FbStatement
-
- All Superinterfaces:
java.lang.AutoCloseable,ExceptionListenable
- All Known Subinterfaces:
FbWireStatement
- All Known Implementing Classes:
AbstractFbStatement,AbstractFbWireStatement,JnaStatement,V10Statement,V11Statement,V12Statement,V13Statement,V16Statement,V18Statement
public interface FbStatement extends ExceptionListenable, java.lang.AutoCloseable
API for statement handles.All methods defined in this interface are required to notify all
SQLExceptionthrown from the methods defined in this interface.- Since:
- 3.0
- Author:
- Mark Rotteveel
-
-
Method Summary
All Methods Instance Methods Abstract Methods Default Methods Modifier and Type Method Description voidaddStatementListener(StatementListener statementListener)Registers aStatementListener.default voidbatchCancel()Cancels the server side batch (that is, clear any rows batched on the server).default BatchCompletionbatchExecute()Execute the batch on the server.default voidclearCursorFlag(CursorFlag flag)Clears cursor flag.voidclose()Close and deallocate this statement.voidcloseCursor()Closes the cursor associated with this statement, leaving the statement itself allocated.voidcloseCursor(boolean transactionEnd)Closes the cursor associated with this statement, leaving the statement itself allocated.default BatchParameterBuffercreateBatchParameterBuffer()Creates aBatchParameterBufferinstance compatible with this protocol version.default voiddeferredBatchCreate(FbBatchConfig batchConfig, DeferredResponse<java.lang.Void> onResponse)Sends batch create with deferred response processing.default voiddeferredBatchRelease(DeferredResponse<java.lang.Void> onResponse)Closes (releases) the batch on the server with deferred response processing.default voiddeferredBatchSend(java.util.Collection<RowValue> rowValues, DeferredResponse<java.lang.Void> onResponse)Sends batch data with deferred response processing.RowDescriptoremptyRowDescriptor()voidensureClosedCursor(boolean transactionEnd)Ensures that the statement cursor is closed.voidexecute(RowValue parameters)Execute the statement.voidfetchRows(int fetchSize)Requests this statement to fetch the nextfetchSizerows.default voidfetchScroll(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> TgetCursorInfo(byte[] requestItems, int bufferLength, InfoProcessor<T> infoProcessor)Request cursor info.FbDatabasegetDatabase()intgetDefaultSqlInfoSize()java.lang.StringgetExecutionPlan()java.lang.StringgetExplainedExecutionPlan()intgetHandle()intgetMaxSqlInfoSize()RowDescriptorgetParameterDescriptor()RowDescriptorgetRowDescriptor()SqlCountHoldergetSqlCounts()Retrieves the SQL counts for the last execution of this statement.byte[]getSqlInfo(byte[] requestItems, int bufferLength)Request statement info.<T> TgetSqlInfo(byte[] requestItems, int bufferLength, InfoProcessor<T> infoProcessor)Request statement info.StatementStategetState()longgetTimeout()Gets the current statement timeout for this statement.FbTransactiongetTransaction()StatementTypegetType()booleanhasFetched()Has at least one fetch been executed on the current cursor?default booleanisCursorFlagSet(CursorFlag flag)Reports whether a cursor flag is set.voidprepare(java.lang.String statementText)Prepare the statement text.voidremoveStatementListener(StatementListener statementListener)Removes aStatementListener.default voidsetCursorFlag(CursorFlag flag)Set cursor flag.voidsetCursorName(java.lang.String cursorName)Sets the named cursor name for this statement.voidsetTimeout(long timeoutMillis)Sets the statement timeout.voidsetTransaction(FbTransaction transaction)Associates a transaction with this statementdefault booleansupportBatchUpdates()Reports whether this statement implementation supports server-side batch updates.default booleansupportsCursorInfo()Reports whether this statement implementation supportsgetCursorInfo(byte[], int, InfoProcessor)andgetCursorInfo(byte[], int).default booleansupportsFetchScroll()Reports whether this statement implementation supportsfetchScroll(FetchType, int, int)with anything other thanFetchType.NEXT.voidunprepare()Attempts to unprepare the currently prepared statement.voidvalidateParameters(RowValue parameters)Validates if the number of parameters matches the expected number and types, and if all values have been set.LockCloseablewithLock()Locks the lock withLock.lock()(or equivalent).-
Methods inherited from interface org.firebirdsql.gds.ng.listeners.ExceptionListenable
addExceptionListener, removeExceptionListener
-
-
-
-
Method Detail
-
getTransaction
FbTransaction getTransaction()
- Returns:
- Transaction currently associated with this statement
-
getDatabase
FbDatabase getDatabase()
- Returns:
- The database connection that created this statement
-
setTransaction
void setTransaction(FbTransaction transaction) throws java.sql.SQLException
Associates a transaction with this statement- Parameters:
transaction- The transaction- Throws:
java.sql.SQLException
-
getParameterDescriptor
RowDescriptor getParameterDescriptor()
- Returns:
- descriptor of the parameters of this statement
-
getRowDescriptor
RowDescriptor getRowDescriptor()
- Returns:
- descriptor of the row returned by this statement
-
getType
StatementType getType()
- Returns:
- The statement type
-
getState
StatementState getState()
- Returns:
- The current state of this statement
-
getHandle
int getHandle()
- Returns:
- The Firebird statement handle identifier
-
close
void close() throws java.sql.SQLExceptionClose and deallocate this statement.- Specified by:
closein interfacejava.lang.AutoCloseable- Throws:
java.sql.SQLException
-
closeCursor
void closeCursor() throws java.sql.SQLExceptionCloses the cursor associated with this statement, leaving the statement itself allocated.Equivalent to calling
closeCursor(boolean)withfalse.- Throws:
java.sql.SQLException
-
closeCursor
void closeCursor(boolean transactionEnd) throws java.sql.SQLExceptionCloses the cursor associated with this statement, leaving the statement itself allocated.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.- Parameters:
transactionEnd- close is in response to a transaction end or another operation which will close the cursor- Throws:
java.sql.SQLException
-
prepare
void prepare(java.lang.String statementText) throws java.sql.SQLExceptionPrepare the statement text.If this handle is in state
StatementState.NEWthen it will first allocate the statement.- Parameters:
statementText- Statement text- Throws:
java.sql.SQLException- If a database access error occurs, or this statement is currently executing a query.
-
unprepare
void unprepare() throws java.sql.SQLExceptionAttempts to unprepare the currently prepared statement.For Firebird versions that do not support
DSQL_unprepare, the implementation should attempt to close the cursor (usingcloseCursor()).- Throws:
java.sql.SQLException- If a database access error occurs
-
validateParameters
void validateParameters(RowValue parameters) throws java.sql.SQLException
Validates if the number of parameters matches the expected number and types, and if all values have been set.- Parameters:
parameters- Parameter values to validate- Throws:
java.sql.SQLException- When the number or type of parameters does not matchgetParameterDescriptor(), or when a parameter has not been set.
-
execute
void execute(RowValue parameters) throws java.sql.SQLException
Execute the statement.- Parameters:
parameters- The list of parameter values to use for execution.- Throws:
java.sql.SQLException- When the number of type of parameters does not match the types returned bygetParameterDescriptor(), a parameter value was not set, or when an error occurred executing this statement.
-
fetchRows
void fetchRows(int fetchSize) throws java.sql.SQLExceptionRequests this statement to fetch the nextfetchSizerows.Fetched rows are not returned from this method, but sent to the registered
StatementListenerinstances.- Parameters:
fetchSize- Number of rows to fetch (must be greater than0)- Throws:
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 than0.
-
fetchScroll
default void fetchScroll(FetchType fetchType, int fetchSize, int position) throws java.sql.SQLException
Requests this statement to fetch rows using the specified fetch type.The default implementation only supports
FetchType.NEXTby redirecting tofetchRows(int)and throws anSQLFeatureNotSupportedfor 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
NEXTorPRIOR, and 80 rows are still in the local buffer, the server-side position is actually 80 rows ahead (or behind). The next fetch withRELATIVEwill need to correct this inposition, and aPRIORafter aNEXTor aNEXTafter aPRIORwill need to reposition withRELATIVEorABSOLUTE, or know how many rows to ignore from the fetched batch.- Parameters:
fetchType- Fetch typefetchSize- Number of rows to fetch (must be> 0) (ignored by server for types other thanFetchType.NEXTandFetchType.PRIOR)position- Absolute or relative position for the row to fetch (ignored by server for types other thanFetchType.ABSOLUTEandFetchType.RELATIVE)- Throws:
java.sql.SQLFeatureNotSupportedException- For types other thanFetchType.NEXTif 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 conditions- Since:
- 5
- See Also:
supportsFetchScroll()
-
hasFetched
boolean hasFetched()
Has at least one fetch been executed on the current cursor?- Returns:
trueif at least one fetch has been executed on the current cursor,falseotherwise (including if nothing has been executed, or the current statement has no cursor)- Since:
- 5
-
supportsFetchScroll
default boolean supportsFetchScroll()
Reports whether this statement implementation supportsfetchScroll(FetchType, int, int)with anything other thanFetchType.NEXT.- Returns:
truefetchScrollsupported,falseif not supported (default implementation returnsfalse)- Since:
- 5
-
addStatementListener
void addStatementListener(StatementListener statementListener)
Registers aStatementListener.- Parameters:
statementListener- The row listener
-
removeStatementListener
void removeStatementListener(StatementListener statementListener)
Removes aStatementListener.- Parameters:
statementListener- The row listener
-
getSqlInfo
<T> T getSqlInfo(byte[] requestItems, int bufferLength, InfoProcessor<T> infoProcessor) throws java.sql.SQLExceptionRequest statement info.- Parameters:
requestItems- Array of info items to requestbufferLength- Response buffer length to useinfoProcessor- Implementation ofInfoProcessorto transform the info response- Returns:
- Transformed info response of type T
- Throws:
java.sql.SQLException- For errors retrieving or transforming the response.
-
getSqlInfo
byte[] getSqlInfo(byte[] requestItems, int bufferLength) throws java.sql.SQLExceptionRequest statement info.- Parameters:
requestItems- Array of info items to requestbufferLength- Response buffer length to use- Returns:
- Response buffer
- Throws:
java.sql.SQLException- For errors retrieving or transforming the response.
-
getCursorInfo
default <T> T getCursorInfo(byte[] requestItems, int bufferLength, InfoProcessor<T> infoProcessor) throws java.sql.SQLExceptionRequest cursor info.- Parameters:
requestItems- Array of info items to requestbufferLength- Response buffer length to useinfoProcessor- Implementation ofInfoProcessorto transform the info response- Returns:
- Transformed info response of type T
- Throws:
java.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)- Since:
- 5
- See Also:
supportsCursorInfo()
-
getCursorInfo
default byte[] getCursorInfo(byte[] requestItems, int bufferLength) throws java.sql.SQLExceptionRequest cursor info.- Parameters:
requestItems- Array of info items to requestbufferLength- Response buffer length to use- Returns:
- Response buffer
- Throws:
java.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)- Since:
- 5
-
supportsCursorInfo
default boolean supportsCursorInfo()
Reports whether this statement implementation supportsgetCursorInfo(byte[], int, InfoProcessor)andgetCursorInfo(byte[], int).- Returns:
truegetCursorInfosupported,falseif not supported (default implementation returnsfalse)- Since:
- 5
-
getDefaultSqlInfoSize
int getDefaultSqlInfoSize()
- Returns:
- The default size to use for the sql info buffer
-
getMaxSqlInfoSize
int getMaxSqlInfoSize()
- Returns:
- The maximum size to use for the sql info buffer
-
getExecutionPlan
java.lang.String getExecutionPlan() throws java.sql.SQLException- Returns:
- The execution plan of the currently prepared statement
- Throws:
java.sql.SQLException- If this statement is closed.
-
getExplainedExecutionPlan
java.lang.String getExplainedExecutionPlan() throws java.sql.SQLException- Returns:
- The detailed execution plan of the currently prepared statement
- Throws:
java.sql.SQLException- If this statement is closed.
-
getSqlCounts
SqlCountHolder getSqlCounts() throws java.sql.SQLException
Retrieves the SQL counts for the last execution of this statement.The retrieved SQL counts are also notified to all registered
StatementListeners.In general the
FbStatementwill (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).- Returns:
- The SQL counts of the last execution of this statement
- Throws:
java.sql.SQLException- If this statement is closed, or if this statement is in stateStatementState.CURSOR_OPENand not all rows have been fetched.
-
setCursorName
void setCursorName(java.lang.String cursorName) throws java.sql.SQLExceptionSets the named cursor name for this statement.- Parameters:
cursorName- Name of the cursor- Throws:
java.sql.SQLException- If this statement is closed, TODO: Other reasons (eg cursor open)?
-
emptyRowDescriptor
RowDescriptor emptyRowDescriptor()
- Returns:
- A potentially cached empty row descriptor for this statement or database.
-
ensureClosedCursor
void ensureClosedCursor(boolean transactionEnd) throws java.sql.SQLExceptionEnsures that the statement cursor is closed. Resets a statement, so it is ready to be reused for re-execute or prepare.- Parameters:
transactionEnd- Close is in response to a transaction end- Throws:
java.sql.SQLException- If this statement is closed or the cursor could not be closed.- Since:
- 3.0.6
-
setTimeout
void setTimeout(long timeoutMillis) throws java.sql.SQLExceptionSets the statement timeout.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.
- Parameters:
timeoutMillis- Timeout value in milliseconds- Throws:
java.sql.SQLException- If the value is less than zero, this statement is closed, or a database access error occurs- Since:
- 4.0
-
getTimeout
long getTimeout() throws java.sql.SQLExceptionGets the current statement timeout for this statement.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.
- Returns:
- The configured timeout in milliseconds; read the documentation in
setTimeout(long) - Throws:
java.sql.SQLException- If this statement is closed, or a database access error occurs- Since:
- 4.0
- See Also:
setTimeout(long)
-
setCursorFlag
default void setCursorFlag(CursorFlag flag)
Set cursor flag.If a protocol version does not support cursor flags, this is silently ignored.
- Parameters:
flag- Cursor flag to set- Since:
- 5
-
clearCursorFlag
default void clearCursorFlag(CursorFlag flag)
Clears cursor 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.
- Parameters:
flag- Cursor flag to clear- Since:
- 5
-
isCursorFlagSet
default boolean isCursorFlagSet(CursorFlag flag)
Reports whether a cursor flag is set.If a protocol version does not support cursor flags,
falseshould be returned.- Parameters:
flag- Cursor flag- Returns:
truewhen set,falseotherwise- Since:
- 5
-
supportBatchUpdates
default boolean supportBatchUpdates()
Reports whether this statement implementation supports server-side batch updates.- Returns:
trueserver-side batch updates supported,falseif not supported (default implementation returnsfalse)- Since:
- 5
-
deferredBatchCreate
default void deferredBatchCreate(FbBatchConfig batchConfig, DeferredResponse<java.lang.Void> onResponse) throws java.sql.SQLException
Sends batch create with deferred response processing.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 callonResponsebefore method return, and any exceptions generated by deferred processing should then be thrown from the method that causes the response to be received.- Parameters:
batchConfig- batch configurationonResponse- deferred action to call when response is received- Throws:
java.sql.SQLException- for database access errors (I/O errors)java.sql.SQLFeatureNotSupportedException- when this statement implementation does not support batch updates- Since:
- 5
- See Also:
supportBatchUpdates()
-
deferredBatchSend
default void deferredBatchSend(java.util.Collection<RowValue> rowValues, DeferredResponse<java.lang.Void> onResponse) throws java.sql.SQLException
Sends batch data with deferred response processing.For implementations that do not supported deferred or async response processing, see
deferredBatchCreate(FbBatchConfig, DeferredResponse)for expected behaviour.- Parameters:
rowValues- collection of row valuesonResponse- deferred action to call when response is received- Throws:
java.sql.SQLException- for database access errors (I/O errors)java.sql.SQLFeatureNotSupportedException- when this statement implementation does not support batch updates- Since:
- 5
- See Also:
supportBatchUpdates()
-
batchExecute
default BatchCompletion batchExecute() throws java.sql.SQLException
Execute the batch on the server.- Returns:
- batch completion response
- Throws:
java.sql.SQLException- for database access errorsjava.sql.SQLFeatureNotSupportedException- when this statement implementation does not support batch updates- Since:
- 5
- See Also:
supportBatchUpdates()
-
batchCancel
default void batchCancel() throws java.sql.SQLExceptionCancels the server side batch (that is, clear any rows batched on the server).- Throws:
java.sql.SQLException- for database access errorsjava.sql.SQLFeatureNotSupportedException- when this statement implementation does not support batch updates- Since:
- 5
- See Also:
supportBatchUpdates()
-
deferredBatchRelease
default void deferredBatchRelease(DeferredResponse<java.lang.Void> onResponse) throws java.sql.SQLException
Closes (releases) the batch on the server with deferred response processing.For implementations that do not supported deferred or async response processing, see
deferredBatchCreate(FbBatchConfig, DeferredResponse)for expected behaviour.- Parameters:
onResponse- deferred action to call when response is received- Throws:
java.sql.SQLException- for database access errorsjava.sql.SQLFeatureNotSupportedException- when this statement implementation does not support batch updates- Since:
- 5
- See Also:
supportBatchUpdates()
-
createBatchParameterBuffer
default BatchParameterBuffer createBatchParameterBuffer() throws java.sql.SQLException
Creates aBatchParameterBufferinstance compatible with this protocol version.- Returns:
- batch parameter buffer
- Throws:
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 updates- Since:
- 5
- See Also:
supportBatchUpdates()
-
withLock
LockCloseable withLock()
Locks the lock withLock.lock()(or equivalent).Implementations are expected to apply the same lock as
FbAttachment.withLock().- Returns:
- lock closeable which unlocks the lock on close
- See Also:
FbAttachment.withLock()
-
-