Module org.firebirdsql.jaybird

Package org.firebirdsql.jdbc

Class FBStatement

java.lang.Object

org.firebirdsql.jdbc.AbstractStatement

org.firebirdsql.jdbc.FBStatement

All Implemented Interfaces:

AutoCloseable, Statement, Wrapper, FirebirdStatement

Direct Known Subclasses:

FBPreparedStatement

@InternalApi
@NullMarked
public class FBStatement
extends AbstractStatement
implements FirebirdStatement

Implementation of Statement.

This class is internal API of Jaybird. Future versions may radically change, move, or make inaccessible this type. For the public API, refer to the Statement and FirebirdStatement interfaces.

Author:

David Jencks, Mark Rotteveel

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
protected static enum	FBStatement.StatementResult	The current result of a statement.

Field Summary

Fields

Modifier and Type	Field	Description
protected FBStatement.StatementResult	currentStatementResult
protected final FbStatement	fbStatement
protected final GDSHelper	gdsHelper
protected boolean	isSingletonResult
protected final List<RowValue>	specialResult
protected final FBObjectListener.StatementListener	statementListener

Fields inherited from class org.firebirdsql.jdbc.AbstractStatement

connection

Fields inherited from interface java.sql.Statement

CLOSE_ALL_RESULTS, CLOSE_CURRENT_RESULT, EXECUTE_FAILED, KEEP_CURRENT_RESULT, NO_GENERATED_KEYS, RETURN_GENERATED_KEYS, SUCCESS_NO_INFO

Constructor Summary

Constructors

Modifier	Constructor	Description
protected	FBStatement(FBConnection connection, ResultSetBehavior rsBehavior, FBObjectListener.StatementListener statementListener)

Method Summary

Modifier and Type	Method	Description
void	addBatch(String sql)
void	cancel()
void	clearBatch()
void	close()
void	completeStatement(CompletionReason reason)	Completes this statement with reason.
protected final BatchUpdateException	createBatchUpdateException(String reason, @Nullable String sqlState, int vendorCode, List<? extends Number> updateCounts, Throwable cause)
protected final BatchUpdateException	createBatchUpdateException(SQLException cause, List<? extends Number> updateCounts)
protected FBResultSet	createSpecialResultSet(@Nullable FBObjectListener.ResultSetListener resultSetListener)	Create the result set for specialResult.
protected StatementListener	createStatementListener()	Creates the StatementListener to be associated with the instance of FbStatement created for this FBStatement or subclasses.
String	enquoteIdentifier(String identifier, boolean alwaysQuote)	Returns a SQL identifier.
String	enquoteLiteral(String val)	Returns a String enclosed in single quotes.
String	enquoteNCharLiteral(String val)
boolean	execute(String sql)
boolean	execute(String sql, int autoGeneratedKeys)
boolean	execute(String sql, int[] columnIndexes)
boolean	execute(String sql, String[] columnNames)
final int[]	executeBatch()
protected List<Long>	executeBatchInternal()
protected boolean	executeImpl(String sql)	Internal implementation of execute(String), so it can be used for normal queries and for queries returning generated keys.
final long[]	executeLargeBatch()
final long	executeLargeUpdate(String sql)
final long	executeLargeUpdate(String sql, int autoGeneratedKeys)
final long	executeLargeUpdate(String sql, int[] columnIndexes)
final long	executeLargeUpdate(String sql, String[] columnNames)
ResultSet	executeQuery(String sql)
int	executeUpdate(String sql)
int	executeUpdate(String sql, int autoGeneratedKeys)
int	executeUpdate(String sql, int[] columnIndexes)
int	executeUpdate(String sql, String[] columnNames)
@Nullable ResultSet	getCurrentResultSet()	Deprecated, for removal: This API element is subject to removal in a future version. Use getResultSet() instead, will be removed in Jaybird 7
int	getDeletedRowsCount()	Get number of deleted rows.
final @Nullable String	getExecutionPlan()	Gets the simple execution plan of the statement.
final @Nullable String	getExplainedExecutionPlan()	Gets the explained (or detailed) execution plan of the statement.
ResultSet	getGeneratedKeys()
int	getInsertedRowsCount()	Get number of inserted rows.
long	getLargeUpdateCount()
protected final long	getLargeUpdateCountMinZero()	Equivalent of getLargeUpdateCount(), with a minimum value of zero.
int	getMaxFieldSize()
boolean	getMoreResults()
boolean	getMoreResults(int mode)
int	getQueryTimeout()
@Nullable ResultSet	getResultSet()
protected @Nullable FBResultSet	getResultSet(boolean metaDataQuery)
protected final FbStatement	getStatementHandle()
final int	getStatementType()	Get the current statement type of this statement.
int	getUpdateCount()
protected final int	getUpdateCountMinZero()	Equivalent of getUpdateCount(), with a minimum value of zero.
int	getUpdatedRowsCount()	Get number of updated rows.
boolean	hasOpenResultSet()	Check if this statement has open result set.
protected boolean	internalExecute(String sql)
protected boolean	internalExecute(RowValue rowValue)
protected boolean	isGeneratedKeyQuery()
boolean	isSimpleIdentifier(String identifier)
boolean	isValid()	Check if this statement is valid.
boolean	isWrapperFor(Class<?> iface)
protected String	nativeSQL(String sql)
protected void	notifyStatementCompleted()	Notifies statement completion.
protected void	notifyStatementCompleted(boolean success)	Notifies statement completion.
protected void	notifyStatementStarted()
protected void	notifyStatementStarted(boolean closeResultSet)
protected void	prepareFixedStatement(String sql)
void	setEscapeProcessing(boolean enable)
void	setMaxFieldSize(int max)
void	setQueryTimeout(int seconds)
<T> T	unwrap(Class<T> iface)

