org.firebirdsql.gds.ng

Interface FbStatement

All Superinterfaces:

ExceptionListenable

All Known Subinterfaces:

FbWireStatement

All Known Implementing Classes:

AbstractFbStatement, AbstractFbWireStatement, JnaStatement, V10Statement, V11Statement, V12Statement, V13Statement

public interface FbStatement
extends ExceptionListenable

API for statement handles.

All methods defined in this interface are required to notify all SQLException thrown from the methods defined in this interface.

Since:

3.0

Author:

Mark Rotteveel

Method Summary

Modifier and Type	Method and Description
void	addStatementListener(StatementListener statementListener) Registers a StatementListener.
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.
RowDescriptor	emptyRowDescriptor()
void	ensureClosedCursor(boolean transactionEnd) Ensures that the statement cursor is closed.
void	execute(RowValue parameters) Execute the statement.
void	fetchRows(int fetchSize) Requests this statement to fetch the next fetchSize rows.
FbDatabase	getDatabase()
int	getDefaultSqlInfoSize()
java.lang.String	getExecutionPlan()
RowDescriptor	getFieldDescriptor()
int	getHandle()
int	getMaxSqlInfoSize()
RowDescriptor	getParameterDescriptor()
SqlCountHolder	getSqlCounts() Retrieves the SQL counts for the last execution of this statement.
byte[]	getSqlInfo(byte[] requestItems, int bufferLength) Request statement info.
<T> T	getSqlInfo(byte[] requestItems, int bufferLength, InfoProcessor<T> infoProcessor) Request statement info.
StatementState	getState()
FbTransaction	getTransaction()
StatementType	getType()
void	prepare(java.lang.String statementText) Prepare the statement text.
void	removeStatementListener(StatementListener statementListener) Removes a StatementListener.
void	setCursorName(java.lang.String cursorName) Sets the named cursor name for this statement.
void	setTransaction(FbTransaction transaction) Associates a transaction with this statement

Methods inherited from interface org.firebirdsql.gds.ng.listeners.ExceptionListenable

addExceptionListener, removeExceptionListener

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

getFieldDescriptor

RowDescriptor getFieldDescriptor()

Returns:

descriptor of the fields returned by this statement

getType

StatementType getType()

Returns:

The statement type

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.

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

Parameters:

transactionEnd - Close is in response to a transaction end.

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.

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

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

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.

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

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.

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