Package org.firebirdsql.gds.ng

Class AbstractFbStatement

    • Constructor Detail

      • AbstractFbStatement

        protected AbstractFbStatement()

    • Method Detail

      • getTransactionListener

        protected final TransactionListener getTransactionListener()
        Gets the TransactionListener instance for this statement.

        This method should only be called by this object itself. Subclasses may provide their own transaction listener, but the instance returned by this method should be the same for the lifetime of this FbStatement.

        Returns:
        The transaction listener instance for this statement.

      • hasFetched

        public final boolean hasFetched()
        Description copied from interface: FbStatement
        Has at least one fetch been executed on the current cursor?
        Specified by:
        hasFetched in interface FbStatement
        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)

      • close

        public void close()
           throws java.sql.SQLException
        Description copied from interface: FbStatement
        Close and deallocate this statement.
        Specified by:
        close in interface java.lang.AutoCloseable
        Specified by:
        close in interface FbStatement
        Throws:
        java.sql.SQLException

      • closeCursor

        public final void closeCursor()
                       throws java.sql.SQLException
        Description copied from interface: FbStatement
        Closes the cursor associated with this statement, leaving the statement itself allocated.

        Equivalent to calling FbStatement.closeCursor(boolean) with false.

        Specified by:
        closeCursor in interface FbStatement
        Throws:
        java.sql.SQLException

      • closeCursor

        public final void closeCursor​(boolean transactionEnd)
                       throws java.sql.SQLException
        Description copied from interface: FbStatement
        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.

        Specified by:
        closeCursor in interface FbStatement
        Parameters:
        transactionEnd - close is in response to a transaction end or another operation which will close the cursor
        Throws:
        java.sql.SQLException

      • ensureClosedCursor

        public final void ensureClosedCursor​(boolean transactionEnd)
                              throws java.sql.SQLException
        Description copied from interface: FbStatement
        Ensures that the statement cursor is closed. Resets a statement, so it is ready to be reused for re-execute or prepare.
        Specified by:
        ensureClosedCursor in interface FbStatement
        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.

      • unprepare

        public void unprepare()
               throws java.sql.SQLException
        Description copied from interface: FbStatement
        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 FbStatement.closeCursor()).

        Specified by:
        unprepare in interface FbStatement
        Throws:
        java.sql.SQLException - If a database access error occurs

      • switchState

        protected final void switchState​(StatementState newState)
                          throws java.sql.SQLException
        Sets the StatementState.
        Parameters:
        newState - New state
        Throws:
        java.sql.SQLException - When the state is changed to an illegal next state

      • forceState

        protected void forceState​(StatementState newState)
        Forces the statement to the specified state without throwing an exception if this is not a valid transition.

        Does nothing if current state is CLOSED.

        Parameters:
        newState - New state
        See Also:
        switchState(StatementState)

      • setType

        protected void setType​(StatementType type)
        Sets the StatementType
        Parameters:
        type - New type

      • queueRowData

        protected final void queueRowData​(RowValue rowData)
        Queues row data for consumption
        Parameters:
        rowData - Row data

      • isBeforeFirst

        protected final boolean isBeforeFirst()

      • isAfterLast

        protected final boolean isAfterLast()

      • reset

        protected final void reset()
        Reset statement state, equivalent to calling reset(boolean) with false.

      • resetAll

        protected final void resetAll()
        Reset statement state and clear parameter description, equivalent to calling reset(boolean) with true.

      • reset

        protected void reset​(boolean resetAll)
        Resets the statement for next execution. Implementation in derived class must lock on FbStatement.withLock() and call super.reset(resetAll)
        Parameters:
        resetAll - Also reset field and parameter info

      • setParameterDescriptor

        protected void setParameterDescriptor​(RowDescriptor parameterDescriptor)
        Sets the parameter descriptor.
        Parameters:
        parameterDescriptor - Parameter descriptor

      • setRowDescriptor

        protected void setRowDescriptor​(RowDescriptor rowDescriptor)
        Sets the (result set) row descriptor.
        Parameters:
        rowDescriptor - Row descriptor

      • getParameterDescriptionInfoRequestItems

        public byte[] getParameterDescriptionInfoRequestItems()
        Returns:
        The isc_info_sql_describe_vars info request items.
        See Also:
        getStatementInfoRequestItems()

      • fetchScroll

        public final void fetchScroll​(FetchType fetchType,
                              int fetchSize,
                              int position)
                       throws java.sql.SQLException
        Description copied from interface: FbStatement
        Requests this statement to fetch rows using the specified fetch type.

        The default implementation only supports FetchType.NEXT by redirecting to FbStatement.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.

        Specified by:
        fetchScroll in interface FbStatement
        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
        See Also:
        FbStatement.supportsFetchScroll()

      • getSqlInfo

        public final <T> T getSqlInfo​(byte[] requestItems,
                              int bufferLength,
                              InfoProcessor<T> infoProcessor)
                       throws java.sql.SQLException
        Request statement info.
        Specified by:
        getSqlInfo in interface FbStatement
        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.

      • getCursorInfo

        public final <T> T getCursorInfo​(byte[] requestItems,
                                 int bufferLength,
                                 InfoProcessor<T> infoProcessor)
                          throws java.sql.SQLException
        Description copied from interface: FbStatement
        Request cursor info.
        Specified by:
        getCursorInfo in interface FbStatement
        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)
        See Also:
        FbStatement.supportsCursorInfo()

      • getCursorInfo

        public final byte[] getCursorInfo​(byte[] requestItems,
                                  int bufferLength)
                           throws java.sql.SQLException
        Description copied from interface: FbStatement
        Request cursor info.
        Specified by:
        getCursorInfo in interface FbStatement
        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)

      • getCursorInfoImpl

        protected byte[] getCursorInfoImpl​(byte[] requestItems,
                                   int bufferLength)
                            throws java.sql.SQLException
        Implementation of getCursorInfo(byte[], int).

        An implementation should not notify exceptionListenerDispatcher, as that is already handled in getCursorInfo(byte[], int).

        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)
        See Also:
        getCursorInfo(byte[], int), FbStatement.supportsCursorInfo()

      • getExecutionPlan

        public final java.lang.String getExecutionPlan()
                                        throws java.sql.SQLException
        Specified by:
        getExecutionPlan in interface FbStatement
        Returns:
        The execution plan of the currently prepared statement
        Throws:
        java.sql.SQLException - If this statement is closed.

      • getExplainedExecutionPlan

        public final java.lang.String getExplainedExecutionPlan()
                                                 throws java.sql.SQLException
        Specified by:
        getExplainedExecutionPlan in interface FbStatement
        Returns:
        The detailed execution plan of the currently prepared statement
        Throws:
        java.sql.SQLException - If this statement is closed.

      • getSqlCounts

        public SqlCountHolder getSqlCounts()
                            throws java.sql.SQLException
        Description copied from interface: FbStatement
        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).

        Specified by:
        getSqlCounts in interface FbStatement
        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.

      • free

        protected abstract void free​(int option)
                      throws java.sql.SQLException
        Frees the currently allocated statement. Either close the cursor with ISCConstants.DSQL_close or drop the statement handle using ISCConstants.DSQL_drop.
        Parameters:
        option - Free option
        Throws:
        java.sql.SQLException

      • validateParameters

        public final void validateParameters​(RowValue parameters)
                              throws java.sql.SQLException
        Description copied from interface: FbStatement
        Validates if the number of parameters matches the expected number and types, and if all values have been set.
        Specified by:
        validateParameters in interface FbStatement
        Parameters:
        parameters - Parameter values to validate
        Throws:
        java.sql.SQLException - When the number or type of parameters does not match FbStatement.getParameterDescriptor(), or when a parameter has not been set.

      • checkStatementValid

        protected final void checkStatementValid​(StatementState ignoreState)
                                  throws java.sql.SQLException
        Performs the same check as checkStatementValid(), but considers ignoreState as valid.
        Parameters:
        ignoreState - The invalid state (see checkStatementValid() to ignore
        Throws:
        java.sql.SQLException - When this statement is closed or in error state.

      • finalize

        protected void finalize()
                 throws java.lang.Throwable
        Overrides:
        finalize in class java.lang.Object
        Throws:
        java.lang.Throwable

      • isValidTransactionClass

        protected abstract boolean isValidTransactionClass​(java.lang.Class<? extends FbTransaction> transactionClass)
        Method to decide if a transaction implementation class is valid for the statement implementation.

        Eg a V10Statement will only work with an FbWireTransaction implementation.

        Parameters:
        transactionClass - Class of the transaction
        Returns:
        true when the transaction class is valid for the statement implementation.

      • setTransaction

        public final void setTransaction​(FbTransaction newTransaction)
                          throws java.sql.SQLException
        Description copied from interface: FbStatement
        Associates a transaction with this statement
        Specified by:
        setTransaction in interface FbStatement
        Parameters:
        newTransaction - The transaction
        Throws:
        java.sql.SQLException

      • setTimeout

        public void setTimeout​(long statementTimeout)
                throws java.sql.SQLException
        Description copied from interface: FbStatement
        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.

        Specified by:
        setTimeout in interface FbStatement
        Parameters:
        statementTimeout - 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

      • getTimeout

        public long getTimeout()
                throws java.sql.SQLException
        Description copied from interface: FbStatement
        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.

        Specified by:
        getTimeout in interface FbStatement
        Returns:
        The configured timeout in milliseconds; read the documentation in FbStatement.setTimeout(long)
        Throws:
        java.sql.SQLException - If this statement is closed, or a database access error occurs
        See Also:
        FbStatement.setTimeout(long)

      • getAllowedTimeout

        protected long getAllowedTimeout()
                          throws java.sql.SQLException
        Returns:
        The timeout value, or 0 if the timeout is larger than supported
        Throws:
        java.sql.SQLException - If the statement is invalid

      • parseStatementInfo

        protected void parseStatementInfo​(byte[] statementInfoResponse)
                           throws java.sql.SQLException
        Parse the statement info response in statementInfoResponse. If the response is truncated, a new request is done using getStatementInfoRequestItems()
        Parameters:
        statementInfoResponse - Statement info response
        Throws:
        java.sql.SQLException

      • hasSingletonResult

        protected final boolean hasSingletonResult()
        Returns:
        true if this is a stored procedure (or other singleton result producing statement) with at least 1 output field

      • hasFields

        protected final boolean hasFields()
        Returns:
        true if this statement has at least one output field (either singleton or result set)

      • signalExecute

        protected final OperationCloseHandle signalExecute()
        Signals the start of an execute for this statement.
        Returns:
        OperationCloseHandle handle for the operation

      • signalFetch

        protected final OperationCloseHandle signalFetch()
        Signals the start of a fetch for this statement.
        Returns:
        OperationCloseHandle handle for the operation