Package org.firebirdsql.gds.ng

Interface FbStatement

    • 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

      • 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

      • 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.SQLException
        Close and deallocate this statement.
        Throws:
        java.sql.SQLException

      • closeCursor

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

        Equivalent to calling closeCursor(boolean) with false.

        Throws:
        java.sql.SQLException

      • closeCursor

        void closeCursor​(boolean transactionEnd)
          throws java.sql.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:
        java.sql.SQLException

      • prepare

        void prepare​(java.lang.String statementText)
      throws java.sql.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:
        java.sql.SQLException - If a database access error occurs, or this statement is currently executing a query.

      • 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 match getParameterDescriptor(), 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 by getParameterDescriptor(), a parameter value was not set, or when an error occurred executing this statement.

      • fetchRows

        void fetchRows​(int fetchSize)
        throws java.sql.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:
        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.

      • 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 java.sql.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:
        java.sql.SQLException - For errors retrieving or transforming the response.

      • getSqlInfo

        byte[] getSqlInfo​(byte[] requestItems,
                  int bufferLength)
           throws java.sql.SQLException
        Request statement info.
        Parameters:
        requestItems - Array of info items to request
        bufferLength - Response buffer length to use
        Returns:
        Response buffer
        Throws:
        java.sql.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

        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 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:
        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.

      • setCursorName

        void setCursorName​(java.lang.String cursorName)
            throws java.sql.SQLException
        Sets 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.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:
        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.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:
        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.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:
        java.sql.SQLException - If this statement is closed, or a database access error occurs
        Since:
        4.0
        See Also:
        setTimeout(long)