Package wt.pom

Provides low-level, yet database independent, access to a database.

See:
Description

Interface Summary

PersistentObjectManager.FirePOMOperationListener
POMIfc	The persistent object manager interface for managing persistent objects.
POMOperationListener	This interface specifies methods for listening to operations(create, update, delete, lock, refresh) on PerssitentObjectManager layer.
TransactionCommitListener	This interface specifies methods for processing that occurs at the end of a transaction after normal work is completed, but before the transaction is committed.
TransactionListener	This interface specifies methods for listening to transaction commits and rollbacks.
TransactionManager.FireTransactionListener

Class Summary

BeforeCompletionValidationListener	This class implements POMOperationListener to validate that no database modifications are made during TransactionCommitListener beforeCompletion event notification.
CacheEnumerator
DataServicesRegistry	DataServicesRegistry maintains the datastore - PDS mappings.
DBProperties	Database configuration properties.
EmptyTableManager	Provides methods to access cached empty tables information.
ExpandAllLinkRoleIndicator
ExpandAllResultProcessor
NoOpEmptyTableManager	Provides methods to access cached empty tables information.
OIDPool
OracleTransactionManager	This class provides a standard implementation for TransactionManager to manage nested transactions for a user thread.
PagingCacheEntry
PagingSessionCache	A fixed size cache of PagingSession information.
PersistentObjectManager	PersistentObjectManager provides datastore independent persistence interfaces.
PersistentObjectManager.NotifyCreateListener
PersistentObjectManager.NotifyDeleteListener
PersistentObjectManager.NotifyLockListener
PersistentObjectManager.NotifyRefreshListener
PersistentObjectManager.NotifyUpdateListener
POMHandler	An adapter to handle dependencies between the wt.method and wt.pom packages which are potentially loaded by different class loaders.
POMLog	POMLog.java
POMOperationListenerAdapter	This class implements no-op methods for listening to operations (create, update, delete, lock, refresh) in the PerssitentObjectManager layer.
POMPrintStream	A filter output stream to save SQL statements from the DriverManager.
RefreshCache	A fixed size, most recently used object cache.
ShowTableHits
SnapshotInsertProcess	Supported API: false Extendable: false
StatementCache	A fixed size cache of java.sql.Statement objects indexed by SQL string.
StatementCacheEntry
TableRef
Transaction	Transaction provides interfaces to create transaction blocks.
TransactionManager	TransactionManager manages nested transactions for a user thread.
TransactionManager.BeforeCompletionTransactionListener
TransactionManager.FinishTransactionListener
TransactionManager.NotifyCommitTransactionListener
TransactionManager.NotifyRollbackTransactionListener
WTConnection	WTConnection provides a datastore connection

Exception Summary

ConnectionException	ConnectionException captures errors with a datastore connect/disconnect.
ConnectionLostException	ConnectionLostException captures errors with a datastore interaction.
DatastoreException	DatastoreException captures errors with a datastore interaction.
DeadlockDetectedException	DeadlockDetectedException captures deadlock detection during a datastore interaction.
ObjectIsPersistentException	ObjectIsPersistentException captures errors with a datastore interaction.
ObjectIsStaleException	ObjectIsStaleException captures errors with a datastore interaction.
ObjectLockedException	ObjectLockedException captures errors with a datastore interaction.
ObjectNotPersistentException	ObjectNotPersistentException captures errors with a datastore interaction.
PagingFetchTimeOutException	PagingFetchTimeOutException captures errors when fetching pages.
PagingSessionCacheTimeOutException	This exception captures errors when attempting to fetch pages from a paging session that has timed out.
PersistenceException	PersistenceException is the super class of all exceptions in the wt.pom package.
POMInitException	This exception is thrown when an error occurs during Persistent Object Manager (POM) initialization.
UniquenessException	UniquenessException captures errors with a datastore interaction.
UnsupportedPDSException

Package wt.pom Description

Provides low-level, yet database independent, access to a database. See PersistenceManager for the higher-level access that most developers will use.

Transaction

The following transaction features are supported.

Nested Transaction Context

The Transaction class provides methods for creating transaction blocks. The Transaction.start() method must always be paired with either a Transaction.commit() or Transaction.rollback() to form a transaction block. In between these calls, other code can be invoked which can also create transaction blocks. These blocks would be considered nested within each other. The common pattern for ensuring that transaction blocks are created correctly uses the try/finally construct.

Transaction trx = new Transaction();
try 
{
  trx.start();
  
  // Do transaction work

  if(/* successfull */)
  {
    trx.commit();
    trx = null;
  }
}
finally 
{
  if(trx != null) 
  {
    trx.rollback();
  }
}