Methods inherited from class org.firebirdsql.jdbc.AbstractStatement

addWarning, checkValidity, clearWarnings, closeOnCompletion, completeStatement, equals, fetchConfig, getConnection, getCursorName, getFetchDirection, getFetchSize, getLargeMaxRows, getLocalStatementId, getMaxRows, getResultSetConcurrency, getResultSetHoldability, getResultSetType, getWarnings, hashCode, isClosed, isCloseOnCompletion, isPoolable, performCloseOnCompletion, resultSetBehavior, setCursorName, setFetchDirection, setFetchSize, setLargeMaxRows, setMaxRows, setPoolable, withLock

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface org.firebirdsql.jdbc.FirebirdStatement

getLastExecutionPlan, getLastExplainedExecutionPlan, getLocalStatementId

Methods inherited from interface java.sql.Statement

clearWarnings, closeOnCompletion, getConnection, getFetchDirection, getFetchSize, getLargeMaxRows, getMaxRows, getResultSetConcurrency, getResultSetHoldability, getResultSetType, getWarnings, isClosed, isCloseOnCompletion, isPoolable, setCursorName, setFetchDirection, setFetchSize, setLargeMaxRows, setMaxRows, setPoolable

Field Details

gdsHelper

protected final GDSHelper gdsHelper

statementListener

protected final FBObjectListener.StatementListener statementListener

fbStatement

protected final FbStatement fbStatement

currentStatementResult

protected FBStatement.StatementResult currentStatementResult

isSingletonResult

protected boolean isSingletonResult

specialResult

protected final List<RowValue> specialResult

Constructor Details

FBStatement

protected FBStatement(FBConnection connection,
 ResultSetBehavior rsBehavior,
 FBObjectListener.StatementListener statementListener)
               throws SQLException

Throws:

SQLException

Method Details

isValid

public boolean isValid()

Description copied from interface: FirebirdStatement

Check if this statement is valid.

Specified by:

isValid in interface FirebirdStatement

Overrides:

isValid in class AbstractStatement

Returns:

true if statement is valid and can be used to execute SQL.

completeStatement

public void completeStatement(CompletionReason reason)
                       throws SQLException

Description copied from class: AbstractStatement

Completes this statement with reason.

On completion, any open result set will be closed, and possibly the statement itself may be closed.

Specified by:

completeStatement in class AbstractStatement

Parameters:

reason - completion reason

Throws:

SQLException - for failures completing this statement

executeQuery

public ResultSet executeQuery(String sql)
                       throws SQLException

