Package org.eclipse.persistence.internal.databaseaccess

Interface Accessor

All Superinterfaces:

Cloneable

All Known Implementing Classes:

DatabaseAccessor, DatasourceAccessor, EISAccessor, XMLAccessor

public interface Accessor
extends Cloneable

INTERNAL: Accessor defines the interface used primarily by the assorted TopLink Sessions to interact with a data store. In "normal" TopLink this data store is a relational database. But this interface also allows developers using the TopLink SDK to develop Accessors to other, non-relational, data stores.

Accessors must implement the following behavior:

• connect to and disconnect from the data store
• handle transaction contexts
• execute calls that read, insert, update, and delete data
• keep track of concurrently executing calls
• supply metadata about the data store

Since:

TOPLink/Java 3.0

Author:

Big Country

See Also:

AbstractSession, Call

Method Summary

Modifier and Type	Method	Description
void	beginTransaction(AbstractSession session)	Begin a transaction on the data store.
Object	clone()	Return a clone of the accessor.
void	closeConnection()	Close the accessor's connection.
void	closeJTSConnection()	Called from beforeCompletion external transaction synchronization listener callback to close the external connection corresponding to the completing external transaction.
void	commitTransaction(AbstractSession session)	Commit a transaction on the data store.
void	connect(Login login, AbstractSession session)	Connect to the data store using the configuration information in the login.
void	createCustomizer(AbstractSession session)	Attempts to create ConnectionCustomizer.
void	decrementCallCount()	Decrement the number of calls in progress.
void	disconnect(AbstractSession session)	Disconnect from the data store.
Object	executeCall(Call call, AbstractRecord translationRow, AbstractSession session)	Execute the call.
void	flushSelectCalls(AbstractSession session)	Execute any deferred select calls.
int	getCallCount()	Return the number of calls currently in progress.
Vector	getColumnInfo(String catalog, String schema, String tableName, String columnName, AbstractSession session)	Return the column metadata for the specified selection criteria.
Connection	getConnection()	Return the JDBC connection for relational accessors.
Object	getDatasourceConnection()	Return the driver level connection, this will need to be cast to the implementation class for the data access type being used.
ConnectionPool	getPool()	Return the associated connection pool this connection was obtained from.
SequencingCallback	getSequencingCallback(SequencingCallbackFactory sequencingCallbackFactory)	Return sequencing callback.
Vector	getTableInfo(String catalog, String schema, String tableName, String[] types, AbstractSession session)	Return the table metadata for the specified selection criteria.
void	incrementCallCount(AbstractSession session)	Increment the number of calls in progress.
boolean	isConnected()	Return whether the accessor is connected to the data store.
boolean	isInTransaction()	Return whether the accessor is in transaction.
boolean	isValid()	Returns true if this Accessor can continue to be used.
void	reestablishConnection(AbstractSession session)	Reconnect to the database.
void	releaseCustomizer()	Clear customizer if it's active and set it to null.
void	releaseCustomizer(AbstractSession session)	Clear and remove customizer if its session is the same as the passed one; in case prevCustomizer exists set it as a new customizer.
void	reset()	Reset the accessor before being released.
void	rollbackTransaction(AbstractSession session)	Roll back a transaction on the data store.
void	setIsValid(boolean isValid)	This should be set to false if a communication failure occurred durring a call execution.
void	setPool(ConnectionPool pool)	Set the associated connection pool this connection was obtained from.
boolean	usesExternalConnectionPooling()	Return whether the accessor uses external connection pooling.
boolean	usesExternalTransactionController()	Return whether the accessor uses an external transaction controller (e.g.
void	writesCompleted(AbstractSession session)	This method will be called after a series of writes have been issued to mark where a particular set of writes has completed.

Method Detail

closeJTSConnection

void closeJTSConnection()

Called from beforeCompletion external transaction synchronization listener callback to close the external connection corresponding to the completing external transaction. Final sql calls could be sent through the connection by this method before it closes the connection.

beginTransaction

void beginTransaction(AbstractSession session)
               throws DatabaseException

Begin a transaction on the data store.

Throws:

DatabaseException

clone

Object clone()

Return a clone of the accessor.

closeConnection

void closeConnection()

Close the accessor's connection. This is used only for external connection pooling when it is intended for the connection to be reconnected in the future.

commitTransaction

void commitTransaction(AbstractSession session)
                throws DatabaseException

Commit a transaction on the data store.

Throws:

DatabaseException

connect

void connect(Login login,
             AbstractSession session)
      throws DatabaseException

Connect to the data store using the configuration information in the login.

Throws:

DatabaseException

decrementCallCount

void decrementCallCount()

Decrement the number of calls in progress. Used for external pooling.

disconnect

void disconnect(AbstractSession session)
         throws DatabaseException

Disconnect from the data store.

Throws:

DatabaseException

executeCall

Object executeCall(Call call,
                   AbstractRecord translationRow,
                   AbstractSession session)
            throws DatabaseException

Execute the call. The actual behavior of the execution depends on the type of call. The call may be parameterized where the arguments are in the translation row. The row will be empty if there are no parameters.

Returns:

a row, a collection of rows, a row count, or a cursor

Throws:

DatabaseException

flushSelectCalls

void flushSelectCalls(AbstractSession session)

Execute any deferred select calls. This method will generally be called after one or more select calls have been collected in a LOBValueWriter (to be executed after all insert calls are executed). Bug 2804663.

See Also:

LOBValueWriter.buildAndExecuteSelectCalls(AbstractSession)

getCallCount

int getCallCount()

Return the number of calls currently in progress. Used for load balancing and external pooling.

getColumnInfo

Vector getColumnInfo(String catalog,
                     String schema,
                     String tableName,
                     String columnName,
                     AbstractSession session)
              throws DatabaseException

Return the column metadata for the specified selection criteria.

Throws:

DatabaseException

getConnection

Connection getConnection()

Return the JDBC connection for relational accessors. This will fail for non-relational accessors.

getDatasourceConnection

Object getDatasourceConnection()

Return the driver level connection, this will need to be cast to the implementation class for the data access type being used.

getSequencingCallback

SequencingCallback getSequencingCallback(SequencingCallbackFactory sequencingCallbackFactory)

Return sequencing callback.

getTableInfo

Vector getTableInfo(String catalog,
                    String schema,
                    String tableName,
                    String[] types,
                    AbstractSession session)
             throws DatabaseException

Return the table metadata for the specified selection criteria.

Throws:

DatabaseException

incrementCallCount

void incrementCallCount(AbstractSession session)

Increment the number of calls in progress. Used for external pooling.

isConnected

boolean isConnected()

Return whether the accessor is connected to the data store.

isInTransaction

boolean isInTransaction()

Return whether the accessor is in transaction.

isValid

boolean isValid()

Returns true if this Accessor can continue to be used. This will be false if a communication failure occurred during a call execution. In the case of an invalid accessor the Accessor will not be returned to the pool.

reestablishConnection

void reestablishConnection(AbstractSession session)
                    throws DatabaseException

Reconnect to the database. This can be used if the connection was temporarily disconnected or if it timed out.

Throws:

DatabaseException

rollbackTransaction

void rollbackTransaction(AbstractSession session)
                  throws DatabaseException

Roll back a transaction on the data store.

Throws:

DatabaseException

setIsValid

void setIsValid(boolean isValid)

This should be set to false if a communication failure occurred durring a call execution. In the case of an invalid accessor the Accessor will not be returned to the pool.

usesExternalTransactionController

boolean usesExternalTransactionController()

Return whether the accessor uses an external transaction controller (e.g. JTS).

usesExternalConnectionPooling

boolean usesExternalConnectionPooling()

Return whether the accessor uses external connection pooling.

writesCompleted

void writesCompleted(AbstractSession session)

This method will be called after a series of writes have been issued to mark where a particular set of writes has completed. It will be called from commitTransaction and may be called from writeChanges. Its main purpose is to ensure that the batched statements have been executed

createCustomizer

void createCustomizer(AbstractSession session)

Attempts to create ConnectionCustomizer. If created the customizer is cached by the accessor. Called by the owner of accessor (DatabaseSession, ServerSession through ConnectionPool) just once, typically right after the accessor is created. Also called by ClientSession when it acquires write accessor. If accessor already has a customizer set by ConnectionPool then ClientSession's customizer compared with the existing one and if they are not equal (don't produce identical customization) then the new customizer set onto accessor, caching the old customizer so that it could be restored later.

releaseCustomizer

void releaseCustomizer()

Clear customizer if it's active and set it to null. Called by the same object that has created customizer (DatabaseSession, ConnectionPool) when the latter is no longer required, typically before releasing the accessor. Ignored if there's no customizer.

releaseCustomizer

void releaseCustomizer(AbstractSession session)

Clear and remove customizer if its session is the same as the passed one; in case prevCustomizer exists set it as a new customizer. Called when ClientSession releases write accessor: if the customizer was created by the ClientSession it's removed, and the previous customizer (that ConnectionPool had set) is brought back; otherwise the customizer (created by ConnectionPool) is kept. Ignored if there's no customizer.

reset

void reset()

Reset the accessor before being released.

getPool

ConnectionPool getPool()

Return the associated connection pool this connection was obtained from.

setPool

void setPool(ConnectionPool pool)

Set the associated connection pool this connection was obtained from.