org.firebirdsql.gds.ng

Interface FbDatabase

All Superinterfaces:

java.lang.AutoCloseable, ExceptionListenable, FbAttachment

All Known Subinterfaces:

FbWireDatabase

All Known Implementing Classes:

AbstractFbDatabase, AbstractFbWireDatabase, JnaDatabase, V10Database, V11Database, V12Database, V13Database

public interface FbDatabase
extends FbAttachment

Connection handle to a database.

All methods defined in this interface are required to notify all SQLException thrown from the methods defined in this interface, and those exceptions notified by all ExceptionListenable implementations created from them.

Since:

3.0

Author:

Mark Rotteveel

Method Summary

Modifier and Type	Method and Description
void	addDatabaseListener(DatabaseListener listener) Adds a DatabaseListener instance to this database.
void	addWeakDatabaseListener(DatabaseListener listener) Adds a DatabaseListener instance to this database using a weak reference.
void	cancelEvent(EventHandle eventHandle) Cancels a registered event.
void	cancelOperation(int kind) Cancels the current operation.
void	countEvents(EventHandle eventHandle) Counts the events occurred.
FbBlob	createBlobForInput(FbTransaction transaction, BlobParameterBuffer blobParameterBuffer, long blobId) Creates a blob for read access to an existing blob on the server.
FbBlob	createBlobForOutput(FbTransaction transaction, BlobParameterBuffer blobParameterBuffer) Creates a blob for write access to a new blob on the server.
BlobParameterBuffer	createBlobParameterBuffer() Creates a blob parameter buffer that is usable with createBlobForInput(FbTransaction, org.firebirdsql.gds.BlobParameterBuffer, long) and createBlobForOutput(FbTransaction, org.firebirdsql.gds.BlobParameterBuffer) of this instance.
void	createDatabase() Creates a new database, connection remains attached to database.
EventHandle	createEventHandle(java.lang.String eventName, EventHandler eventHandler) Creates an event handle for this database type.
FbStatement	createStatement(FbTransaction transaction) Creates a statement associated with a transaction
TransactionParameterBuffer	createTransactionParameterBuffer() Creates a transaction parameter buffer that is usable with startTransaction(org.firebirdsql.gds.TransactionParameterBuffer).
void	dropDatabase() Drops (and deletes) the currently attached database.
RowDescriptor	emptyRowDescriptor()
void	executeImmediate(java.lang.String statementText, FbTransaction transaction) Performs an execute immediate of a statement.
short	getConnectionDialect()
IConnectionProperties	getConnectionProperties()
short	getDatabaseDialect()
byte[]	getDatabaseInfo(byte[] requestItems, int maxBufferLength) Performs a database info request.
<T> T	getDatabaseInfo(byte[] requestItems, int bufferLength, InfoProcessor<T> infoProcessor) Request database info.
int	getHandle()
int	getOdsMajor()
int	getOdsMinor()
void	queueEvent(EventHandle eventHandle) Queues a wait for an event.
FbTransaction	reconnectTransaction(long transactionId) Reconnects a prepared transaction.
void	removeDatabaseListener(DatabaseListener listener) Removes a DatabaseListener instance from this database.
FbTransaction	startTransaction(TransactionParameterBuffer tpb) Creates and starts a transaction.

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

attach, close, getDatatypeCoder, getEncoding, getEncodingFactory, getServerVersion, getSynchronizationObject, isAttached

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

addExceptionListener, removeExceptionListener

Method Detail

createDatabase

void createDatabase()
             throws java.sql.SQLException

Creates a new database, connection remains attached to database.

Throws:

java.sql.SQLException

dropDatabase

void dropDatabase()
           throws java.sql.SQLException

Drops (and deletes) the currently attached database.

Throws:

java.sql.SQLException

cancelOperation

void cancelOperation(int kind)
              throws java.sql.SQLException

Cancels the current operation.

The cancellation types are:

ISCConstants.fb_cancel_disable

disables execution of fb_cancel_raise requests for the specified attachment. It can be useful when your0 program is executing critical operations, such as cleanup, for example.

ISCConstants.fb_cancel_enable

re-enables delivery of a cancel execution that was previously disabled. The 'cancel' state is effective by default, being initialized when the attachment is created.

ISCConstants.fb_cancel_raise

cancels any activity related to the database handle. The effect will be that, as soon as possible, the engine will try to stop the running request and return an exception to the caller

ISCConstants.fb_cancel_abort

forcibly close client side of connection. Useful if you need to close a connection urgently. All active transactions will be rolled back by the server. 'Success' is always returned to the application. Use with care!

Parameters:

kind - Cancellation type

Throws:

java.sql.SQLException - For errors cancelling, or if the cancel operation is not supported.

startTransaction

FbTransaction startTransaction(TransactionParameterBuffer tpb)
                        throws java.sql.SQLException

Creates and starts a transaction.

Parameters:

tpb - TransactionParameterBuffer with the required transaction options

Returns:

FbTransaction

Throws:

java.sql.SQLException

reconnectTransaction

FbTransaction reconnectTransaction(long transactionId)
                            throws java.sql.SQLException

Reconnects a prepared transaction.

Reconnecting transactions is only allowed for transactions in limbo (prepared, but not committed or rolled back).

Parameters:

transactionId - The id of the transaction to reconnect.

Returns:

FbTransaction

Throws:

java.sql.SQLException - For errors reconnecting the transaction