Specified by:

executeQuery in interface Statement

Throws:

SQLException

notifyStatementStarted

protected void notifyStatementStarted()
                               throws SQLException

Throws:

SQLException

notifyStatementStarted

protected void notifyStatementStarted(boolean closeResultSet)
                               throws SQLException

Throws:

SQLException

notifyStatementCompleted

protected void notifyStatementCompleted()
                                 throws SQLException

Notifies statement completion.

Equivalent to notifyStatementCompleted(true)

Throws:

SQLException - exception from handling statement completion (e.g. commit or rollback in auto-commit)

See Also:

• notifyStatementCompleted(boolean)

notifyStatementCompleted

protected void notifyStatementCompleted(boolean success)
                                 throws SQLException

Notifies statement completion.

Use of success = false should not be generally used for failing execution. The only difference between true and false is whether completion triggers commit or rollback in auto-commit mode, and in general, even for failed execution, a commit should be triggered. The only exception is for batch execution in auto-commit, where we rollback if one statement failed (and this behaviour is specified by JDBC as implementation-specific), and ending a transaction if statement preparation failed in FBPreparedStatement.

Parameters:

success - true notify successful completion, false for unsuccessful completion

Throws:

SQLException - exception from handling statement completion (e.g. commit or rollback in auto-commit)

executeUpdate

public int executeUpdate(String sql)
                  throws SQLException

Specified by:

executeUpdate in interface Statement

Throws:

SQLException

executeUpdate

public int executeUpdate(String sql,
 int autoGeneratedKeys)
                  throws SQLException

Specified by:

executeUpdate in interface Statement

Throws:

SQLException

executeUpdate

public int executeUpdate(String sql,
 int[] columnIndexes)
                  throws SQLException

Specified by:

executeUpdate in interface Statement

Throws:

SQLException

executeUpdate

public int executeUpdate(String sql,
 String[] columnNames)
                  throws SQLException

Specified by:

executeUpdate in interface Statement

Throws:

SQLException

execute

public boolean execute(String sql,
 int autoGeneratedKeys)
                throws SQLException

Specified by:

execute in interface Statement

Throws:

SQLException

execute

public boolean execute(String sql,
 int[] columnIndexes)
                throws SQLException

Specified by:

execute in interface Statement

Throws:

SQLException

execute

public boolean execute(String sql,
 String[] columnNames)
                throws SQLException

Specified by:

execute in interface Statement

Throws:

SQLException

getGeneratedKeys

public ResultSet getGeneratedKeys()
                           throws SQLException

Specified by:

getGeneratedKeys in interface Statement

Throws:

SQLException

close

public void close()
           throws SQLException

Description copied from class: AbstractStatement

Subclasses overriding this method are expected to call this method with super.close() at an appropriate point to mark it closed.

Specified by:

close in interface AutoCloseable

Specified by:

close in interface Statement

Overrides:

close in class AbstractStatement

Throws:

SQLException

getMaxFieldSize

public int getMaxFieldSize()
                    throws SQLException

Specified by:

getMaxFieldSize in interface Statement

Throws:

SQLException

setMaxFieldSize

public void setMaxFieldSize(int max)
                     throws SQLException

Specified by:

setMaxFieldSize in interface Statement

Throws:

SQLException

setEscapeProcessing

public void setEscapeProcessing(boolean enable)
                         throws SQLException

Specified by:

setEscapeProcessing in interface Statement

Throws:

SQLException

getQueryTimeout

public int getQueryTimeout()
                    throws SQLException

Firebird 4 and higher also support attachment level and global statement timeouts. This method only reports the value explicitly configured for this statement. In practice, a more stringent timeout might be applied by this attachment level or global statement timeout.

Specified by:

getQueryTimeout in interface Statement

Throws:

SQLException

See Also:

• setQueryTimeout(int)

setQueryTimeout

public void setQueryTimeout(int seconds)
                     throws SQLException

Query timeout is only supported on Firebird 4 and higher, and only for the pure-java wire protocol implementation. For earlier versions or native/embedded connections, the timeout is ignored. The maximum timeout for Firebird 4 is 4294967 seconds, higher values will be handled as if 0 was set. Firebird 4 also has attachment level and global statement timeouts. This configuration governs the statement level statement timeout only. In practice, a more stringent timeout might be applied by this attachment level or global statement timeout.

