org.firebirdsql.gds.ng

Class AbstractFbStatement

java.lang.Object

org.firebirdsql.gds.ng.AbstractFbStatement

All Implemented Interfaces:

FbStatement, ExceptionListenable

Direct Known Subclasses:

AbstractFbWireStatement, JnaStatement

public abstract class AbstractFbStatement
extends java.lang.Object
implements FbStatement

Since:

3.0

Author:

Mark Rotteveel

Field Summary

Fields

Modifier and Type	Field and Description
protected ExceptionListenerDispatcher	exceptionListenerDispatcher
protected StatementListenerDispatcher	statementListenerDispatcher

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	AbstractFbStatement(java.lang.Object syncObject)

Method Summary

Modifier and Type	Method and Description
void	addExceptionListener(ExceptionListener listener) Adds an exception listener to this object.
void	addStatementListener(StatementListener statementListener) Registers a StatementListener.
protected void	checkStatementValid() Checks if this statement is not in StatementState.CLOSED, StatementState.CLOSING, StatementState.NEW or StatementState.ERROR, and throws an SQLException if it is.
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.
protected ExecutionPlanProcessor	createExecutionPlanProcessor()
protected SqlCountProcessor	createSqlCountProcessor()
void	ensureClosedCursor(boolean transactionEnd) Ensures that the statement cursor is closed.
protected void	finalize()
protected abstract void	free(int option) Frees the currently allocated statement (either close the cursor with ISCConstants.DSQL_close or drop the statement handle using ISCConstants.DSQL_drop.
java.lang.String	getExecutionPlan()
RowDescriptor	getFieldDescriptor()
byte[]	getParameterDescriptionInfoRequestItems()
RowDescriptor	getParameterDescriptor()
SqlCountHolder	getSqlCounts() Retrieves the SQL counts for the last execution of this statement.
<T> T	getSqlInfo(byte[] requestItems, int bufferLength, InfoProcessor<T> infoProcessor) Request statement info.
StatementState	getState()
byte[]	getStatementInfoRequestItems()
protected WarningMessageCallback	getStatementWarningCallback()
protected java.lang.Object	getSynchronizationObject() Get synchronization object.
FbTransaction	getTransaction()
protected TransactionListener	getTransactionListener() Gets the TransactionListener instance for this statement.
StatementType	getType()
protected boolean	hasFields()
protected boolean	hasSingletonResult()
protected boolean	isAllRowsFetched()
protected boolean	isPrepareAllowed(StatementState state) Is a call to FbStatement.prepare(String) allowed for the supplied StatementState.
protected abstract boolean	isValidTransactionClass(java.lang.Class<? extends FbTransaction> transactionClass) Method to decide if a transaction implementation class is valid for the statement implementation.
protected void	parseStatementInfo(byte[] statementInfoResponse) Parse the statement info response in statementInfoResponse.
protected void	queueRowData(RowValue rowData) Queues row data for consumption
void	removeExceptionListener(ExceptionListener listener) Removes an exception listener to this object.
void	removeStatementListener(StatementListener statementListener) Removes a StatementListener.
protected void	reset() Reset statement state, equivalent to calling reset(boolean) with false
protected void	reset(boolean resetAll) Resets the statement for next execution.
protected void	resetAll() Reset statement state and clear parameter description, equivalent to calling reset(boolean) with true
protected void	setAllRowsFetched(boolean allRowsFetched) Sets the allRowsFetched property.
protected void	setFieldDescriptor(RowDescriptor fieldDescriptor) Sets the (result set) field descriptor.
protected void	setParameterDescriptor(RowDescriptor parameterDescriptor) Sets the parameter descriptor.
void	setTransaction(FbTransaction newTransaction) Associates a transaction with this statement
protected void	setType(StatementType type) Sets the StatementType
protected void	switchState(StatementState newState) Sets the StatementState.
protected void	validateParameters(RowValue parameters) Validates if the number of parameters matches the expected number and types, and if all values have been set.

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface org.firebirdsql.gds.ng.FbStatement

emptyRowDescriptor, execute, fetchRows, getDatabase, getDefaultSqlInfoSize, getHandle, getMaxSqlInfoSize, getSqlInfo, prepare, setCursorName

Field Detail

statementListenerDispatcher

protected final StatementListenerDispatcher statementListenerDispatcher

exceptionListenerDispatcher

protected final ExceptionListenerDispatcher exceptionListenerDispatcher

Constructor Detail

AbstractFbStatement

protected AbstractFbStatement(java.lang.Object syncObject)

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.

getStatementWarningCallback

protected final WarningMessageCallback getStatementWarningCallback()

getSynchronizationObject

protected final java.lang.Object getSynchronizationObject()

Get synchronization object.

Returns:

object, cannot be null.

close

public void close()
           throws java.sql.SQLException

Description copied from interface: FbStatement

Close and deallocate this statement.

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 or rollback (see transactionEnd), then implementations may opt to not close the cursor on the server if the server closes the cursor automatically.

Specified by:

closeCursor in interface FbStatement

Parameters:

transactionEnd - Close is in response to a transaction end.

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.

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.

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.

getState

public StatementState getState()

Specified by:

getState in interface FbStatement

Returns:

The current state of this statement

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

getType

public final StatementType getType()

Specified by:

getType in interface FbStatement

Returns:

The statement type

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

setAllRowsFetched

protected final void setAllRowsFetched(boolean allRowsFetched)

Sets the allRowsFetched property.

When set to true all registered StatementListener instances are notified for the StatementListener.allRowsFetched(FbStatement) event.

Parameters:

allRowsFetched - true: all rows fetched, false not all rows fetched.

isAllRowsFetched

protected final boolean isAllRowsFetched()

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 synchronize on getSynchronizationObject() and call super.reset(resetAll)

Parameters:

resetAll - Also reset field and parameter info

isPrepareAllowed

protected boolean isPrepareAllowed(StatementState state)

Is a call to FbStatement.prepare(String) allowed for the supplied StatementState.

Parameters:

state - The statement state

Returns:

true call to prepare is allowed

getParameterDescriptor

public final RowDescriptor getParameterDescriptor()

Specified by:

getParameterDescriptor in interface FbStatement

Returns:

descriptor of the parameters of this statement

setParameterDescriptor

protected void setParameterDescriptor(RowDescriptor parameterDescriptor)

Sets the parameter descriptor.

Parameters:

parameterDescriptor - Parameter descriptor

getFieldDescriptor

public final RowDescriptor getFieldDescriptor()

Specified by:

getFieldDescriptor in interface FbStatement

Returns:

descriptor of the fields returned by this statement

setFieldDescriptor

protected void setFieldDescriptor(RowDescriptor fieldDescriptor)

Sets the (result set) field descriptor.

Parameters:

fieldDescriptor - Field descriptor

getStatementInfoRequestItems

public byte[] getStatementInfoRequestItems()

Returns:

The (full) statement info request items.

See Also:

getParameterDescriptionInfoRequestItems()

getParameterDescriptionInfoRequestItems

public byte[] getParameterDescriptionInfoRequestItems()

Returns:

The isc_info_sql_describe_vars info request items.

See Also:

getStatementInfoRequestItems()

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.

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.

createExecutionPlanProcessor

protected ExecutionPlanProcessor createExecutionPlanProcessor()

Returns:

New instance of ExecutionPlanProcessor (or subclass) for this statement.

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

createSqlCountProcessor

protected SqlCountProcessor createSqlCountProcessor()

Returns:

New instance of SqlCountProcessor (or subclass) for this statement.

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

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

addStatementListener

public final void addStatementListener(StatementListener statementListener)

Description copied from interface: FbStatement

Registers a StatementListener.

Specified by:

addStatementListener in interface FbStatement

Parameters:

statementListener - The row listener

removeStatementListener

public final void removeStatementListener(StatementListener statementListener)

Description copied from interface: FbStatement

Removes a StatementListener.

Specified by:

removeStatementListener in interface FbStatement

Parameters:

statementListener - The row listener

addExceptionListener

public final void addExceptionListener(ExceptionListener listener)

Description copied from interface: ExceptionListenable

Adds an exception listener to this object.

Implementations use WeakReference.

Specified by:

addExceptionListener in interface ExceptionListenable

Parameters:

listener - Listener to register

removeExceptionListener

public final void removeExceptionListener(ExceptionListener listener)

Description copied from interface: ExceptionListenable

Removes an exception listener to this object.

Specified by:

removeExceptionListener in interface ExceptionListenable

Parameters:

listener - Listener to remove

checkStatementValid

protected final void checkStatementValid()
                                  throws java.sql.SQLException

Checks if this statement is not in StatementState.CLOSED, StatementState.CLOSING, StatementState.NEW or StatementState.ERROR, and throws an SQLException if it is.

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

getTransaction

public FbTransaction getTransaction()

Specified by:

getTransaction in interface FbStatement

Returns:

Transaction currently associated with this statement

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

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)