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
All Methods Instance Methods Abstract Methods 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.
-
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.
-
-