Important: Query timeouts in Firebird 4 and higher have an important caveat: for result set producing statements, the timeout covers the time from execution start until the cursor is closed. This includes the time that Firebird waits for your application to fetch more rows. This means that if you execute a SELECT and take your time processing the results, the statement may be cancelled even when Firebird itself returns rows quickly.

A query timeout is not applied for execution of DDL.

Specified by:

setQueryTimeout in interface Statement

Throws:

SQLException

cancel

public void cancel()
            throws SQLException

Specified by:

cancel in interface Statement

Throws:

SQLException

execute

public boolean execute(String sql)
                throws SQLException

Specified by:

execute in interface Statement

Throws:

SQLException

executeImpl

protected boolean executeImpl(String sql)
                       throws SQLException

Internal implementation of execute(String), so it can be used for normal queries and for queries returning generated keys.

Throws:

SQLException

See Also:

• execute(String)

getResultSet

public @Nullable ResultSet getResultSet()
                                 throws SQLException

Specified by:

getResultSet in interface Statement

Throws:

SQLException

getResultSet

protected @Nullable FBResultSet getResultSet(boolean metaDataQuery)
                                      throws SQLException

Throws:

SQLException

createSpecialResultSet

protected FBResultSet createSpecialResultSet(@Nullable FBObjectListener.ResultSetListener resultSetListener)
                                      throws SQLException

Create the result set for specialResult.

Should only be called from getResultSet(boolean). This exists because FBCallableStatement needs to create the result set in a slightly different way to account for the fact that the blobs were already cached earlier.

Parameters:

resultSetListener - result set listener (can be null)

Returns:

result set wrapping specialResult

Throws:

SQLException

hasOpenResultSet

public boolean hasOpenResultSet()

Description copied from interface: FirebirdStatement

Check if this statement has open result set. Note, this method works correctly if auto-commit is disabled. In auto-commit mode it will always return false because from the statement's point of view result set is not open (in auto-commit mode complete result set is fetched and cached in wrapping object before returning from the Statement.getResultSet() method).

Specified by:

hasOpenResultSet in interface FirebirdStatement

Returns:

true if there's already open result set associated with this statement, otherwise false.

getUpdateCountMinZero

protected final int getUpdateCountMinZero()
                                   throws SQLException

Equivalent of getUpdateCount(), with a minimum value of zero.

For use in executeUpdate methods as the API mandates 0 instead of -1 for no results, and in (emulated) executeBatch methods for consistency with server-side batch execution.

Throws:

SQLException

See Also:

• getLargeUpdateCountMinZero()

getUpdateCount

public int getUpdateCount()
                   throws SQLException

Specified by:

getUpdateCount in interface Statement

Throws:

SQLException

getDeletedRowsCount

public int getDeletedRowsCount()
                        throws SQLException

Description copied from interface: FirebirdStatement

Get number of deleted rows. You can call this method multiple times, it does not affect the JDBC result number.

Specified by:

getDeletedRowsCount in interface FirebirdStatement

Returns:

number of deleted rows or -1 if current result is result set.

Throws:

SQLException - if database error occurs.

getInsertedRowsCount

public int getInsertedRowsCount()
                         throws SQLException

Description copied from interface: FirebirdStatement

Get number of inserted rows. You can call this method multiple times, it does not affect the JDBC result number.

Specified by:

getInsertedRowsCount in interface FirebirdStatement

Returns:

number of inserted rows or -1 if current result is result set.

Throws:

SQLException - if database error occurs.

getUpdatedRowsCount

public int getUpdatedRowsCount()
                        throws SQLException

Description copied from interface: FirebirdStatement

Get number of updated rows. You can call this method multiple times, it does not affect the JDBC result number.

Specified by:

getUpdatedRowsCount in interface FirebirdStatement

Returns:

number of updated rows or -1 if current result is result set.

Throws:

SQLException - if database error occurs.

getMoreResults

public boolean getMoreResults()
                       throws SQLException

Specified by:

