public interface FbStatement extends ExceptionListenable
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 . |
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.
|
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. |
FbDatabase |
getDatabase() |
int |
getDefaultSqlInfoSize() |
java.lang.String |
getExecutionPlan() |
java.lang.String |
getExplainedExecutionPlan() |
RowDescriptor |
getFieldDescriptor()
Deprecated.
Use
getRowDescriptor() instead; will be removed in Jaybird 5 |
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() |
void |
prepare(java.lang.String statementText)
Prepare the statement text.
|
void |
removeStatementListener(StatementListener statementListener)
Removes a
StatementListener . |
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
|
void |
validateParameters(RowValue parameters)
Validates if the number of parameters matches the expected number and types, and if all values have been set.
|
addExceptionListener, removeExceptionListener
FbTransaction getTransaction()
FbDatabase getDatabase()
void setTransaction(FbTransaction transaction) throws java.sql.SQLException
transaction
- The transactionjava.sql.SQLException
RowDescriptor getParameterDescriptor()
@Deprecated RowDescriptor getFieldDescriptor()
getRowDescriptor()
instead; will be removed in Jaybird 5RowDescriptor getRowDescriptor()
StatementType getType()
StatementState getState()
int getHandle()
void close() throws java.sql.SQLException
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 or rollback (see transactionEnd
), then
implementations may opt to not close the cursor on the server if the server closes the cursor automatically.
transactionEnd
- Close is in response to a transaction end.java.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 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 > 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 > 0
.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
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 were
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
Implementations should only close an open cursor and log this fact with a stacktrace on debug. This is a stopgap measure for situations where the code using this statement handle has not been able to properly close the cursor.
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)
Copyright © 2001-2023 Jaybird (Firebird JDBC/JCA) team. All rights reserved.