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 Description protected ExceptionListenerDispatcherexceptionListenerDispatcherprotected StatementListenerDispatcherstatementListenerDispatcher
-
Constructor Summary
Constructors Modifier Constructor Description protectedAbstractFbStatement(java.lang.Object syncObject)
-
Method Summary
All Methods Instance Methods Abstract Methods Concrete Methods Deprecated Methods Modifier and Type Method Description voidaddExceptionListener(ExceptionListener listener)Adds an exception listener to this object.voidaddStatementListener(StatementListener statementListener)Registers aStatementListener.protected voidcheckStatementValid()Checks if this statement is not inStatementState.CLOSED,StatementState.CLOSING,StatementState.NEWorStatementState.ERROR, and throws anSQLExceptionif it is.protected voidcheckStatementValid(StatementState ignoreState)Performs the same check ascheckStatementValid(), but considersignoreStateas valid.voidclose()Close and deallocate this statement.voidcloseCursor()Closes the cursor associated with this statement, leaving the statement itself allocated.voidcloseCursor(boolean transactionEnd)Closes the cursor associated with this statement, leaving the statement itself allocated.protected ExecutionPlanProcessorcreateExecutionPlanProcessor()protected SqlCountProcessorcreateSqlCountProcessor()voidensureClosedCursor(boolean transactionEnd)Ensures that the statement cursor is closed.protected voidfinalize()protected abstract voidfree(int option)Frees the currently allocated statement (either close the cursor withISCConstants.DSQL_closeor drop the statement handle usingISCConstants.DSQL_drop.protected longgetAllowedTimeout()java.lang.StringgetExecutionPlan()java.lang.StringgetExplainedExecutionPlan()RowDescriptorgetFieldDescriptor()Deprecated.byte[]getParameterDescriptionInfoRequestItems()RowDescriptorgetParameterDescriptor()RowDescriptorgetRowDescriptor()SqlCountHoldergetSqlCounts()Retrieves the SQL counts for the last execution of this statement.<T> TgetSqlInfo(byte[] requestItems, int bufferLength, InfoProcessor<T> infoProcessor)Request statement info.StatementStategetState()byte[]getStatementInfoRequestItems()protected WarningMessageCallbackgetStatementWarningCallback()protected java.lang.ObjectgetSynchronizationObject()Get synchronization object.longgetTimeout()Gets the current statement timeout for this statement.FbTransactiongetTransaction()protected TransactionListenergetTransactionListener()Gets theTransactionListenerinstance for this statement.StatementTypegetType()protected booleanhasFields()protected booleanhasSingletonResult()protected booleanisAllRowsFetched()protected booleanisPrepareAllowed(StatementState state)Is a call toFbStatement.prepare(String)allowed for the suppliedStatementState.protected abstract booleanisValidTransactionClass(java.lang.Class<? extends FbTransaction> transactionClass)Method to decide if a transaction implementation class is valid for the statement implementation.protected voidparseStatementInfo(byte[] statementInfoResponse)Parse the statement info response instatementInfoResponse.protected voidqueueRowData(RowValue rowData)Queues row data for consumptionvoidremoveExceptionListener(ExceptionListener listener)Removes an exception listener to this object.voidremoveStatementListener(StatementListener statementListener)Removes aStatementListener.protected voidreset()Reset statement state, equivalent to callingreset(boolean)withfalseprotected voidreset(boolean resetAll)Resets the statement for next execution.protected voidresetAll()Reset statement state and clear parameter description, equivalent to callingreset(boolean)withtrueprotected voidsetAllRowsFetched(boolean allRowsFetched)Sets theallRowsFetchedproperty.protected voidsetFieldDescriptor(RowDescriptor fieldDescriptor)Deprecated.UsesetRowDescriptor(RowDescriptor)instead; will be removed in Jaybird 5protected voidsetParameterDescriptor(RowDescriptor parameterDescriptor)Sets the parameter descriptor.protected voidsetRowDescriptor(RowDescriptor rowDescriptor)Sets the (result set) row descriptor.voidsetTimeout(long statementTimeout)Sets the statement timeout.voidsetTransaction(FbTransaction newTransaction)Associates a transaction with this statementprotected voidsetType(StatementType type)Sets the StatementTypeprotected OperationCloseHandlesignalExecute()Signals the start of an execute for this statement.protected OperationCloseHandlesignalFetch()Signals the start of a fetch for this statement.protected voidswitchState(StatementState newState)Sets the StatementState.voidvalidateParameters(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
-
-
Method Detail
-
getTransactionListener
protected final TransactionListener getTransactionListener()
Gets theTransactionListenerinstance 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.SQLExceptionDescription copied from interface:FbStatementClose and deallocate this statement.- Specified by:
closein interfaceFbStatement- Throws:
java.sql.SQLException
-
closeCursor
public final void closeCursor() throws java.sql.SQLExceptionDescription copied from interface:FbStatementCloses the cursor associated with this statement, leaving the statement itself allocated.Equivalent to calling
FbStatement.closeCursor(boolean)withfalse.- Specified by:
closeCursorin interfaceFbStatement- Throws:
java.sql.SQLException
-
closeCursor
public final void closeCursor(boolean transactionEnd) throws java.sql.SQLExceptionDescription copied from interface:FbStatementCloses 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:
closeCursorin interfaceFbStatement- Parameters:
transactionEnd- Close is in response to a transaction end.- Throws:
java.sql.SQLException
-
ensureClosedCursor
public final void ensureClosedCursor(boolean transactionEnd) throws java.sql.SQLExceptionDescription copied from interface:FbStatementEnsures 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:
ensureClosedCursorin interfaceFbStatement- 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:
getStatein interfaceFbStatement- 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:
getTypein interfaceFbStatement- 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 theallRowsFetchedproperty.When set to true all registered
StatementListenerinstances are notified for theStatementListener.allRowsFetched(FbStatement)event.- Parameters:
allRowsFetched-true: all rows fetched,falsenot all rows fetched.
-
isAllRowsFetched
protected final boolean isAllRowsFetched()
-
reset
protected final void reset()
Reset statement state, equivalent to callingreset(boolean)withfalse
-
resetAll
protected final void resetAll()
Reset statement state and clear parameter description, equivalent to callingreset(boolean)withtrue
-
reset
protected void reset(boolean resetAll)
Resets the statement for next execution. Implementation in derived class must synchronize ongetSynchronizationObject()and callsuper.reset(resetAll)- Parameters:
resetAll- Also reset field and parameter info
-
isPrepareAllowed
protected boolean isPrepareAllowed(StatementState state)
Is a call toFbStatement.prepare(String)allowed for the suppliedStatementState.- Parameters:
state- The statement state- Returns:
truecall toprepareis allowed
-
getParameterDescriptor
public final RowDescriptor getParameterDescriptor()
- Specified by:
getParameterDescriptorin interfaceFbStatement- Returns:
- descriptor of the parameters of this statement
-
setParameterDescriptor
protected void setParameterDescriptor(RowDescriptor parameterDescriptor)
Sets the parameter descriptor.- Parameters:
parameterDescriptor- Parameter descriptor
-
getFieldDescriptor
@Deprecated public final RowDescriptor getFieldDescriptor()
Deprecated.- Specified by:
getFieldDescriptorin interfaceFbStatement- Returns:
- descriptor of the fields returned by this statement
-
setFieldDescriptor
@Deprecated protected void setFieldDescriptor(RowDescriptor fieldDescriptor)
Deprecated.UsesetRowDescriptor(RowDescriptor)instead; will be removed in Jaybird 5Sets the (result set) field descriptor.- Parameters:
fieldDescriptor- Field descriptor
-
getRowDescriptor
public final RowDescriptor getRowDescriptor()
- Specified by:
getRowDescriptorin interfaceFbStatement- Returns:
- descriptor of the row returned by this statement
-
setRowDescriptor
protected void setRowDescriptor(RowDescriptor rowDescriptor)
Sets the (result set) row descriptor.- Parameters:
rowDescriptor- Row 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_varsinfo request items. - See Also:
getStatementInfoRequestItems()
-
getSqlInfo
public final <T> T getSqlInfo(byte[] requestItems, int bufferLength, InfoProcessor<T> infoProcessor) throws java.sql.SQLExceptionRequest statement info.- Specified by:
getSqlInfoin interfaceFbStatement- Parameters:
requestItems- Array of info items to requestbufferLength- Response buffer length to useinfoProcessor- Implementation ofInfoProcessorto 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:
getExecutionPlanin interfaceFbStatement- 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:
getExplainedExecutionPlanin interfaceFbStatement- Returns:
- The detailed 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:FbStatementRetrieves the SQL counts for the last execution of this statement.The retrieved SQL counts are also notified to all registered
StatementListeners.In general the
FbStatementwill (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:
getSqlCountsin interfaceFbStatement- 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 stateStatementState.CURSOR_OPENand 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.SQLExceptionFrees the currently allocated statement (either close the cursor withISCConstants.DSQL_closeor drop the statement handle usingISCConstants.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:FbStatementValidates if the number of parameters matches the expected number and types, and if all values have been set.- Specified by:
validateParametersin interfaceFbStatement- Parameters:
parameters- Parameter values to validate- Throws:
java.sql.SQLException- When the number or type of parameters does not matchFbStatement.getParameterDescriptor(), or when a parameter has not been set.
-
addStatementListener
public final void addStatementListener(StatementListener statementListener)
Description copied from interface:FbStatementRegisters aStatementListener.- Specified by:
addStatementListenerin interfaceFbStatement- Parameters:
statementListener- The row listener
-
removeStatementListener
public final void removeStatementListener(StatementListener statementListener)
Description copied from interface:FbStatementRemoves aStatementListener.- Specified by:
removeStatementListenerin interfaceFbStatement- Parameters:
statementListener- The row listener
-
addExceptionListener
public final void addExceptionListener(ExceptionListener listener)
Description copied from interface:ExceptionListenableAdds an exception listener to this object.Implementations use
WeakReference.- Specified by:
addExceptionListenerin interfaceExceptionListenable- Parameters:
listener- Listener to register
-
removeExceptionListener
public final void removeExceptionListener(ExceptionListener listener)
Description copied from interface:ExceptionListenableRemoves an exception listener to this object.- Specified by:
removeExceptionListenerin interfaceExceptionListenable- Parameters:
listener- Listener to remove
-
checkStatementValid
protected final void checkStatementValid() throws java.sql.SQLExceptionChecks if this statement is not inStatementState.CLOSED,StatementState.CLOSING,StatementState.NEWorStatementState.ERROR, and throws anSQLExceptionif it is.- Throws:
java.sql.SQLException- When this statement is closed or in error state.
-
checkStatementValid
protected final void checkStatementValid(StatementState ignoreState) throws java.sql.SQLException
Performs the same check ascheckStatementValid(), but considersignoreStateas valid.- Parameters:
ignoreState- The invalid state (seecheckStatementValid()to ignore- Throws:
java.sql.SQLException- When this statement is closed or in error state.
-
finalize
protected void finalize() throws java.lang.Throwable- Overrides:
finalizein classjava.lang.Object- Throws:
java.lang.Throwable
-
getTransaction
public FbTransaction getTransaction()
- Specified by:
getTransactionin interfaceFbStatement- 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
V10Statementwill only work with anFbWireTransactionimplementation.- Parameters:
transactionClass- Class of the transaction- Returns:
truewhen the transaction class is valid for the statement implementation.
-
setTransaction
public final void setTransaction(FbTransaction newTransaction) throws java.sql.SQLException
Description copied from interface:FbStatementAssociates a transaction with this statement- Specified by:
setTransactionin interfaceFbStatement- Parameters:
newTransaction- The transaction- Throws:
java.sql.SQLException
-
setTimeout
public void setTimeout(long statementTimeout) throws java.sql.SQLExceptionDescription copied from interface:FbStatementSets 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:
setTimeoutin interfaceFbStatement- 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.SQLExceptionDescription copied from interface:FbStatementGets 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:
getTimeoutin interfaceFbStatement- 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
0if the timeout is larger than supported - Throws:
java.sql.SQLException- If the statement is invalid
-
parseStatementInfo
protected void parseStatementInfo(byte[] statementInfoResponse) throws java.sql.SQLExceptionParse the statement info response instatementInfoResponse. If the response is truncated, a new request is done usinggetStatementInfoRequestItems()- Parameters:
statementInfoResponse- Statement info response- Throws:
java.sql.SQLException
-
hasSingletonResult
protected final boolean hasSingletonResult()
- Returns:
trueif this is a stored procedure (or other singleton result producing statement) with at least 1 output field
-
hasFields
protected final boolean hasFields()
- Returns:
trueif 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:
OperationCloseHandlehandle for the operation
-
signalFetch
protected final OperationCloseHandle signalFetch()
Signals the start of a fetch for this statement.- Returns:
OperationCloseHandlehandle for the operation
-
-