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

      • 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.
        Specified by:
        close in interface java.lang.AutoCloseable
        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, 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.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.

      • unprepare

        void unprepare()
        throws java.sql.SQLException
        Attempts to unprepare the currently prepared statement.

        For Firebird versions that do not support DSQL_unprepare, the implementation should attempt to close the cursor (using closeCursor()).

        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 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 greater than 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 greater than 0.

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

        Parameters:
        fetchType - Fetch type
        fetchSize - 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)
        Throws:
        java.sql.SQLFeatureNotSupportedException - For types other than FetchType.NEXT if the protocol version or the implementation does not support scroll fetch
        java.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:
        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)
        Since:
        5

      • supportsFetchScroll

        default boolean supportsFetchScroll()
        Reports whether this statement implementation supports fetchScroll(FetchType, int, int) with anything other than FetchType.NEXT.
        Returns:
        true fetchScroll supported, false if not supported (default implementation returns false)
        Since:
        5

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

      • getCursorInfo

        default <T> T getCursorInfo​(byte[] requestItems,
                            int bufferLength,
                            InfoProcessor<T> infoProcessor)
                     throws java.sql.SQLException
        Request cursor 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
        java.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.SQLException
        Request cursor info.
        Parameters:
        requestItems - Array of info items to request
        bufferLength - Response buffer length to use
        Returns:
        Response buffer
        Throws:
        java.sql.SQLException - For errors retrieving or transforming the response
        java.sql.SQLFeatureNotSupportedException - If requesting cursor info is not supported (Firebird 4.0 or earlier, or native implementation)
        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 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).

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

      • 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, false should be returned.

        Parameters:
        flag - Cursor flag
        Returns:
        true when set, false otherwise
        Since:
        5

      • supportBatchUpdates

        default boolean supportBatchUpdates()
        Reports whether this statement implementation supports server-side batch updates.
        Returns:
        true server-side batch updates supported, false if not supported (default implementation returns false)
        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 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.

        Parameters:
        batchConfig - batch configuration
        onResponse - 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 values
        onResponse - 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 errors
        java.sql.SQLFeatureNotSupportedException - when this statement implementation does not support batch updates
        Since:
        5
        See Also:
        supportBatchUpdates()

      • batchCancel

        default void batchCancel()
                  throws java.sql.SQLException
        Cancels the server side batch (that is, clear any rows batched on the server).
        Throws:
        java.sql.SQLException - for database access errors
        java.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 errors
        java.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 a BatchParameterBuffer instance 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 reasons
        java.sql.SQLFeatureNotSupportedException - when this statement implementation does not support batch updates
        Since:
        5
        See Also:
        supportBatchUpdates()