createStatement

FbStatement createStatement(FbTransaction transaction)
                     throws java.sql.SQLException

Creates a statement associated with a transaction

Parameters:

transaction - FbTransaction to associate with this statement (can be null).

Returns:

FbStatement

Throws:

java.sql.SQLException

createBlobForOutput

FbBlob createBlobForOutput(FbTransaction transaction,
                           BlobParameterBuffer blobParameterBuffer)

Creates a blob for write access to a new blob on the server.

The blob is initially closed.

Parameters:

transaction - Transaction associated with the blob.

blobParameterBuffer - Blob Parameter Buffer

Returns:

Instance of FbBlob

createBlobForInput

FbBlob createBlobForInput(FbTransaction transaction,
                          BlobParameterBuffer blobParameterBuffer,
                          long blobId)

Creates a blob for read access to an existing blob on the server.

The blob is initially closed.

Parameters:

transaction - Transaction associated with the blob.

blobParameterBuffer - Blob Parameter Buffer

blobId - Handle id of the blob

Returns:

Instance of FbBlob

createBlobParameterBuffer

BlobParameterBuffer createBlobParameterBuffer()

Creates a blob parameter buffer that is usable with createBlobForInput(FbTransaction, org.firebirdsql.gds.BlobParameterBuffer, long) and createBlobForOutput(FbTransaction, org.firebirdsql.gds.BlobParameterBuffer) of this instance.

Returns:

A blob parameter buffer.

createTransactionParameterBuffer

TransactionParameterBuffer createTransactionParameterBuffer()

Creates a transaction parameter buffer that is usable with startTransaction(org.firebirdsql.gds.TransactionParameterBuffer).

Returns:

A transaction parameter buffer

getDatabaseInfo

<T> T getDatabaseInfo(byte[] requestItems,
                      int bufferLength,
                      InfoProcessor<T> infoProcessor)
               throws java.sql.SQLException

Request database 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.

getDatabaseInfo

byte[] getDatabaseInfo(byte[] requestItems,
                       int maxBufferLength)
                throws java.sql.SQLException

Performs a database info request.

Parameters:

requestItems - Information items to request

maxBufferLength - Maximum response buffer length to use

Returns:

The response buffer (note: length is the actual length of the response, not maxBufferLength

Throws:

java.sql.SQLException - For errors retrieving the information.

executeImmediate

void executeImmediate(java.lang.String statementText,
                      FbTransaction transaction)
               throws java.sql.SQLException

Performs an execute immediate of a statement.

A call to this method is the equivalent of a isc_dsql_execute_immediate() without parameters.

Parameters:

statementText - Statement text

transaction - Transaction (null only allowed if database is not attached!)

Throws:

java.sql.SQLException - For errors executing the statement, or if transaction is null when the database is attached or not null when the database is not attached

getDatabaseDialect

short getDatabaseDialect()

Returns:

The database dialect

getConnectionDialect

short getConnectionDialect()

Returns:

The client connection dialect

getHandle

int getHandle()

Specified by:

getHandle in interface FbAttachment

Returns:

The database handle value

getOdsMajor

int getOdsMajor()

Returns:

ODS major version

getOdsMinor

int getOdsMinor()

Returns:

ODS minor version

addDatabaseListener

void addDatabaseListener(DatabaseListener listener)

Adds a DatabaseListener instance to this database.

Parameters:

listener - Database listener

addWeakDatabaseListener

void addWeakDatabaseListener(DatabaseListener listener)

Adds a DatabaseListener instance to this database using a weak reference.

If the listener is already strongly referenced, this call will be ignored

Parameters:

listener - Database listener

removeDatabaseListener

void removeDatabaseListener(DatabaseListener listener)

Removes a DatabaseListener instance from this database.

Parameters:

listener - Database Listener

createEventHandle

EventHandle createEventHandle(java.lang.String eventName,
                              EventHandler eventHandler)
                       throws java.sql.SQLException

Creates an event handle for this database type.

The returned event handle can be used with queueEvent(org.firebirdsql.gds.EventHandle).

Parameters:

eventName - Name of the event

eventHandler - The event handler to call when the event occurred

Returns:

A suitable event handle instance

Throws:

java.sql.SQLException - For errors creating the event handle

countEvents

void countEvents(EventHandle eventHandle)
          throws java.sql.SQLException

Counts the events occurred.

Parameters:

eventHandle - The event handle

Throws:

java.sql.SQLException - When the count can not be done (as - for example - the event handle is of the wrong type)

queueEvent

void queueEvent(EventHandle eventHandle)
         throws java.sql.SQLException

Queues a wait for an event.

Parameters:

eventHandle - The event handle (created using createEventHandle(String, EventHandler) of this instance).

Throws:

java.sql.SQLException - For errors establishing the asynchronous channel, or for queuing the event.

cancelEvent

void cancelEvent(EventHandle eventHandle)
          throws java.sql.SQLException

Cancels a registered event.

After cancellation, the event handle should be considered unusable. Before queueing a new event, an new handle needs to be created.

Parameters:

eventHandle - The event handle to cancel

Throws:

java.sql.SQLException - For errors cancelling the event

getConnectionProperties

IConnectionProperties getConnectionProperties()

Returns:

An immutable copy of the connection properties of this database

emptyRowDescriptor

RowDescriptor emptyRowDescriptor()

Returns:

A potentially cached empty row descriptor for this database.