Package org.firebirdsql.gds.ng.jna

Class JnaDatabase

java.lang.Object

org.firebirdsql.gds.ng.AbstractFbAttachment<T>

org.firebirdsql.gds.ng.AbstractFbDatabase<JnaDatabaseConnection>

org.firebirdsql.gds.ng.jna.JnaDatabase

All Implemented Interfaces:

AutoCloseable, FbAttachment, FbDatabase, FbClientFeatureAccess, JnaAttachment, ExceptionListenable, TransactionListener

public class JnaDatabase
extends AbstractFbDatabase<JnaDatabaseConnection>
implements JnaAttachment, TransactionListener, FbClientFeatureAccess

Implementation of FbDatabase for native client access.

Since:

3.0

Author:

Mark Rotteveel

Field Summary

Fields

Modifier and Type	Field	Description
protected final com.sun.jna.ptr.IntByReference	handle
static final int	MAX_STATEMENT_LENGTH
static final int	STATUS_VECTOR_SIZE
protected final ISC_STATUS[]	statusVector

Fields inherited from class org.firebirdsql.gds.ng.AbstractFbDatabase

databaseListenerDispatcher

Fields inherited from class org.firebirdsql.gds.ng.AbstractFbAttachment

connection, exceptionListenerDispatcher

Constructor Summary

Constructors

Constructor	Description
JnaDatabase(JnaDatabaseConnection connection)

Method Summary

Modifier and Type	Method	Description
protected void	afterAttachActions()	Additional tasks to execute directly after attach operation.
void	attach()	Attach to the attachment type.
protected void	attachOrCreate(DatabaseParameterBuffer dpb, boolean create)
void	cancelEvent(EventHandle eventHandle)	Cancels a registered event.
void	cancelOperation(int kind)	Cancels the current operation.
protected void	checkConnected()	Checks if the attachment is connected, and throws a SQLException if it isn't connected.
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.
void	createDatabase()	Creates a new database, connection remains attached to database.
JnaEventHandle	createEventHandle(String eventName, EventHandler eventHandler)	Creates an event handle for this database type.
JnaStatement	createStatement(FbTransaction transaction)	Creates a statement associated with a transaction
void	dropDatabase()	Drops (and deletes) the currently attached database.
void	executeImmediate(String statementText, FbTransaction transaction)	Performs an execute immediate of a statement.
protected void	finalize()
protected final FbClientLibrary	getClientLibrary()
byte[]	getDatabaseInfo(byte[] requestItems, int maxBufferLength)	Performs a database info request.
final EncodingDefinition	getEncodingDefinition()
Set<FbClientFeature>	getFeatures()
int	getHandle()
com.sun.jna.ptr.IntByReference	getJnaHandle()
int	getNetworkTimeout()	Gets the current network timeout for this attachment.
protected byte[]	getTransactionIdBuffer(long transactionId)
boolean	hasFeature(FbClientFeature clientFeature)	Checks for presence of a client feature.
protected void	internalDetach()	Actual implementation of database detach.
void	processStatusVector(ISC_STATUS[] statusVector, WarningMessageCallback warningMessageCallback)
void	queueEvent(EventHandle eventHandle)	Queues a wait for an event.
FbTransaction	reconnectTransaction(long transactionId)	Reconnects a prepared transaction.
void	setNetworkTimeout(int milliseconds)	Sets the network timeout for this attachment.
JnaTransaction	startTransaction(TransactionParameterBuffer tpb)	Creates and starts a transaction.
protected JnaEventHandle	validateEventHandle(EventHandle eventHandle)

Methods inherited from class org.firebirdsql.gds.ng.AbstractFbDatabase

addDatabaseListener, addWeakDatabaseListener, close, createBlobParameterBuffer, createTransactionParameterBuffer, emptyRowDescriptor, getActiveTransactionCount, getConnectionDialect, getConnectionProperties, getDatabaseDialect, getDatabaseInfo, getDatabaseInformationProcessor, getDatabaseWarningCallback, getDescribeDatabaseInfoBlock, getOdsMajor, getOdsMinor, getParameterDescriptionInfoRequestItems, getStatementInfoRequestItems, removeDatabaseListener, setDatabaseDialect, setOdsMajor, setOdsMinor, transactionAdded, transactionStateChanged

Methods inherited from class org.firebirdsql.gds.ng.AbstractFbAttachment