getMoreResults in interface Statement

Throws:

SQLException

getMoreResults

public boolean getMoreResults(int mode)
                       throws SQLException

Specified by:

getMoreResults in interface Statement

Throws:

SQLException

addBatch

public void addBatch(String sql)
              throws SQLException

Specified by:

addBatch in interface Statement

Throws:

SQLException

clearBatch

public void clearBatch()
                throws SQLException

Specified by:

clearBatch in interface Statement

Throws:

SQLException

executeBatch

public final int[] executeBatch()
                         throws SQLException

Specified by:

executeBatch in interface Statement

Throws:

SQLException

executeBatchInternal

protected List<Long> executeBatchInternal()
                                   throws SQLException

Throws:

SQLException

createBatchUpdateException

protected final BatchUpdateException createBatchUpdateException(SQLException cause,
 List<? extends Number> updateCounts)

createBatchUpdateException

protected final BatchUpdateException createBatchUpdateException(String reason,
 @Nullable String sqlState,
 int vendorCode,
 List<? extends Number> updateCounts,
 Throwable cause)

getStatementHandle

protected final FbStatement getStatementHandle()
                                        throws SQLException

Specified by:

getStatementHandle in class AbstractStatement

Returns:

instance of FbStatement associated with this statement; cannot be null

Throws:

SQLException - if this statement is closed

SQLFeatureNotSupportedException - if this statement implementation does not use statement handles

getCurrentResultSet

@Deprecated(since="6",
            forRemoval=true)
public @Nullable ResultSet getCurrentResultSet()
                                        throws SQLException

Deprecated, for removal: This API element is subject to removal in a future version.

Use getResultSet() instead, will be removed in Jaybird 7

Get current result set. Behaviour of this method is similar to the behavior of the Statement.getResultSet().

Specified by:

getCurrentResultSet in interface FirebirdStatement

Returns:

instance of ResultSet representing current result set or null if it is not available.

Throws:

SQLException - if a database access error happens

isWrapperFor

public boolean isWrapperFor(Class<?> iface)
                     throws SQLException

Specified by:

isWrapperFor in interface Wrapper

Throws:

SQLException

unwrap

public <T> T unwrap(Class<T> iface)
             throws SQLException

Specified by:

unwrap in interface Wrapper

Throws:

SQLException

internalExecute

protected boolean internalExecute(String sql)
                           throws SQLException

Throws:

SQLException

internalExecute

protected boolean internalExecute(RowValue rowValue)
                           throws SQLException

Throws:

SQLException

prepareFixedStatement

protected void prepareFixedStatement(String sql)
                              throws SQLException

Throws:

SQLException

nativeSQL

protected String nativeSQL(String sql)
                    throws SQLException

Throws:

SQLException

isGeneratedKeyQuery

protected boolean isGeneratedKeyQuery()

Returns:

true when the current statement is expected to return generated keys, false otherwise.

getExecutionPlan

public final @Nullable String getExecutionPlan()
                                        throws SQLException

Description copied from interface: FirebirdStatement

Gets the simple execution plan of the statement.

Behaviour depends on the specific type:

• Statement but not PreparedStatement — returns the plan of the last executed statement
• PreparedStatement — returns the plan of the prepared statement
• CallableStatement — is not guaranteed to return the plan until after the first execution

Specified by:

getExecutionPlan in interface FirebirdStatement

Returns:

execution plan returned by the server

Throws:

SQLException - if no statement was executed or prepared before calling this method, if the statement is not valid or open, or there was an error when obtaining the execution plan

See Also:

• FirebirdStatement.getExplainedExecutionPlan()

getExplainedExecutionPlan

public final @Nullable String getExplainedExecutionPlan()
                                                 throws SQLException

Description copied from interface: FirebirdStatement

Gets the explained (or detailed) execution plan of the statement.

The explained execution plan is a more structured and comprehensible form compared to the (simple) execution plan returned by FirebirdStatement.getExecutionPlan(). This requires Firebird 3.0 or higher.

Behaviour depends on the specific type:

• Statement but not PreparedStatement — returns the plan of the last executed statement
• PreparedStatement — returns the plan of the prepared statement
• CallableStatement — is not guaranteed to return the plan until after the first execution

