SavepointManager (P2J - Progress 4GL to Java Conversion and Runtime)

java.lang.Object
- com.goldencode.p2j.persist.orm.SavepointManager

All Implemented Interfaces:

DmoState, Commitable, Finalizable
```
public class SavepointManager
extends java.lang.Object
implements Commitable, Finalizable, DmoState
```
The purpose of this class is to manage database savepoints in the context of application blocks with transaction properties, such that the state of in-memory DMOs can be kept in sync with the database, as full and sub-transactions are committed or rolled back.
An instance of this class is created when an application block with a full transaction property is executed. If and when an associated database transaction is created, the SavepointManager instance is installed in the active database session. The instantiation of this class and the creation of a database transaction do not necessarily have to occur simultaneously. In fact, a database transaction may not be created at all. A database-level transaction is only begun the first time a record buffer for the associated database is used (i.e., its scope is opened). This lazy creation of a database transaction is intended to prevent the overhead of creating unused database transactions every time an application-level transaction is opened.
When created at an application full transaction, this object is registered for Commitable and Finalizable callbacks. It must again be registered for these callbacks at each sub-transaction block encountered. The registration for these callbacks is the responsibility of the BufferManager. It is also the BufferManager which determines when a database transaction needs to be opened.
When a database transaction is opened and the savepoint manager installed in the session, the latter needs to be activated with a call to setSession(Session). Once activated, this object will track any changes made to DMOs, lazily creating savepoints as necessary when a change is made. It will track application persistence state which needs to be kept in sync with database create, update, and delete activity. The lazy creation of savepoints only when a change has been made prevents round trips to the database to set and release savepoints, if there is no database activity to be rolled back in a given subtransaction block.
Undoable and NO-UNDO operations are treated differently. For the former, this class ensures that the state of in-memory records is left in the state they were in at the time a rolled-back block was entered, while rolling back a corresponding savepoint in the database. For the latter, this class ensures that any rollback of NO-UNDO changes at the database is negated, by re-applying any SQL operations which were rolled back at the database, after the sub-transaction or full transaction completes.

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`private static class`	`SavepointManager.Block` Block state corresponding with full and sub-transactions, for the purpose of tracking updated records and their states.
`static interface`	`SavepointManager.PersistenceCode` Allows to execute a piece of code which may throw a `PersistenceException` by a foreign object.

Field Summary

Fields
Modifier and Type	Field and Description
`private SavepointManager.Block`	`activeBlock` State of the transaction block which currently is active, if any
`private java.util.Deque<SavepointManager.Block>`	`blocks` Stack of block states which coincide with transaction block scopes
`private static boolean`	`debug` Debug logging level
`private static CentralLogger`	`log` Logger
`private SavepointManager.Block`	`parentBlock` The current parent block, if any (will be `null` at a full transaction block)
`private Session`	`session` Database session used for savepoint processing

Fields inherited from interface com.goldencode.p2j.persist.orm.DmoState
CACHED, CHANGED, COPY, DEFAULT, DELETED, DELETING, INCOMPLETE, INVALID, NEW, NOUNDO, READ, STALE, TRACKED

Constructor Summary

Constructors
Constructor and Description

SavepointManager()
Default constructor.

