Package org.firebirdsql.gds.ng

Interface FbStatement

All Superinterfaces:
ExceptionListenable
All Known Subinterfaces:
FbWireStatement
All Known Implementing Classes:
AbstractFbStatement, AbstractFbWireStatement, JnaStatement, V10Statement, V11Statement, V12Statement, V13Statement, V16Statement
public interface FbStatement extends ExceptionListenable
API for statement handles.

All methods defined in this interface are required to notify all SQLException thrown from the methods defined in this interface.

Since:
3.0
Author:
Mark Rotteveel

  • Method Details

    • 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 SQLException
      Associates a transaction with this statement
      Parameters:
      transaction - The transaction
      Throws:
      SQLException

    • getParameterDescriptor

      RowDescriptor getParameterDescriptor()
      Returns:
      descriptor of the parameters of this statement

    • getFieldDescriptor

      @Deprecated RowDescriptor getFieldDescriptor()
      Deprecated.
      Use getRowDescriptor() instead; will be removed in Jaybird 5
      Returns:
      descriptor of the fields returned by 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 SQLException
      Close and deallocate this statement.
      Throws:
      SQLException

    • closeCursor

      void closeCursor() throws SQLException
      Closes the cursor associated with this statement, leaving the statement itself allocated.

      Equivalent to calling closeCursor(boolean) with false.

      Throws:
      SQLException

    • closeCursor

      void closeCursor(boolean transactionEnd) throws SQLException
      Closes the cursor associated with this statement, leaving the statement itself allocated.

      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.

      Parameters:
      transactionEnd - Close is in response to a transaction end.
      Throws:
      SQLException

    • prepare

      void prepare(String statementText) throws SQLException
      Prepare the statement text.

      If this handle is in state StatementState.NEW then it will first allocate the statement.

      Parameters:
      statementText - Statement text
      Throws:
      SQLException - If a database access error occurs, or this statement is currently executing a query.

    • validateParameters

      void validateParameters(RowValue parameters) throws 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:
      SQLException - When the number or type of parameters does not match getParameterDescriptor(), or when a parameter has not been set.

    • execute

      void execute(RowValue parameters) throws SQLException
      Execute the statement.
      Parameters:
      parameters - The list of parameter values to use for execution.
      Throws:
      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.

    • fetchRows

      void fetchRows(int fetchSize) throws SQLException
      Requests this statement to fetch the next fetchSize rows.

      Fetched rows are not returned from this method, but sent to the registered StatementListener instances.

      Parameters:
      fetchSize - Number of rows to fetch (must be > 0)
      Throws:
      SQLException - For database access errors, when called on a closed statement, when no cursor is open or when the fetch size is not > 0.

    • addStatementListener

      void addStatementListener(StatementListener statementListener)
      Registers a StatementListener.
      Parameters:
      statementListener - The row listener

    • removeStatementListener

      void removeStatementListener(StatementListener statementListener)
      Removes a StatementListener.
      Parameters:
      statementListener - The row listener

    • getSqlInfo

      <T> T getSqlInfo(byte[] requestItems, int bufferLength, InfoProcessor<T> infoProcessor) throws SQLException
      Request statement info.
      Parameters:
      requestItems - Array of info items to request
      bufferLength - Response buffer length to use
      infoProcessor - Implementation of InfoProcessor to transform the info response
      Returns:
      Transformed info response of type T
      Throws:
      SQLException - For errors retrieving or transforming the response.

    • getSqlInfo

      byte[] getSqlInfo(byte[] requestItems, int bufferLength) throws SQLException
      Request statement info.
      Parameters:
      requestItems - Array of info items to request
      bufferLength - Response buffer length to use
      Returns:
      Response buffer
      Throws:
      SQLException

    • 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

      String getExecutionPlan() throws SQLException
      Returns:
      The execution plan of the currently prepared statement
      Throws:
      SQLException - If this statement is closed.

    • getExplainedExecutionPlan

      String getExplainedExecutionPlan() throws SQLException
      Returns:
      The detailed execution plan of the currently prepared statement
      Throws:
      SQLException - If this statement is closed.

    • getSqlCounts

      SqlCountHolder getSqlCounts() throws 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 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).

      Returns:
      The SQL counts of the last execution of this statement
      Throws:
      SQLException - If this statement is closed, or if this statement is in state StatementState.CURSOR_OPEN and not all rows have been fetched.

    • setCursorName

      void setCursorName(String cursorName) throws SQLException
      Sets the named cursor name for this statement.
      Parameters:
      cursorName - Name of the cursor
      Throws:
      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 SQLException
      Ensures that the statement cursor is closed. Resets a statement so it is ready to be reused for re-execute or prepare.

      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.

      Parameters:
      transactionEnd - Close is in response to a transaction end
      Throws:
      SQLException - If this statement is closed or the cursor could not be closed.
      Since:
      3.0.6

    • setTimeout

      void setTimeout(long timeoutMillis) throws SQLException
      Sets 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:
      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 SQLException
      Gets 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:
      SQLException - If this statement is closed, or a database access error occurs
      Since:
      4.0
      See Also: