Module org.firebirdsql.jaybird

Package org.firebirdsql.jdbc

Interface FirebirdConnection

All Superinterfaces:

AutoCloseable, Connection, Wrapper

All Known Implementing Classes:

FBConnection

public interface FirebirdConnection
extends Connection

Extension of Connection interface providing access to Firebird specific features.

Since:

1.5

Author:

Roman Rokytskyy

Field Summary

Fields inherited from interface java.sql.Connection

TRANSACTION_NONE, TRANSACTION_READ_COMMITTED, TRANSACTION_READ_UNCOMMITTED, TRANSACTION_REPEATABLE_READ, TRANSACTION_SERIALIZABLE

Method Summary

Modifier and Type	Method	Description
Blob	createBlob()
TransactionParameterBuffer	createTransactionParameterBuffer()	Create new instance of TransactionParameterBuffer.
@NonNull String	enquoteIdentifier(@NonNull String identifier, boolean alwaysDelimit)	Returns a simple SQL identifier or a delimited identifier, as appropriate for the connection dialect.
@NonNull String	enquoteLiteral(@NonNull String val)	Returns a string appropriately quoted as a string literal for the connection dialect.
@NonNull String	enquoteNCharLiteral(@NonNull String val)	Returns a string appropriately quoted as a string literal for the connection dialect.
FbDatabase	getFbDatabase()	Provides access to the low-level connection handle.
TransactionParameterBuffer	getTransactionParameters(int isolationLevel)	Get transaction parameters for the specified transaction isolation level.
boolean	isSimpleIdentifier(@NonNull String identifier)	Returns whether identifier is a simple identifier.
boolean	isUseFirebirdAutoCommit()
void	resetKnownClientInfoProperties()	Resets the known client info properties of this connection to the defaults.
void	setTransactionParameters(int isolationLevel, int[] parameters)	Deprecated. use setTransactionParameters(int, TransactionParameterBuffer) instead.
void	setTransactionParameters(int isolationLevel, TransactionParameterBuffer tpb)	Set transaction parameters for the specified transaction isolation level.
void	setTransactionParameters(TransactionParameterBuffer tpb)	Set transaction parameters for the next transactions.

Methods inherited from interface java.sql.Connection

abort, beginRequest, clearWarnings, close, commit, createArrayOf, createClob, createNClob, createSQLXML, createStatement, createStatement, createStatement, createStruct, endRequest, getAutoCommit, getCatalog, getClientInfo, getClientInfo, getHoldability, getMetaData, getNetworkTimeout, getSchema, getTransactionIsolation, getTypeMap, getWarnings, isClosed, isReadOnly, isValid, nativeSQL, prepareCall, prepareCall, prepareCall, prepareStatement, prepareStatement, prepareStatement, prepareStatement, prepareStatement, prepareStatement, releaseSavepoint, rollback, rollback, setAutoCommit, setCatalog, setClientInfo, setClientInfo, setHoldability, setNetworkTimeout, setReadOnly, setSavepoint, setSavepoint, setSchema, setShardingKey, setShardingKey, setShardingKeyIfValid, setShardingKeyIfValid, setTransactionIsolation, setTypeMap

Methods inherited from interface java.sql.Wrapper

isWrapperFor, unwrap

Method Details

createBlob

Blob createBlob()
         throws SQLException

Specified by:

createBlob in interface Connection

Returns:

instance of FirebirdBlob.

Throws:

SQLException

setTransactionParameters

@Deprecated(since="2")
void setTransactionParameters(int isolationLevel,
 int[] parameters)
                       throws SQLException

Deprecated.

use setTransactionParameters(int, TransactionParameterBuffer) instead.

Set transaction parameters for the specified isolation level. They will take effect only on the newly started transaction.

Parameters:

isolationLevel - JDBC isolation level.

parameters - array of TPB parameters, see all TPB_* constants.

Throws:

SQLException - if specified transaction parameters cannot be set.

getTransactionParameters

TransactionParameterBuffer getTransactionParameters(int isolationLevel)
                                             throws SQLException

Get transaction parameters for the specified transaction isolation level.

Parameters:

isolationLevel - isolation level defined in the Connection interface.

Returns:

instance of TransactionParameterBuffer containing current transaction parameters.

Throws:

SQLException - if error occurred obtaining transaction parameters.

Since:

2

createTransactionParameterBuffer

TransactionParameterBuffer createTransactionParameterBuffer()
                                                     throws SQLException

Create new instance of TransactionParameterBuffer.

Returns:

empty instance of TransactionParameterBuffer.

Throws:

SQLException - if error occurred during this operation.

Since:

2

setTransactionParameters

void setTransactionParameters(int isolationLevel,
 TransactionParameterBuffer tpb)
                       throws SQLException

Set transaction parameters for the specified transaction isolation level.

This method replaces the default TPB mapping with the specified one, changes will be effective from the next transaction start.

Parameters:

tpb - instance of TransactionParameterBuffer with parameters to set.

Throws:

SQLException - if error occurred during this operation.

Since:

2

setTransactionParameters

void setTransactionParameters(TransactionParameterBuffer tpb)
                       throws SQLException

Set transaction parameters for the next transactions.

This method does not change the TPB mapping, but replaces the mapping for the current transaction isolation until Connection.setTransactionIsolation(int) is called.

This method cannot be called when a transaction is currently active.

Parameters:

tpb - instance of TransactionParameterBuffer with new transaction parameters.

Throws:

SQLException - if method is called within a transaction.

Since:

2

isUseFirebirdAutoCommit

boolean isUseFirebirdAutoCommit()

Returns:

true if this connection is configured to use isc_tpb_autocommit when in auto commit.

Since:

3

getFbDatabase

@InternalApi
FbDatabase getFbDatabase()
                  throws SQLException

Provides access to the low-level connection handle.

WARNING using this connection handle directly may bring the JDBC connection in an inconsistent state.

Returns:

The low-level connection handle.

Throws:

SQLException

Since:

3

resetKnownClientInfoProperties

void resetKnownClientInfoProperties()

Resets the known client info properties of this connection to the defaults. This does not reset the values of those properties on the server, but only resets the list of known properties held by this connection

If this connection is closed, this is effectively a no-op. Primary use-case for this method is to reset a connection held in a connection pool.

Since:

6

enquoteLiteral

@NonNull String enquoteLiteral(@NonNull String val)
                        throws SQLException

Returns a string appropriately quoted as a string literal for the connection dialect.

This method is defined in Connection starting with JDBC 4.5 (Java 26). The definition in this interface may be removed without notice once Jaybird only supports Java versions that expect JDBC 4.5 or higher.

Parameters:

val - a character string

Returns:

for dialect 3, a string enclosed by single quotes with every single quote converted to two single quotes, for dialect 1, with double quotes instead of single quotes.

Throws:

NullPointerException - if val is null

SQLException - for database access errors

Since:

6.0.5

enquoteNCharLiteral

@NonNull String enquoteNCharLiteral(@NonNull String val)
                             throws SQLException

Returns a string appropriately quoted as a string literal for the connection dialect.

Implementations should call their implementation of enquoteLiteral(String). Given the future removal of this method from this interface, we're not providing a default implementation in this interface. Contrary to the requirements stated in JDBC 4.5, the returned string is not prefixed with N as Firebird doesn't have NCHAR literals.

This method is defined in Connection starting with JDBC 4.5 (Java 26). The definition in this interface may be removed without notice once Jaybird only supports Java versions that expect JDBC 4.5 or higher.

Parameters:

val - a character string

Returns:

for dialect 3, a string enclosed by single quotes with every single quote converted to two single quotes, for dialect 1, with double quotes instead of single quotes.

Throws:

NullPointerException - if val is null

SQLException - for database access errors

Since:

6.0.5

See Also:

• enquoteLiteral(String)

enquoteIdentifier

@NonNull String enquoteIdentifier(@NonNull String identifier,
 boolean alwaysDelimit)
                           throws SQLException

Returns a simple SQL identifier or a delimited identifier, as appropriate for the connection dialect.

For dialect 3, if identifier already starts and ends in a double quote, we strip the quotes, unescape doubled double quotes, and requote and reescape. Reserved words known to Jaybird are not considered simple identifiers, and are always delimited.

For dialect 1, if identifier is not a simple identifier or if alwaysDelimit is true, this method will throw a SQLFeatureNotSupportedException as dialect 1 does not support delimited identifiers.

This method is defined in Connection starting with JDBC 4.5 (Java 26). The definition in this interface may be removed without notice once Jaybird only supports Java versions that expect JDBC 4.5 or higher.

Parameters:

identifier - a SQL identifier

alwaysDelimit - indicates if a simple SQL identifier should be returned as a delimited identifier

Returns:

a simple SQL identifier or a delimited identifier

Throws:

NullPointerException - if identifier is null

SQLFeatureNotSupportedException - if the datasource does not support delimited identifiers and identifier is not a simple identifier or alwaysDelimit is true

SQLException - if identifier is not a valid identifier

Since:

6.0.5

See Also:

• isSimpleIdentifier(String)

isSimpleIdentifier

boolean isSimpleIdentifier(@NonNull String identifier)
                    throws SQLException

Returns whether identifier is a simple identifier.

Reserved words known to Jaybird are not considered simple identifiers.

This method is defined in Connection starting with JDBC 4.5 (Java 26). The definition in this interface may be removed without notice once Jaybird only supports Java versions that expect JDBC 4.5 or higher.

Parameters:

identifier - a SQL identifier

Returns:

true if a simple SQL identifier, false otherwise

Throws:

NullPointerException - if identifier is null

SQLException - for database access errors

Since:

6.0.5