Constructors
Constructor and Description
`SavepointManager()` Default constructor.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`private void`	`cleanupBlock()` End of block processing, which entails discarding the currently active block, re-applying any rolled back changes to a NO-UNDO temporary table, and reactivating the parent block, if any, for further processing.
`void`	`commit(boolean transaction)` Commit the active block, which entails releasing any savepoint and rolling up tracked resources.
`private void`	`debug(java.lang.String message)` Log a debug message if FINE logging is enabled for this class.
`void`	`deleted()` No-op delete hook.
`void`	`deregisterGlobalBlockHooks(TransactionManager.TransactionHelper txHelper)` Deregister the current instance from the transaction manager.
`void`	`finished()` The block has finished.
`(package private) int`	`getTxNestingLevel()` Get the zero-based transaction block nesting level, where 0 indicates the current block is a full transaction block, 1 indicates the current block is the first level of nested subtransaction, and so on.
`void`	`iterate()` Prepare to iterate through another pass of a looping block.
`(package private) SavepointManager.PersistenceCode`	`lazilySetSavepoints(boolean exceptLast)` Set a savepoint in the active block and in every previous block which has not yet had one set, except for the outermost (which represents the full transaction block).
`private void`	`prepareBlock()` Prepare a new block and make it the active block.
`void`	`registerBlockHooks(TransactionManager.TransactionHelper txHelper, boolean fullTx, int blockDepth)` Register for transaction manager notifications for the current block.
`void`	`retry()` Retry a block after handling a condition.
`void`	`rollback(boolean transaction)` Roll back the active block, which entails rolling back any savepoint, rolling up tracked resources, and marking any tracked undoable records as stale.
`private void`	`setSavepoint(SavepointManager.Block block)` Set a new savepoint in the database and associate it with the given block.
`(package private) void`	`setSession(Session session)` Install the given session into this savepoint manager.
`(package private) void`	`trackUndoable(BaseRecord dmo)` Begin tracking an undoable record as needing savepoint processing.
`void`	`validate(boolean transaction, boolean aggressiveFlush)` No-op validation hook.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface com.goldencode.p2j.util.Finalizable
entry, initFailure, weight

- Field Detail
  - log
```
private static final CentralLogger log
```
    Logger
  - debug
```
private static final boolean debug
```
    Debug logging level
  - blocks
```
private final java.util.Deque<SavepointManager.Block> blocks
```
    Stack of block states which coincide with transaction block scopes
  - session
```
private Session session
```
    Database session used for savepoint processing
  - activeBlock
```
private SavepointManager.Block activeBlock
```
    State of the transaction block which currently is active, if any
  - parentBlock
```
private SavepointManager.Block parentBlock
```
    The current parent block, if any (will be null at a full transaction block)
- Constructor Detail
  - SavepointManager
```
public SavepointManager()
```
    Default constructor.
- Method Detail
  - registerBlockHooks
```
public void registerBlockHooks(TransactionManager.TransactionHelper txHelper,
                               boolean fullTx,
                               int blockDepth)
```
    Register for transaction manager notifications for the current block. This is invoked before the block is entered for sub-transactions, but lazily as the block is entered for full transactions.
    We register for Finalizable and Commitable notifications.
    
    Parameters:
    
    txHelper - Transaction manager helper object with which we register for notifications.
    
    fullTx - true if this is a full-transaction.
    
    blockDepth - zero-based depth of target block, starting from the outermost block. 0 indicates the global block.
  - deregisterGlobalBlockHooks
```
public void deregisterGlobalBlockHooks(TransactionManager.TransactionHelper txHelper)
```
    Deregister the current instance from the transaction manager. This method is called when the TxWrapper instance that created the current instance is cleaned up and the transaction is initiated by TRANSACTION-MODE AUTO, the Finalizable is removed from the global block.
    
    Parameters:
    
    txHelper - Transaction manager helper object with which we register for notifications.
  - finished
```
public void finished()
```
    The block has finished. Clean up.
    
    Specified by:
    
    finished in interface Finalizable
  - deleted
```
public void deleted()
```
    No-op delete hook.
    
    Specified by:
    
    deleted in interface Finalizable
  - iterate
```
public void iterate()
```
    Prepare to iterate through another pass of a looping block. Clean up the block from the previous loop iteration and prepare it for a new iteration.
    
    Specified by:
    
    iterate in interface Finalizable
  - retry
```
public void retry()
```
    Retry a block after handling a condition. Clean up the block from the aborted attempt to process it and prepare it for a retry.
    
    Specified by:
    
    retry in interface Finalizable
  - validate
```
public void validate(boolean transaction,
                     boolean aggressiveFlush)
```
    No-op validation hook.
    
    Specified by:
    
    validate in interface Commitable
    
    Parameters:
    
    transaction - Not used.
    
    aggressiveFlush - Not used.
  - commit
```
public void commit(boolean transaction)
```
    Commit the active block, which entails releasing any savepoint and rolling up tracked resources.
    
    Specified by:
    
    commit in interface Commitable
    
    Parameters:
    
    transaction - true if the current block is a full transaction; false if it is a sub-transaction.
  - rollback
```
public void rollback(boolean transaction)
```
    Roll back the active block, which entails rolling back any savepoint, rolling up tracked resources, and marking any tracked undoable records as stale.
    
    Specified by:
    
    rollback in interface Commitable
    
    Parameters:
    
    transaction - true if the current block is a full transaction; false if it is a sub-transaction.
  - setSession
```
void setSession(Session session)
```
    Install the given session into this savepoint manager.
    
    Parameters:
    
    session - Database session used for savepoint processing.
  - getTxNestingLevel
```
int getTxNestingLevel()
```
    Get the zero-based transaction block nesting level, where 0 indicates the current block is a full transaction block, 1 indicates the current block is the first level of nested subtransaction, and so on. Note that this includes only blocks with transaction properties; no-transaction blocks which may be nested between blocks with transaction properties or ignored for purposes of this count.
    
    Returns:
    
    The current block's transaction nesting level.
  - trackUndoable
```
void trackUndoable(BaseRecord dmo)
            throws PersistenceException
```
    Begin tracking an undoable record as needing savepoint processing. Only record states are stored. On rollback, they will be marked STALE, so the persistence framework can refresh them lazily on first use after the rollback.
    A record is tracked when a change (create/update/delete) has been made to it and that change has been persisted to the database.
    
    Parameters:
    
    dmo - Record to be tracked.
    
    Throws:
    
    PersistenceException - if there is an error lazily setting savepoints in the active block and any ancestor blocks which do not yet have savepoints assigned.
  - lazilySetSavepoints
```
SavepointManager.PersistenceCode lazilySetSavepoints(boolean exceptLast)
                                              throws PersistenceException
```
    Set a savepoint in the active block and in every previous block which has not yet had one set, except for the outermost (which represents the full transaction block).
    We do this lazily, when an actual change is made, rather than as each block is created. This avoids setting "empty" savepoints which never contain updates, thereby preventing many unnecessary round trips to the database.
    
    Parameters:
    
    exceptLast - If true, do not set up the very last block, instead return a lambda code which is prepared to do that. This allows a complete intermediary, short-leved sub-transaction to be executed before the savepoint for this blolck to be set up.
    
    Returns:
    
    a PersistenceCode implementation which will set up the last block with a savepoint.
    
    Throws:
    
    PersistenceException
  - prepareBlock
```
private void prepareBlock()
```
    Prepare a new block and make it the active block. If this is a sub-transaction, set a database savepoint at this time. Otherwise, prepare the block without a savepoint, because the full transaction will be used instead (external to this class) for database-level commit or rollback.
  - cleanupBlock
```
private void cleanupBlock()
```
    End of block processing, which entails discarding the currently active block, re-applying any rolled back changes to a NO-UNDO temporary table, and reactivating the parent block, if any, for further processing. Any commit or rollback hook called after this method is invoked will operate on the reactivated block.
  - setSavepoint
```
private void setSavepoint(SavepointManager.Block block)
                   throws PersistenceException
```
    Set a new savepoint in the database and associate it with the given block.
    
    Parameters:
    
    block - Block with which the savepoint is associated.
    
    Throws:
    
    PersistenceException - if there is a database error setting the savepoint.
  - debug
```
private void debug(java.lang.String message)
```
    Log a debug message if FINE logging is enabled for this class.
    
    Parameters:
    
    message - Message text.

Class SavepointManager

Nested Class Summary

Field Summary

Fields inherited from interface com.goldencode.p2j.persist.orm.DmoState

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Methods inherited from interface com.goldencode.p2j.util.Finalizable

Field Detail

log

debug

blocks

session

activeBlock

parentBlock

Constructor Detail

SavepointManager

Method Detail

registerBlockHooks

deregisterGlobalBlockHooks

finished

deleted

iterate

retry

validate

commit

rollback

setSession

getTxNestingLevel

trackUndoable

lazilySetSavepoints

prepareBlock

cleanupBlock

setSavepoint

debug