This code will always guarantee that either a commit or rollback will be executed. If the work is not succesfull or an exception is thrown, then trx will not be set to null, so the rollback will execute.

Commit and Rollback

Although Transaction programatically supports nesting, the database supports only a single flat transaction. Internal state is maintained so that a database commit is only executed at the outer most nested transaction block. A database rollback at any nested block will cause the entire transaction to be rolled back immediately.

Listener Subscription and Notification

The common pattern for listener subscription and notification is supported for the Transaction commit and rollback operations. Two seperate listerner types are supported, TransactionListener and TransactionCommitListener. TransactionListener instances can be added/ removed from the local and global Transactions using Transaction.addLocalTransactionListener(wt.pom.TransactionListener)/Transaction.removeLocalTransactionListener(wt.pom.TransactionListener) and Transaction.addTransactionListener(wt.pom.TransactionListener)/Transaction.removeTransactionListener(wt.pom.TransactionListener), respectively .

The following scenarios show the order of key steps for commit and rollback operations. If an exception is thrown at any step, then the remaining steps are not completed. Note that the order of notification to listeners is identical to the order in which they have been added.

The following is the order of operations for a commit to a Transaction that is nested.

1. The method finishTransaction() is called on local TransactionListeners implementing the TransactionCommitListener interface.
2. The method beforeCompletion() is called on local TransactionListeners implementing the TransactionCommitListener interface.
3. The method notifyCommit() is called on local TransactionListeners.

The following is the order of operations for a commit to a Transaction that is the outer-most (initial) in a nested block.

1. The method finishTransaction() is called on local TransactionListeners implementing the TransactionCommitListener interface.
2. The method beforeCompletion() is called on local TransactionListeners implementing the TransactionCommitListener interface.
3. The method finishTransaction() is called on global TransactionListeners implementing the TransactionCommitListener interface.
4. The method finishTransaction() is called on global TransactionListeners implementing the TransactionCommitListener interface.
5. The method beforeCompletion() is called on global TransactionListeners implementing the TransactionCommitListener interface.
6. The database commit is executed.
7. The WTConnection associated with the Transaction is released. Any new DB operations initiated would be in a separate global transaction.
8. The method notifyCommit() is called on global TransactionListeners.
9. The method notifyCommit() is called on local TransactionListeners.

The following is the order of operations for a rollback to a Transaction that is nested, but is not the inner-most Transaction.

1. The method notifyRollback() is called on local TransactionListeners.

The following is the order of operations for a rollback to a Transaction that is the inner-most Transaction in a nested block.

1. The database rollback is executed.
2. The WTConnection associated with the Transaction is released. Any new DB operations initiated would be in a separate global transaction.
3. The method notifyRollback() is called on global TransactionListeners.
4. The method notifyRollback() is called on local TransactionListeners.

Key and Value Pair Storage and Lookup

The nested transaction blocks support local and global java.util.Map attributes (Transaction.getLocalMap() and Transaction.getGlobalMap()) that can be used for key/value pair storage as needed by the application. Lookup methods are provided that access these Maps in the current Transaction stack. Adding a key/value pair is accomplished by accessing the current transaction either through a local reference or a call to Transaction.getCurrentTransaction(). The key/value pair can then be added to the local Map. Accessing the keys or associated values can be accomplished by searching the current Transaction or the entire nested Transaction block. The lookup methods support searching for the existence of a key (Transaction.containsKeyInContext(java.lang.Object, boolean, boolean)) and searching for the value associated with a key (Transaction.getInContext(java.lang.Object, boolean, boolean)) similar to the Map lookup methods. In addition, lookup methods also exist for returning the Transaction associated with the key (Transaction.findInContext(java.lang.Object) and Transaction.findAllInContext(java.lang.Object)).

Accessing key/value pairs in Transaction listeners during the commit or rollback operations is supported. The following are specific details concerning when the current Transaction and associated Maps are valid during these operations. During a local commit, the local Transaction is still in context during the local finishTransaction() and beforeComplete() notifications, but it is removed from context in the local notifyCommit() notification. For the outermost Transaction block, the global Transaction finishTransaction() and beforeComplete() notifications will occur while the outermost Transaction is still in context. The outermost Transaction is removed from context before the global TransactionListeners notifyCommit() notification. The global Transaction Map is removed after global TransactionListeners notifyCommit() notification. During a local rollback(), the local Transaction is removed from context in the local notifyCommit() notification. For the innermost Transaction block, the global Transaction notifyRollback() notification occurs after the outermost Transaction has been removed from context. The global Transaction Map is removed before global TransactionListeners notifyRollback() notification.

See Also:

wt.fc