addExceptionListener, forceClose, getDatatypeCoder, getEncoding, getEncodingFactory, getServerVersion, getServerVersionInformation, getSynchronizationObject, isAttached, removeExceptionListener, safelyDetach, setAttached, setDetached, setServerVersion

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.listeners.ExceptionListenable

addExceptionListener, removeExceptionListener

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

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

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

transactionStateChanged

Field Details

STATUS_VECTOR_SIZE

public static final int STATUS_VECTOR_SIZE

See Also:

• Constant Field Values

MAX_STATEMENT_LENGTH

public static final int MAX_STATEMENT_LENGTH

See Also:

• Constant Field Values

handle

protected final com.sun.jna.ptr.IntByReference handle

statusVector

protected final ISC_STATUS[] statusVector

Constructor Details

JnaDatabase

public JnaDatabase(JnaDatabaseConnection connection)

Method Details

getClientLibrary

protected final FbClientLibrary getClientLibrary()

Returns:

The client library instance associated with the database.

checkConnected

protected void checkConnected()
                       throws SQLException

Description copied from class: AbstractFbAttachment

Checks if the attachment is connected, and throws a SQLException if it isn't connected.

Specified by:

checkConnected in class AbstractFbAttachment<JnaDatabaseConnection>

Throws:

SQLException

internalDetach

protected void internalDetach()
                       throws SQLException

Description copied from class: AbstractFbDatabase

Actual implementation of database detach.

Implementations of this method should only be called from AbstractFbDatabase.close(), and should not notify database listeners of the database DatabaseListener.detaching(FbDatabase) and DatabaseListener.detached(FbDatabase) events.

Specified by:

internalDetach in class AbstractFbDatabase<JnaDatabaseConnection>

Throws:

SQLException

attach

public void attach()
            throws SQLException

Description copied from interface: FbAttachment

Attach to the attachment type.

Specified by:

attach in interface FbAttachment

Throws:

SQLException

attachOrCreate

protected void attachOrCreate(DatabaseParameterBuffer dpb,
 boolean create)
                       throws SQLException

Throws:

SQLException

afterAttachActions

protected void afterAttachActions()
                           throws SQLException

Additional tasks to execute directly after attach operation.

Implementation retrieves database information like dialect ODS and server version.

Throws:

SQLException - For errors reading or writing database information.

createDatabase

public void createDatabase()
                    throws SQLException

Description copied from interface: FbDatabase

Creates a new database, connection remains attached to database.

Specified by:

createDatabase in interface FbDatabase

Throws:

SQLException

dropDatabase

public void dropDatabase()
                  throws SQLException

Description copied from interface: FbDatabase

Drops (and deletes) the currently attached database.

Specified by:

dropDatabase in interface FbDatabase

Throws:

SQLException

cancelOperation

public void cancelOperation(int kind)
                     throws SQLException

Description copied from interface: FbDatabase

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 your 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!

Specified by:

cancelOperation in interface FbDatabase

Parameters:

kind - Cancellation type

Throws:

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

startTransaction

public JnaTransaction startTransaction(TransactionParameterBuffer tpb)
                                throws SQLException

Description copied from interface: FbDatabase

Creates and starts a transaction.

Specified by:

startTransaction in interface FbDatabase

Parameters:

tpb - TransactionParameterBuffer with the required transaction options

Returns:

FbTransaction

Throws:

SQLException

reconnectTransaction

public FbTransaction reconnectTransaction(long transactionId)
                                   throws SQLException

Description copied from interface: FbDatabase

Reconnects a prepared transaction.

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

Specified by:

reconnectTransaction in interface FbDatabase

Parameters:

transactionId - The id of the transaction to reconnect.

Returns:

FbTransaction

Throws:

SQLException - For errors reconnecting the transaction

getTransactionIdBuffer

protected byte[] getTransactionIdBuffer(long transactionId)

createStatement

public JnaStatement createStatement(FbTransaction transaction)
                             throws SQLException

Description copied from interface: FbDatabase

Creates a statement associated with a transaction

Specified by:

createStatement in interface FbDatabase

Parameters:

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

Returns:

FbStatement

Throws:

SQLException

createBlobForOutput

public FbBlob createBlobForOutput(FbTransaction transaction,
 BlobParameterBuffer blobParameterBuffer)

Description copied from interface: FbDatabase

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

The blob is initially closed.

Specified by:

createBlobForOutput in interface FbDatabase

Parameters:

transaction - Transaction associated with the blob.

blobParameterBuffer - Blob Parameter Buffer

Returns:

Instance of FbBlob

createBlobForInput

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

Description copied from interface: FbDatabase

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

The blob is initially closed.

Specified by:

createBlobForInput in interface FbDatabase

Parameters:

transaction - Transaction associated with the blob.

blobParameterBuffer - Blob Parameter Buffer

blobId - Handle id of the blob

Returns:

Instance of FbBlob

getDatabaseInfo

public byte[] getDatabaseInfo(byte[] requestItems,
 int maxBufferLength)
                       throws SQLException

Description copied from interface: FbDatabase

Performs a database info request.

Specified by:

getDatabaseInfo in interface FbDatabase

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:

SQLException - For errors retrieving the information.

executeImmediate

public void executeImmediate(String statementText,
 FbTransaction transaction)
                      throws SQLException

Description copied from interface: FbDatabase

Performs an execute immediate of a statement.

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

Specified by:

executeImmediate in interface FbDatabase

Parameters:

statementText - Statement text

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

Throws:

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

getHandle

public int getHandle()

Specified by:

getHandle in interface FbAttachment

Specified by:

getHandle in interface FbDatabase

Returns:

The attachment handle value

setNetworkTimeout

public void setNetworkTimeout(int milliseconds)
                       throws SQLException

Description copied from interface: FbAttachment

Sets the network timeout for this attachment.

Specified by:

setNetworkTimeout in interface FbAttachment

Parameters:

milliseconds - Timeout in milliseconds; 0 means no timeout. If the attachment doesn't support milliseconds, it should round up to the nearest second.

Throws:

SQLException - If this attachment is closed, the value of milliseconds is smaller than 0, or if setting the timeout fails.

SQLFeatureNotSupportedException - If this attachment doesn't support (changing) the network timeout.

getNetworkTimeout

public int getNetworkTimeout()
                      throws SQLException

Description copied from interface: FbAttachment

Gets the current network timeout for this attachment.

Specified by:

getNetworkTimeout in interface FbAttachment

Overrides:

getNetworkTimeout in class AbstractFbAttachment<JnaDatabaseConnection>

Returns:

Timeout in milliseconds, 0 means no timeout

Throws:

SQLException - If this attachment is closed

SQLFeatureNotSupportedException - If this attachment doesn't support network timeout

getJnaHandle

public com.sun.jna.ptr.IntByReference getJnaHandle()

getEncodingDefinition

public final EncodingDefinition getEncodingDefinition()

validateEventHandle

protected JnaEventHandle validateEventHandle(EventHandle eventHandle)
                                      throws SQLException

Throws:

SQLException

createEventHandle

public JnaEventHandle createEventHandle(String eventName,
 EventHandler eventHandler)
                                 throws SQLException

Description copied from interface: FbDatabase

Creates an event handle for this database type.

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

Specified by:

createEventHandle in interface FbDatabase

Parameters:

eventName - Name of the event

eventHandler - The event handler to call when the event occurred

Returns:

A suitable event handle instance

Throws:

SQLException - For errors creating the event handle

countEvents

public void countEvents(EventHandle eventHandle)
                 throws SQLException

Description copied from interface: FbDatabase

Counts the events occurred.

Specified by:

countEvents in interface FbDatabase

Parameters:

eventHandle - The event handle

Throws:

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

queueEvent

public void queueEvent(EventHandle eventHandle)
                throws SQLException

Description copied from interface: FbDatabase

Queues a wait for an event.

Specified by:

queueEvent in interface FbDatabase

Parameters:

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

Throws:

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

cancelEvent

public void cancelEvent(EventHandle eventHandle)
                 throws SQLException

Description copied from interface: FbDatabase

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.

Specified by:

cancelEvent in interface FbDatabase

Parameters:

eventHandle - The event handle to cancel

Throws:

SQLException - For errors cancelling the event

processStatusVector

public void processStatusVector(ISC_STATUS[] statusVector,
 WarningMessageCallback warningMessageCallback)
                         throws SQLException

Throws:

SQLException

finalize

protected void finalize()
                 throws Throwable

Overrides:

finalize in class Object

Throws:

Throwable

hasFeature

public boolean hasFeature(FbClientFeature clientFeature)

Description copied from interface: FbClientFeatureAccess

Checks for presence of a client feature.

Specified by:

hasFeature in interface FbClientFeatureAccess

Parameters:

clientFeature - Client feature

Returns:

true if the feature is present, false otherwise

getFeatures

public Set<FbClientFeature> getFeatures()

Specified by:

getFeatures in interface FbClientFeatureAccess

Returns:

an unmodifiable set with supported client features