Specified by:

getExplainedExecutionPlan in interface FirebirdStatement

Returns:

execution plan returned by the server

Throws:

SQLException - if no statement was executed or prepared before calling this method, if the statement is not valid or open, or there was an error when obtaining the execution plan

See Also:

• FirebirdStatement.getExecutionPlan()

getStatementType

public final int getStatementType()

Description copied from class: AbstractStatement

Get the current statement type of this statement.

The returned value is one of the TYPE_* constant values defined in FirebirdPreparedStatement, or 0 if the statement currently does not have a statement type.

Specified by:

getStatementType in class AbstractStatement

Returns:

The identifier for the given statement's type

getLargeUpdateCountMinZero

protected final long getLargeUpdateCountMinZero()
                                         throws SQLException

Equivalent of getLargeUpdateCount(), with a minimum value of zero.

For use in executeLargeUpdate methods as the API mandates 0 instead of -1 for no results, and in (emulated) executeBatch methods for consistency with server-side batch execution.

Throws:

SQLException

See Also:

• getUpdateCountMinZero()

getLargeUpdateCount

public long getLargeUpdateCount()
                         throws SQLException

Specified by:

getLargeUpdateCount in interface Statement

Throws:

SQLException

executeLargeBatch

public final long[] executeLargeBatch()
                               throws SQLException

Specified by:

executeLargeBatch in interface Statement

Throws:

SQLException

executeLargeUpdate

public final long executeLargeUpdate(String sql)
                              throws SQLException

Specified by:

executeLargeUpdate in interface Statement

Throws:

SQLException

executeLargeUpdate

public final long executeLargeUpdate(String sql,
 int autoGeneratedKeys)
                              throws SQLException

Specified by:

executeLargeUpdate in interface Statement

Throws:

SQLException

executeLargeUpdate

public final long executeLargeUpdate(String sql,
 int[] columnIndexes)
                              throws SQLException

Specified by:

executeLargeUpdate in interface Statement

Throws:

SQLException

executeLargeUpdate

public final long executeLargeUpdate(String sql,
 String[] columnNames)
                              throws SQLException

Specified by:

executeLargeUpdate in interface Statement

Throws:

SQLException

enquoteLiteral

public String enquoteLiteral(String val)
                      throws SQLException

Returns a String enclosed in single quotes. Any occurrence of a single quote within the string will be replaced by two single quotes.

For a dialect 3 database, this will behave exactly like the JDBC 4.3 default implementation. For a dialect 1 database this will quote literals with double quotes and escape double quotes by doubling.

Specified by:

enquoteLiteral in interface Statement

Parameters:

val - a character string

Returns:

A string enclosed by single quotes with every single quote converted to two single quotes

Throws:

NullPointerException - if val is null

SQLException - if a database access error occurs

enquoteNCharLiteral

public String enquoteNCharLiteral(String val)
                           throws SQLException

Specified by:

enquoteNCharLiteral in interface Statement

Throws:

SQLException

See Also:

• enquoteLiteral(String)

enquoteIdentifier

public String enquoteIdentifier(String identifier,
 boolean alwaysQuote)
                         throws SQLException

Returns a SQL identifier. If identifier is a simple SQL identifier:

• Return the original value if alwaysQuote is false
• Return a delimited identifier if alwaysQuote is true

Specified by:

enquoteIdentifier in interface Statement

Parameters:

identifier - a SQL identifier

alwaysQuote - indicates if a simple SQL identifier should be returned as a quoted identifier

Returns:

A simple SQL identifier or a delimited identifier

Throws:

SQLException - if identifier is not a valid identifier

SQLFeatureNotSupportedException - if the datasource does not support delimited identifiers (ie: a dialect 1 database)

NullPointerException - if identifier is null

isSimpleIdentifier

public boolean isSimpleIdentifier(String identifier)
                           throws SQLException

Specified by:

isSimpleIdentifier in interface Statement

Throws:

SQLException

createStatementListener

protected StatementListener createStatementListener()

Creates the StatementListener to be associated with the instance of FbStatement created for this FBStatement or subclasses.

Returns:

instance of StatementListener