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

java.lang.Object
- com.goldencode.p2j.persist.BufferManager

All Implemented Interfaces:

BatchListener, Scopeable, StopConditionVetoHandler
```
public final class BufferManager
extends java.lang.Object
implements Scopeable, BatchListener, StopConditionVetoHandler
```
Manages all record buffers within the current user context. This includes transaction processing, buffer and block scope management. A separate instance of this class is created within each user context. It acts as a broker between the context local TransactionManager, the persistence service layer which manages database resources, and multiple record buffers opened by client code.
A record buffer registers itself with the buffer manager when client code opens a new buffer scope. If a transaction is active, that buffer is immediately registered with the transaction manager for commit processing. This allows the buffer to synchronize its state with the persistence service when a transaction or subtransaction commit occurs. If a transaction is not active when a new buffer scope is opened, the buffer manager keeps track of the open buffer, and the block scope at which it was opened. When a full transaction subsequently is opened, all buffers with open scopes are batch registered for commit processing.
Also, when a full transaction begins, the buffer manager takes stock of all databases referred to by open buffer scopes, and begins a new, database-level transaction for each one. The database transaction's life cycle is managed by an inner class, TxWrapper. This inner class registers itself for master commit and finish processing with the transaction manager, such that it can reflect an application level commit/rollback back to the underlying database transaction.
Updates made to existing records are tracked for undo purposes by this class. A scoped dictionary of reversible updates by DMO type is managed by the context local instance of this class, for all open buffers in the current client context.

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`private static class`	`BufferManager.BatchModeData` Container for batch assign mode information.
`private class`	`BufferManager.PersistentProcScope` Buffer-related data for a certain persistent procedure, surviving after its external procedure is finished.
`private class`	`BufferManager.StaticDefinitionKey` A temp-table key contains the lowercase legacy name of the dataset/table and the procedure where it was created.

Field Summary

Fields
Modifier and Type	Field and Description
`private java.util.Set<Persistence.Context>`	`activePersistenceContexts` Active persistence contexts (those which have an open database session)
`private ScopedDictionary<java.lang.String,RecordBuffer>`	`allBuffers` Scoped dictionary in which all defined record buffers are stored.
`private Finalizable`	`batchCleaner` Finalizable which clears batch mode at the appropriate times
`private java.util.ArrayDeque<BufferManager.BatchModeData>`	`batchModeStack` Stack of batch mode data
`private ScopedDictionary<java.lang.Object,java.util.Map<java.lang.String,RecordBuffer>>`	`byLegacyName` Scoped dictionary in which all defined record buffers are stored.
`private ChangeBroker`	`changeBroker` Change broker instance.
`(package private) java.util.Map<BufferType,MutableInteger>`	`changeScopes` Map of buffer types to high-water block depths of any change to any record of that type
`private static java.util.Map<java.lang.Class<?>,java.util.Set<java.lang.reflect.Field>>`	`classBufferFields` A cache of buffer-related fields defined in a specific legacy-converted class.
`private ConnectionManager`	`connMgr` Connection manager
`private static ContextLocal<BufferManager>`	`context` Stores context local instances of this class
`private LRUCache<java.lang.String,java.lang.String>`	`convertedNames` Buffer names already converted.
`private ScopedDictionary<BufferManager.StaticDefinitionKey,DataSet>`	`dataSetRegistry` The registry with all static `Datasets` mapped by their name.
`private static CentralLogger`	`LOG` Logger
`private NameConverter`	`nc` The cached name converter.
`private boolean`	`nestedQueryError` Does a nested query error condition currently exist?
`private Stack<java.lang.Integer>`	`nextExtScope` Track the external scopes pushed on `BufferManager`.
`private ScopedList<RecordBuffer>`	`openBuffers` Scoped dictionary in which open record buffers are stored
`private ScopedDictionary<BufferManager.StaticDefinitionKey,StaticTempTable>`	`openStaticTempTables` Scoped dictionary which contains currently active static temp tables (i.e.
`private java.util.Map<RecordBuffer,java.lang.Class<?>>`	`pendingBufferClasses` The defining class of a pending buffer, used when initializing an OE class and/or external program.
`private java.util.Set<RecordBuffer>`	`pendingBuffers` The buffers which will be registered on the next scope entry.
`private java.util.Map<Persistence,java.util.Set<java.lang.Long>>`	`pendingReclaimedKeys` Primary keys pending reclamation
`private java.util.Map<StaticTempTable,java.lang.Boolean>`	`pendingStaticTempTables` A map of static temp-tables pending registration.
`private java.util.Map<java.lang.Object,BufferManager.PersistentProcScope>`	`persistProcScopes` Map with buffer-related data surviving a persistent proc's external procedure.
`private ProcedureManager.ProcedureHelper`	`pm` Helper to use the ProcedureManager without any context local lookups.
`private int`	`queryDepth` Number of nested queries being processed
`private ScopedDictionary<OutputTableHandleCopier,java.lang.Integer>`	`thOutputParameters` Scoped dictionary which contains the maps of output copiers for a procedure/function to their 0-based indexes in the set of all TABLE-HANDLE parameters for the procedure/function (excluding other types of parameters).
`private TransactionManager.TransactionHelper`	`txHelper` Transaction helper
`private TxWrapper.TxWrapperHelper`	`txWrapperHelper` Tx wrapper helper.
`private java.util.Map<RecordBuffer,java.lang.Boolean>`	`uninitializedOpenBuffers` Buffers whose scopes have been opened, but are not yet initialized
`private boolean`	`unknownMode` Unknown mode is `true` while evaluating query parameters

Constructor Summary

Constructors
Modifier Constructor and Description

private BufferManager()
Constructor; instances of this class are context-local and must be accessed using the static get() method.

Constructors
Modifier	Constructor and Description
`private`	`BufferManager()` Constructor; instances of this class are context-local and must be accessed using the static `get()` method.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`(package private) java.util.Iterator<RecordBuffer>`	`activeBuffers(Persistence persistence)` Get an iterator on all open buffers which contain non-`null` current records for the given persistence object, within the current client context.
`(package private) java.util.Iterator<RecordBuffer>`	`activeBuffers(Persistence persistence, boolean includeTransient)` Get an iterator on all open buffers which contain non-`null` current records for the given persistence object, within the current client context.
`(package private) void`	`addDirtyBatchBuffer(RecordBuffer buffer)` If we currently are in batch assignment mode, add the given record buffer to the set of buffers requiring validation at the end of the batch.
`(package private) void`	`addPendingReclaimedKeys(Persistence persistence, java.util.List<java.lang.Long> keys)` Add potentially unused keys to be reclaimed after the end of the current transaction or as buffer scopes are closed after a transaction.
`(package private) void`	`addToAllBuffersArray(int blockDepth, RecordBuffer buffer)` Add the target buffer to the set of all buffers at the specified block depth.
`void`	`batchNotify(boolean start)` Provides a notification that a batch is starting or ending.
`void`	`beginTx(boolean inTx, boolean fullTx, int blockDepth)` Executes logic to explicitly begin a transaction.
`(package private) boolean`	`bufferInitialized(RecordBuffer buffer)` A buffer was initialized.
`private void`	`checkLegacyNames(java.util.Map<java.lang.Object,java.util.Map<java.lang.String,RecordBuffer>> dst, java.util.Map<java.lang.Object,java.util.Map<java.lang.String,RecordBuffer>> src)` Add the source buffers to the destination map.
`(package private) void`	`checkNestedQuery(java.util.function.Supplier<java.lang.Boolean> isFindByRowid)` Check whether the current query depth is non-zero, indicating that we are processing a query within the context of another query.
`static void`	`cleanupPending()` Cleanup of pending resources.
`(package private) boolean`	`decrementDepth()` Decrement the query depth.
`private void`	`deregisterByLegacy(java.lang.String lkey, java.util.Map<java.lang.Object,java.util.Map<java.lang.String,RecordBuffer>> refs)` Deregister the buffer from all the defined record buffers stored by the lowercased legacy name.
`(package private) void`	`deregisterDynamicBuffer(RecordBuffer buffer, java.lang.Object referent)` Deregister the given, dynamic record buffer by removing it from the buffer manager's tracking.
`(package private) java.util.Set<RecordBuffer>`	`endBatchAssignMode()` End batch assignment mode if we are currently in batch assignment mode and we are in the same scope at which batch assignment mode was started.
`void`	`endTx(boolean inTx, boolean fullTx)` Executes logic to explicitly end a transaction.
`void`	`endTxPost()` Executes logic required after a full transaction has ended.
`(package private) boolean`	`evictDMOIfUnused(Persistence persistence, Persistence.Context local, Record dmo)` Evict the given DMO from the current ORM session if it is not referenced by any buffer or being tracked for UNDO purposes.
`int`	`findNearestExternal()` Find the nearest external block (from the bottom of the stack).
`(package private) java.lang.String`	`generateUniqueBufferName(java.lang.String legacyBufferName)` Generate unique (across the session) name (DMO alias) for a dynamic buffer.
`static BufferManager`	`get()` Retrieve the context-local instance of this class, instantiating it first if necessary.
`(package private) java.util.Collection<RecordBuffer>`	`getOpenBuffers()` Get the open buffers from the current scope.
`int`	`getOpenBufferScopes()` Query the scope level which currently is open.
`java.lang.Class<?>`	`getPendingBufferClass(RecordBuffer buffer)` Get the defining class for a pending buffer.
`ProcedureManager.ProcedureHelper`	`getProcedureHelper()` Convenient method to retrieve the procedure helper.
`ScopeId`	`getScopeId()` Get the `ScopeId` for the instance.
`long`	`getScopeTransitions()` Get the number of block scope transitions made.
`(package private) DataSet`	`getStaticDataSet(java.lang.Class<?> defType, java.lang.String name, java.lang.Object referent)` Get definition for the active static dataset with the given name.
`(package private) StaticTempTable`	`getStaticTempTable(java.lang.Class<?> defType, java.lang.String name)` Get definition for the active static temp table with the given name.
`(package private) StaticTempTable`	`getStaticTempTable(java.lang.Class<?> defType, java.lang.String name, java.lang.Object referent)` Get definition for the active static temp table with the given name.
`(package private) int`	`getStaticTempTableDepth(StaticTempTable stt)` Get the depth of the scope at which the static temp table was opened.
`(package private) int`	`getStaticTempTableDepth(java.lang.String name)` Get the depth of the scope at which the static temp table was opened.
`(package private) int`	`getStaticTempTableDepth(java.lang.String name, java.lang.Object referent)` Get the depth of the scope at which the static temp table was opened.
`(package private) long`	`getTransactionCount()` Get the current counter value of application-leve transactions which have been opened.
`(package private) TransactionManager.TransactionHelper`	`getTxHelper()` Get the transaction helper object used by this context.
`(package private) TxWrapper.TxWrapperHelper`	`getTxWrapperHelper()` Get the `transaction wrapper` used by this context.
`(package private) boolean`	`incrementDepth()` Increment the query depth.
`(package private) boolean`	`isActiveBuffer(RecordBuffer buffer, Persistence persistence, boolean includeTransient)` Check if the given buffer contains a non-`null` current record for the given persistence object, within the current client context.
`(package private) boolean`	`isBatchAssignMode()` Indicate whether we currently are in batch assignment mode.
`boolean`	`isImportantBlockTransition()` Indicate whether the current block is "important" from the standpoint of transitioning into or out of its scope.
`(package private) boolean`	`isNestedQueryError()` Indicate whether a nested query error has been detected and has not yet been cleared.
`boolean`	`isOutputTableHandle(handle h)` Check if the specified handle instance is registered as an OUTPUT argument.
`boolean`	`isTransaction()` Check whether the current block is within an application-level transaction.
`(package private) boolean`	`isUnknownMode()` Checks whether the unknown mode is active.
`(package private) RecordBuffer`	`lookupBuffer(java.lang.String alias)` Find the record buffer associated with the given DMO alias.
`(package private) RecordBuffer`	`lookupByName(java.lang.String legacyName)` Find the record buffer associated with the given legacy name, which is the variable name with which the buffer was defined.
`(package private) void`	`maybeActivateTxWrapper(Database database)` Given a database which has one or more buffers with an open scope operating within an application level transaction, possibly activate the transaction wrapper associated with that database.
`private void`	`maybeCloseSessions()` Iterate all active persistence contexts and close any open session, if there are no longer any dependencies on it.
`(package private) void`	`notifyRecordWasLoaded(RecordBuffer recordBuffer)` Notify the buffer manager that a new record was loaded (or the old record was reloaded) into the specified record buffer.
`(package private) void`	`openScope(RecordBuffer buffer)` Called by `RecordBuffer` when a new buffer scope is opened.
`(package private) void`	`openScopeAt(int openScopeDepth, RecordBuffer buffer)` Called by `TemporaryBuffer` when a new dynamic buffer scope is opened to register the open scope with the buffer manager, so that the buffer can receive block scope start and stop notifications, and be registered for commit processing when a full transaction is begun.
`boolean`	`postponeTableHandleDelete(TempTable tempTable)` Marks the table for postponed delete, if it is possible.
`(package private) void`	`reclaimPendingKeys(Persistence persistence, java.util.Set<java.lang.Long> released)` Reclaim unused keys collected during the transaction which just ended or from the buffer scope which just closed.
`(package private) void`	`registerBuffer(RecordBuffer buffer)` Register a newly defined record buffer in the current scope.
`(package private) void`	`registerDataSet(java.lang.Class<?> type, java.lang.String name, java.lang.Object ref, DataSet dataset)` Register this static dataset definition.
`void`	`registerDirtyBuffer(RecordBuffer recordBuffer)` Register this buffer as 'dirty' in the current scope.
`(package private) void`	`registerOutputTableHandleCopier(OutputTableHandleCopier copier)` Register the output table copier.
`(package private) void`	`registerPending(java.lang.Class<?> def, RecordBuffer buffer)` Register as pending the newly defined record buffer.
`void`	`registerPendingBufferClass(RecordBuffer buffer, java.lang.Class<?> cls)` Register a pending buffer's defining class.
`static void`	`registerPendingScopeable(BufferManager bufferManager)` Register the `BufferManager` instance as pending scopeable, to be added to the next block.
`(package private) void`	`registerPendingStaticTempTable(StaticTempTable table, boolean global)` Register static temp table, when the external program gets executed.
`(package private) void`	`registerPersistenceContext(Persistence.Context pc)` Register an active persistence context, indicating a database session has been opened.
`static void`	`registerScopeable(BufferManager bufferManager)` Register the `BufferManager` instance as for scope notifications at the current block.
`(package private) void`	`registerStaticTempTable(StaticTempTable table, boolean global)` Register static temp-table when its scope is opened.
`static void`	`registerTxScopeable(BufferManager bufferManager)` Register the `TxWrapper` scopeable as pending for the next opened block.
`void`	`resolvePendingBufferClasses(java.lang.Object referent)` Resolve the defining Java class for all Java fields which define a buffer.
`void`	`scopeDeleted()` Provides notification that the external procedure scope has been deleted.
`void`	`scopeFinished()` Process a notification that a scope is about to be exited.
`void`	`scopeStart(BlockDefinition block)` Process a notification that a new block scope has been entered.
`(package private) boolean`	`setUnknownMode(boolean unknownMode)` Changes the unknown mode.
`(package private) void`	`startBatchAssignMode(boolean internal)` Begin batch assignment mode.
`private void`	`trackDatabase(RecordBuffer buffer, boolean add)` Track the buffer's database.
`(package private) void`	`unregisterOutputTableHandleCopier(OutputTableHandleCopier copier)` Unregister the output table copier in the current scope.
`boolean`	`vetoStop(StopConditionException exc)` Check the specified exception and determine whether we want to allow it to be honored by the `TransactionManager`, or whether we want to veto the STOP at this scope.

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

- Field Detail
  - LOG
```
private static final CentralLogger LOG
```
    Logger
  - context
```
private static final ContextLocal<BufferManager> context
```
    Stores context local instances of this class
  - classBufferFields
```
private static final java.util.Map<java.lang.Class<?>,java.util.Set<java.lang.reflect.Field>> classBufferFields
```
    A cache of buffer-related fields defined in a specific legacy-converted class.
  - changeScopes
```
final java.util.Map<BufferType,MutableInteger> changeScopes
```
    Map of buffer types to high-water block depths of any change to any record of that type
  - batchCleaner
```
private final Finalizable batchCleaner
```
    Finalizable which clears batch mode at the appropriate times
  - pendingBuffers
```
private final java.util.Set<RecordBuffer> pendingBuffers
```
    The buffers which will be registered on the next scope entry.
  - pendingBufferClasses
```
private final java.util.Map<RecordBuffer,java.lang.Class<?>> pendingBufferClasses
```
    The defining class of a pending buffer, used when initializing an OE class and/or external program.
  - allBuffers
```
private final ScopedDictionary<java.lang.String,RecordBuffer> allBuffers
```
    Scoped dictionary in which all defined record buffers are stored. This data structure uses the DMO alias as keys. TODO: this can't be by String, otherwise we can't separate the buffers to its defining class
  - byLegacyName
```
private final ScopedDictionary<java.lang.Object,java.util.Map<java.lang.String,RecordBuffer>> byLegacyName
```
    Scoped dictionary in which all defined record buffers are stored. This data structure uses the lowercased legacy name as keys.
    Note: only the static buffers are kept in this structure. The dynamic resources cannot be stored here as their NAME attribute is mutable and will possible collide with other existing buffers.
  - uninitializedOpenBuffers
```
private final java.util.Map<RecordBuffer,java.lang.Boolean> uninitializedOpenBuffers
```
    Buffers whose scopes have been opened, but are not yet initialized
  - openBuffers
```
private final ScopedList<RecordBuffer> openBuffers
```
    Scoped dictionary in which open record buffers are stored
  - openStaticTempTables
```
private final ScopedDictionary<BufferManager.StaticDefinitionKey,StaticTempTable> openStaticTempTables
```
    Scoped dictionary which contains currently active static temp tables (i.e. table scope was opened and not yet closed). Keyed by a TempTableKey compound from the legacy table name and the procedure where the temp table was defined.
  - dataSetRegistry
```
private ScopedDictionary<BufferManager.StaticDefinitionKey,DataSet> dataSetRegistry
```
    The registry with all static Datasets mapped by their name.
  - pendingStaticTempTables
```
private final java.util.Map<StaticTempTable,java.lang.Boolean> pendingStaticTempTables
```
    A map of static temp-tables pending registration.
  - thOutputParameters
```
private final ScopedDictionary<OutputTableHandleCopier,java.lang.Integer> thOutputParameters
```
    Scoped dictionary which contains the maps of output copiers for a procedure/function to their 0-based indexes in the set of all TABLE-HANDLE parameters for the procedure/function (excluding other types of parameters).
  - activePersistenceContexts
```
private final java.util.Set<Persistence.Context> activePersistenceContexts
```
    Active persistence contexts (those which have an open database session)
  - batchModeStack
```
private final java.util.ArrayDeque<BufferManager.BatchModeData> batchModeStack
```
    Stack of batch mode data
  - persistProcScopes
```
private final java.util.Map<java.lang.Object,BufferManager.PersistentProcScope> persistProcScopes
```
    Map with buffer-related data surviving a persistent proc's external procedure.
  - pendingReclaimedKeys
```
private final java.util.Map<Persistence,java.util.Set<java.lang.Long>> pendingReclaimedKeys
```
    Primary keys pending reclamation
  - pm
```
private final ProcedureManager.ProcedureHelper pm
```
    Helper to use the ProcedureManager without any context local lookups.
  - txHelper
```
private final TransactionManager.TransactionHelper txHelper
```
    Transaction helper
  - txWrapperHelper
```
private TxWrapper.TxWrapperHelper txWrapperHelper
```
    Tx wrapper helper.
  - changeBroker
```
private final ChangeBroker changeBroker
```
    Change broker instance.
  - convertedNames
```
private final LRUCache<java.lang.String,java.lang.String> convertedNames
```
    Buffer names already converted.
  - nextExtScope
```
private final Stack<java.lang.Integer> nextExtScope
```
    Track the external scopes pushed on BufferManager.
  - connMgr
```
private ConnectionManager connMgr
```
    Connection manager
  - queryDepth
```
private int queryDepth
```
    Number of nested queries being processed
  - unknownMode
```
private boolean unknownMode
```
    Unknown mode is true while evaluating query parameters
  - nestedQueryError
```
private boolean nestedQueryError
```
    Does a nested query error condition currently exist?
  - nc
```
private NameConverter nc
```
    The cached name converter.
- Constructor Detail
  - BufferManager
```
private BufferManager()
```
    Constructor; instances of this class are context-local and must be accessed using the static get() method.
- Method Detail
  - get
```
public static BufferManager get()
```
    Retrieve the context-local instance of this class, instantiating it first if necessary.
    
    Returns:
    
    Context-local instance of this class.
  - registerScopeable
```
public static void registerScopeable(BufferManager bufferManager)
```
    Register the BufferManager instance as for scope notifications at the current block.
    
    Parameters:
    
    bufferManager - The BufferManager instance.
  - registerPendingScopeable
```
public static void registerPendingScopeable(BufferManager bufferManager)
```
    Register the BufferManager instance as pending scopeable, to be added to the next block.
    
    Parameters:
    
    bufferManager - The BufferManager instance.
  - registerTxScopeable
```
public static void registerTxScopeable(BufferManager bufferManager)
```
    Register the TxWrapper scopeable as pending for the next opened block.
    
    Parameters:
    
    bufferManager - The BufferManager instance.
  - cleanupPending
```
public static void cleanupPending()
```
    Cleanup of pending resources. This is called when the external procedure constructor failed to build a new object because of an exception thrown in a member initialization (shared frame/table).
  - registerDirtyBuffer
```
public void registerDirtyBuffer(RecordBuffer recordBuffer)
```
    Register this buffer as 'dirty' in the current scope.
    This registration doesn't mean that at the time of TxWrapper.commit(boolean), TxWrapper.rollback(boolean), or TxWrapper.validate(boolean, boolean) the buffer's record is still 'dirty' - this is used to limit the set of buffers receiving such notifications, to avoid iterating over all openBuffers.
    
    Parameters:
    
    recordBuffer - The record buffer.
  - registerPendingBufferClass
```
public void registerPendingBufferClass(RecordBuffer buffer,
                                       java.lang.Class<?> cls)
```
    Register a pending buffer's defining class.
    
    Parameters:
    
    buffer - The newly constructed buffer instance.
    
    cls - The Java class associated with an external program or legacy OE class, where it was defined.
  - getPendingBufferClass
```
public java.lang.Class<?> getPendingBufferClass(RecordBuffer buffer)
```
    Get the defining class for a pending buffer.
    
    Parameters:
    
    buffer - The newly constructed buffer instance.
    
    Returns:
    
    The Java class associated with an external program or legacy OE class, where it was defined.
  - resolvePendingBufferClasses
```
public void resolvePendingBufferClasses(java.lang.Object referent)
```
    Resolve the defining Java class for all Java fields which define a buffer.
    
    Parameters:
    
    referent - The instance associated with an external program or legacy OE class.
  - getOpenBufferScopes
```
public int getOpenBufferScopes()
```
    Query the scope level which currently is open. This is the number of "important" scopes; NO_TRANSACTION blocks inside an application transaction are ignored. So, this number may be lower than the actual number of nested block scopes open, as tracked by the TransactionManager.
    
    Returns:
    
    Number of "important" buffer scopes open, by the above definition.
  - findNearestExternal
```
public int findNearestExternal()
```
    Find the nearest external block (from the bottom of the stack).
    
    Returns:
    
    See above.
  - vetoStop
```
public boolean vetoStop(StopConditionException exc)
```
    Check the specified exception and determine whether we want to allow it to be honored by the TransactionManager, or whether we want to veto the STOP at this scope.
    This implementation is interested only in STOP conditions which have been generated by database connection errors. STOP processing at the current scope is vetoed iff the exception is an instance of DatabaseConnectionException AND either of the following criteria are met:
    - the failing database is one that should be permanently connected to this P2J server instance; OR
    - there is any record buffer still in scope, which is associated with the failing database.
    Otherwise, normal STOP processing is allowed to continue.
    Specified by:
    
    vetoStop in interface StopConditionVetoHandler
    
    Parameters:
    
    exc - The exception to be checked.
    
    Returns:
    
    true if STOP should be vetoed; false if the STOP should be allowed.
  - beginTx
```
public void beginTx(boolean inTx,
                    boolean fullTx,
                    int blockDepth)
```
    Executes logic to explicitly begin a transaction.
    
    Parameters:
    
    inTx - Flag indicating if we are in a transaction.
    
    fullTx - Flag indicating if we are in a full transaction.
    
    blockDepth - The current block depth (all blocks tracked by the TransactionManager).
  - endTx
```
public void endTx(boolean inTx,
                  boolean fullTx)
```
    Executes logic to explicitly end a transaction.
    
    Parameters:
    
    inTx - Flag indicating if we are in a transaction.
    
    fullTx - Flag indicating if we are in a full transaction.
  - endTxPost
```
public void endTxPost()
```
    Executes logic required after a full transaction has ended.
  - scopeStart
```
public void scopeStart(BlockDefinition block)
```
    Process a notification that a new block scope has been entered. Notify every buffer with an open scope that a new block scope has started. If the new block scope is within the context of a transaction, each buffer with an open scope is registered for commit processing with the transaction manager. If the block scope represents the opening of a new, full transaction, we also initialize database transactions for each database referenced by a buffer with an open scope.
    
    Specified by:
    
    scopeStart in interface Scopeable
    
    Parameters:
    
    block - The explicit block definition which required this notification.
    
    Throws:
    
    ErrorConditionException - if there is an error flushing pending changes to the database as we open a new database transaction.
  - scopeFinished
```
public void scopeFinished()
```
    Process a notification that a scope is about to be exited. Notify each record buffer with an open scope that the current block scope is ending.
    
    Specified by:
    
    scopeFinished in interface Scopeable
  - scopeDeleted
```
public void scopeDeleted()
```
    Provides notification that the external procedure scope has been deleted.
    If we are deleting a persistent procedure, clean all its data from the global scope for the following dictionaries: openBuffers, allBuffers, openStaticTempTables.
    
    Specified by:
    
    scopeDeleted in interface Scopeable
  - getScopeId
```
public ScopeId getScopeId()
```
    Get the ScopeId for the instance.
    
    Specified by:
    
    getScopeId in interface Scopeable
    
    Returns:
    
    ScopeId.BUFFER_MANAGER.
  - batchNotify
```
public void batchNotify(boolean start)
```
    Provides a notification that a batch is starting or ending. Enters or exits batch assignment mode for all record buffers in this context, depending on the value of start.
    
    Specified by:
    
    batchNotify in interface BatchListener
    
    Parameters:
    
    start - true if this is the start of a batch, otherwise false.
    
    See Also:
    
    RecordBuffer.startBatch(com.goldencode.p2j.persist.BufferManager, boolean), RecordBuffer.endBatch(com.goldencode.p2j.persist.BufferManager, boolean)
  - postponeTableHandleDelete
```
public boolean postponeTableHandleDelete(TempTable tempTable)
```
    Marks the table for postponed delete, if it is possible. Postponed delete can take place if the table is used as [INPUT-]OUTPUT TABLE-HANDLE parameter.
    
    Parameters:
    
    tempTable - Temporary table to be marked for postponed delete.
    
    Returns:
    
    true if the table was postponed for deletion. false if this can't be done.
  - isTransaction
```
public boolean isTransaction()
```
    Check whether the current block is within an application-level transaction.
    
    Returns:
    
    true if we are in a transaction, else false.
  - getScopeTransitions
```
public long getScopeTransitions()
```
    Get the number of block scope transitions made. This is meant to be a semaphore of sorts, to allow a caller to determine whether this value has changed since some previous point when it was last retrieved. Since it is only meant to detect that the current block has changed over time, we do not protect against overflow.
    
    Returns:
    
    The current unique block ID.
  - getProcedureHelper
```
public ProcedureManager.ProcedureHelper getProcedureHelper()
```
    Convenient method to retrieve the procedure helper. There are many cases where the buffer manager is used and the procedure manager is required. Instead of using this as an intermediate and crowd it with gateway methods towards procedure manager, let the user operate directly on the procedure helper.
    
    Returns:
    
    The procedure helper used by this buffer manager.
  - getOpenBuffers
```
java.util.Collection<RecordBuffer> getOpenBuffers()
```
    Get the open buffers from the current scope.
    
    Returns:
    
    See above.
  - getTransactionCount
```
long getTransactionCount()
```
    Get the current counter value of application-leve transactions which have been opened.
    
    Returns:
    
    Transaction count.
  - getTxWrapperHelper
```
TxWrapper.TxWrapperHelper getTxWrapperHelper()
```
    Get the transaction wrapper used by this context.
    
    Returns:
    
    See above.
  - getTxHelper
```
TransactionManager.TransactionHelper getTxHelper()
```
    Get the transaction helper object used by this context.
    
    Returns:
    
    Transaction helper.
  - registerPersistenceContext
```
void registerPersistenceContext(Persistence.Context pc)
```
    Register an active persistence context, indicating a database session has been opened.
    
    Parameters:
    
    pc - Persistence context.
  - registerDataSet
```
void registerDataSet(java.lang.Class<?> type,
                     java.lang.String name,
                     java.lang.Object ref,
                     DataSet dataset)
```
    Register this static dataset definition.
    
    Parameters:
    
    type - The definition type.
    
    name - The legacy name.
    
    ref - The instance where it is defined.
    
    dataset - The dataset instance to register.
  - registerBuffer
```
void registerBuffer(RecordBuffer buffer)
```
    Register a newly defined record buffer in the current scope. Buffers are deregistered implicitly when the scope in which they were registered ends.
    
    Parameters:
    
    buffer - Buffer to be registered.
  - registerPending
```
void registerPending(java.lang.Class<?> def,
                     RecordBuffer buffer)
```
    Register as pending the newly defined record buffer. When the next scope is entered, all the pendingBuffers will be registered with that scope. Buffers are deregistered implicitly when the scope in which they were registered ends.
    
    Parameters:
    
    def - The Java class defining this buffer.
    
    buffer - Buffer pending to be registered.
  - deregisterDynamicBuffer
```
void deregisterDynamicBuffer(RecordBuffer buffer,
                             java.lang.Object referent)
```
    Deregister the given, dynamic record buffer by removing it from the buffer manager's tracking.
    
    Parameters:
    
    buffer - Dynamic record buffer to be removed.
    
    referent - The persistent procedure where the buffer was defined; may be null.
  - deregisterByLegacy
```
private void deregisterByLegacy(java.lang.String lkey,
                                java.util.Map<java.lang.Object,java.util.Map<java.lang.String,RecordBuffer>> refs)
```
    Deregister the buffer from all the defined record buffers stored by the lowercased legacy name.
    
    Parameters:
    
    lkey - Lowercased legacy name key
    
    refs - Scoped dictionary that uses the lowercased legacy name as keys in which all defined record buffers are stored.
  - startBatchAssignMode
```
void startBatchAssignMode(boolean internal)
```
    Begin batch assignment mode. While in this mode, validation of record buffers is deferred. We remember the scope at which this occurs in order to test for errors now and allow proper cleanup later.
    
    Parameters:
    
    internal - Use false for a programmer required batch assign mode. These can be started at most one at each scope depth.
    Use true for a FWD internal maintenance batch block when some data must be processed "in batch". In this case the depth, is not checked. Only one level of this can be added as the top-level. This mode must be be ended before starting any new batch.
    
    Throws:
    
    java.lang.IllegalStateException - if batch mode is already active in the current block or was started but never ended in a previous block.
    
    See Also:
    
    RecordBuffer.startBatch(com.goldencode.p2j.persist.BufferManager, boolean), RecordBuffer.endBatch(com.goldencode.p2j.persist.BufferManager, boolean), RecordBuffer.cleanupBatchMode(com.goldencode.p2j.persist.BufferManager)
  - endBatchAssignMode
```
java.util.Set<RecordBuffer> endBatchAssignMode()
```
    End batch assignment mode if we are currently in batch assignment mode and we are in the same scope at which batch assignment mode was started. Otherwise do nothing.
    
    Returns:
    
    If the above conditions are met for batch mode to end, the set of record buffers which were modified during batch mode is returned. Otherwise, return null, indicating either we are not in batch mode, or we are not in the proper scope to end it, or the buffers already have been processed, or the program is ending and we are in cleanup mode.
    
    See Also:
    
    RecordBuffer.startBatch(com.goldencode.p2j.persist.BufferManager, boolean), RecordBuffer.endBatch(com.goldencode.p2j.persist.BufferManager, boolean), RecordBuffer.cleanupBatchMode(com.goldencode.p2j.persist.BufferManager)
  - isBatchAssignMode
```
boolean isBatchAssignMode()
```
    Indicate whether we currently are in batch assignment mode.
    
    Returns:
    
    true if in batch assignment mode, else false.
    
    See Also:
    
    startBatchAssignMode(boolean), endBatchAssignMode()
  - addDirtyBatchBuffer
```
void addDirtyBatchBuffer(RecordBuffer buffer)
```
    If we currently are in batch assignment mode, add the given record buffer to the set of buffers requiring validation at the end of the batch. Otherwise, do nothing.
    
    Parameters:
    
    buffer - Buffer to be added to the set of dirty batch mode buffers.
    
    See Also:
    
    startBatchAssignMode(boolean), endBatchAssignMode()
  - incrementDepth
```
boolean incrementDepth()
```
    Increment the query depth.
    This method MUST be invoked in balanced pairs that involve a subsequent call to decrementDepth(). Calls may be nested, but they must be balanced, such that at the end of all nested calls, queryDepth must be 0.
    
    Returns:
    
    true if the starting depth is 0.
  - decrementDepth
```
boolean decrementDepth()
```
    Decrement the query depth.
    This method MUST be invoked in balanced pairs that involve a subsequent call to incrementDepth(). Calls may be nested, but they must be balanced, such that at the end of all nested calls, queryDepth must be 0.
    
    Returns:
    
    true if the resulting depth is 0.
  - checkNestedQuery
```
void checkNestedQuery(java.util.function.Supplier<java.lang.Boolean> isFindByRowid)
```
    Check whether the current query depth is non-zero, indicating that we are processing a query within the context of another query. If so, raise a 7254 error condition, unless the current query represents a legacy FIND by RECID/ROWID, which is permitted to run within such context.
    
    Parameters:
    
    isFindByRowid - A lambda expression which should return true if the current database operation represents a legacy FIND by RECID/ROWID, else false.
  - isNestedQueryError
```
boolean isNestedQueryError()
```
    Indicate whether a nested query error has been detected and has not yet been cleared.
    
    Returns:
    
    true if a nested query error has been detected, else false.
  - setUnknownMode
```
boolean setUnknownMode(boolean unknownMode)
```
    Changes the unknown mode.
    
    Parameters:
    
    unknownMode - The new unknown mode.
    
    Returns:
    
    A Runnable which should be called in a finally block, paired with the call to this method, which restores the unknown mode to its previous value.
  - isUnknownMode
```
boolean isUnknownMode()
```
    Checks whether the unknown mode is active.
    
    Returns:
    
    the current state of unknown mode flag.
  - addPendingReclaimedKeys
```
void addPendingReclaimedKeys(Persistence persistence,
                             java.util.List<java.lang.Long> keys)
```
    Add potentially unused keys to be reclaimed after the end of the current transaction or as buffer scopes are closed after a transaction. Some of these keys may not be collected, if the locks on them are downgraded instead of released.
    
    Parameters:
    
    persistence - Persistence helper object for a particular database.
    
    keys - Keys to be reclaimed.
  - reclaimPendingKeys
```
void reclaimPendingKeys(Persistence persistence,
                        java.util.Set<java.lang.Long> released)
```
    Reclaim unused keys collected during the transaction which just ended or from the buffer scope which just closed.
    
    Parameters:
    
    persistence - Persistence helper object for a particular database.
    
    released - Keys actually released, due to the corresponding locks on them being released (as opposed to downgraded).
  - openScope
```
void openScope(RecordBuffer buffer)
```
    Called by RecordBuffer when a new buffer scope is opened. It registers the open scope with the buffer manager, so that the buffer can receive block scope start and stop notifications, and be registered for commit/rollback/validate processing when a full transaction is begun.
    
    Parameters:
    
    buffer - Buffer for which a new scope is being opened.
  - registerStaticTempTable
```
void registerStaticTempTable(StaticTempTable table,
                             boolean global)
```
    Register static temp-table when its scope is opened.
    
    Parameters:
    
    table - The static temp-table.
    
    global - Indicates if it is a global temp-table (declared as SHARED GLOBAL).
  - registerPendingStaticTempTable
```
void registerPendingStaticTempTable(StaticTempTable table,
                                    boolean global)
```
    Register static temp table, when the external program gets executed.
    
    Parameters:
    
    table - The static temp-table.
    
    global - Indicates if it is a global temp table (declared as SHARED GLOBAL).
  - isOutputTableHandle
```
public boolean isOutputTableHandle(handle h)
```
    Check if the specified handle instance is registered as an OUTPUT argument.
    
    Parameters:
    
    h - The handle instance.
    
    Returns:
    
    true if the handle originates from the caller as an OUTPUT argument.
  - registerOutputTableHandleCopier
```
void registerOutputTableHandleCopier(OutputTableHandleCopier copier)
```
    Register the output table copier.
    
    Parameters:
    
    copier - Copier to register.
  - unregisterOutputTableHandleCopier
```
void unregisterOutputTableHandleCopier(OutputTableHandleCopier copier)
```
    Unregister the output table copier in the current scope.
    
    Parameters:
    
    copier - Copier to unregister.
  - getStaticTempTable
```
StaticTempTable getStaticTempTable(java.lang.Class<?> defType,
                                   java.lang.String name)
```
    Get definition for the active static temp table with the given name.
    
    Parameters:
    
    defType - The type where this call is being made from.
    
    name - Legacy name of the target static temp table.
    
    Returns:
    
    Definition of the static temp table with the given name or null if there is no active table with the given name.
  - getStaticDataSet
```
DataSet getStaticDataSet(java.lang.Class<?> defType,
                         java.lang.String name,
                         java.lang.Object referent)
```
    Get definition for the active static dataset with the given name.
    The lookup is done first from super-classes and after that in dataSetRegistry.
    
    Parameters:
    
    defType - The type where this call is being made from.
    
    name - Legacy name of the target static dataset.
    
    referent - The reference used to lookup this dataset by name.
    
    Returns:
    
    The found dataset with the same legacy name.
  - getStaticTempTable
```
StaticTempTable getStaticTempTable(java.lang.Class<?> defType,
                                   java.lang.String name,
                                   java.lang.Object referent)
```
    Get definition for the active static temp table with the given name.
    
    Parameters:
    
    defType - The type where this call is being made from.
    
    name - Legacy name of the target static temp table.
    
    referent - The external program where it was defined.
    
    Returns:
    
    definition of the static temp table with the given name or null if there is no active table with the given name.
  - getStaticTempTableDepth
```
int getStaticTempTableDepth(java.lang.String name)
```
    Get the depth of the scope at which the static temp table was opened.
    
    Parameters:
    
    name - Legacy name of the target static temp table.
    
    Returns:
    
    zero-based index of the target scope, starting from the outermost scope. If there is no table with the given name, -1 is returned.
  - getStaticTempTableDepth
```
int getStaticTempTableDepth(StaticTempTable stt)
```
    Get the depth of the scope at which the static temp table was opened.
    
    Parameters:
    
    stt - The static temp-table instance.
    
    Returns:
    
    zero-based index of the target scope, starting from the outermost scope. If there is no table with the given name, -1 is returned.
  - getStaticTempTableDepth
```
int getStaticTempTableDepth(java.lang.String name,
                            java.lang.Object referent)
```
    Get the depth of the scope at which the static temp table was opened.
    
    Parameters:
    
    name - Legacy name of the target static temp table.
    
    referent - The external program where it was defined.
    
    Returns:
    
    zero-based index of the target scope, starting from the outermost scope. If there is no table with the given name, -1 is returned.
  - addToAllBuffersArray
```
void addToAllBuffersArray(int blockDepth,
                          RecordBuffer buffer)
```
    Add the target buffer to the set of all buffers at the specified block depth.
    
    Parameters:
    
    blockDepth - Zero-based depth of the block (starting from the outermost block) at which the buffer was opened.
    
    buffer - Buffer to add.
  - openScopeAt
```
void openScopeAt(int openScopeDepth,
                 RecordBuffer buffer)
```
    Called by TemporaryBuffer when a new dynamic buffer scope is opened to register the open scope with the buffer manager, so that the buffer can receive block scope start and stop notifications, and be registered for commit processing when a full transaction is begun.
    
    Parameters:
    
    openScopeDepth - Zero-based depth of the open scopes (starting from the outermost scope) at which this buffer scope is opened.
    
    buffer - Buffer for which a new scope is being opened.
  - bufferInitialized
```
boolean bufferInitialized(RecordBuffer buffer)
```
    A buffer was initialized. If it was previously stored as an uninitialized, open buffer, move it into the active, open buffers list. Perform special handling for persistent procedure buffers.
    
    Parameters:
    
    buffer - Record buffer which was initialized.
    
    Returns:
    
    true if this was properly registered as an open buffer. false if this couldn't be properly registered because the scope wasn't opened properly beforehand.
  - maybeActivateTxWrapper
```
void maybeActivateTxWrapper(Database database)
```
    Given a database which has one or more buffers with an open scope operating within an application level transaction, possibly activate the transaction wrapper associated with that database. Activation entails starting a database-level transaction and activating a savepoint manager for that transaction.
    If the transaction wrapper for the given database already is active, do nothing.
    
    Parameters:
    
    database - Database with at least one buffer with an open scope.
  - lookupBuffer
```
RecordBuffer lookupBuffer(java.lang.String alias)
```
    Find the record buffer associated with the given DMO alias.
    
    Parameters:
    
    alias - Buffer DMO alias in business logic. (AKA Java name)
    
    Returns:
    
    Associated record buffer or null if not found.
  - lookupByName
```
RecordBuffer lookupByName(java.lang.String legacyName)
```
    Find the record buffer associated with the given legacy name, which is the variable name with which the buffer was defined. Because this method is legally called only after the procedure block started, the lookup is not performed on a structure similar to pendingBuffers.
    
    Parameters:
    
    legacyName - Buffer variable's legacy name in business logic.
    
    Returns:
    
    Associated record buffer or null if not found.
  - activeBuffers
```
java.util.Iterator<RecordBuffer> activeBuffers(Persistence persistence)
```
    Get an iterator on all open buffers which contain non-null current records for the given persistence object, within the current client context. Auto-commit record buffers associated with a pending, reversible rollback are not included in the iteration. Records that represent copies of DMOs from other sessions, obtained from a DirtyShareContext, are likewise excluded.
    
    Parameters:
    
    persistence - Persistence object which manages sessions. Only record buffers associated with this persistence object are returned.
    
    Returns:
    
    Iterator on all active buffers.
  - activeBuffers
```
java.util.Iterator<RecordBuffer> activeBuffers(Persistence persistence,
                                               boolean includeTransient)
```
    Get an iterator on all open buffers which contain non-null current records for the given persistence object, within the current client context. Auto-commit record buffers associated with a pending, reversible rollback are not included in the iteration. Records that represent copies of DMOs from other sessions, obtained from a DirtyShareContext, are likewise excluded.
    
    Parameters:
    
    persistence - Persistence object which manages sessions. Only record buffers associated with this persistence object are returned.
    
    includeTransient - true to include transient records in the result set.
    
    Returns:
    
    Iterator on all active buffers.
  - isActiveBuffer
```
boolean isActiveBuffer(RecordBuffer buffer,
                       Persistence persistence,
                       boolean includeTransient)
```
    Check if the given buffer contains a non-null current record for the given persistence object, within the current client context. Auto-commit record buffers associated with a pending, reversible rollback are not included in the iteration. Records that represent copies of DMOs from other sessions, obtained from a DirtyShareContext, are likewise excluded.
    
    Parameters:
    
    buffer - RecordBuffer that is checked.
    
    persistence - Persistence object which manages sessions. Only record buffers associated with this persistence object are returned.
    
    includeTransient - true to include transient records in the result set.
    
    Returns:
    
    true if the buffer has a non-null current record, false otherwise.
  - evictDMOIfUnused
```
boolean evictDMOIfUnused(Persistence persistence,
                         Persistence.Context local,
                         Record dmo)
                  throws PersistenceException
```
    Evict the given DMO from the current ORM session if it is not referenced by any buffer or being tracked for UNDO purposes. This method does not modify the DMO's in-use status. It is intended to quickly evict DMOs which have been loaded into the session by side effect.
    
    Parameters:
    
    persistence - Persistence object which manages sessions.
    
    local - Current user persistence context.
    
    dmo - DMO instance whose reference count is to be decremented.
    
    Returns:
    
    true if the DMO was evicted; false if it was in use.
    
    Throws:
    
    PersistenceException - if an error occurs detaching dmo from the persistence session.
  - notifyRecordWasLoaded
```
void notifyRecordWasLoaded(RecordBuffer recordBuffer)
```
    Notify the buffer manager that a new record was loaded (or the old record was reloaded) into the specified record buffer.
    
    Parameters:
    
    recordBuffer - The record buffer in which a record was loaded (or the old record was reloaded).
  - generateUniqueBufferName
```
java.lang.String generateUniqueBufferName(java.lang.String legacyBufferName)
```
    Generate unique (across the session) name (DMO alias) for a dynamic buffer. The name is generated by using standard P2J buffer name conversion rules and if necessary, appending __{unique number} postfix. This guarantees that the name will not contain invalid characters and will be unique.
    
    Parameters:
    
    legacyBufferName - Legacy name of the buffer.
    
    Returns:
    
    unique name (alias) for a dynamic buffer.
  - maybeCloseSessions
```
private void maybeCloseSessions()
```
    Iterate all active persistence contexts and close any open session, if there are no longer any dependencies on it. This method deregisters an active persistence context by side effect, if its open session was closed.
  - checkLegacyNames
```
private void checkLegacyNames(java.util.Map<java.lang.Object,java.util.Map<java.lang.String,RecordBuffer>> dst,
                              java.util.Map<java.lang.Object,java.util.Map<java.lang.String,RecordBuffer>> src)
```
    Add the source buffers to the destination map.
    
    Parameters:
    
    dst - The destination map.
    
    src - The source map.
  - trackDatabase
```
private void trackDatabase(RecordBuffer buffer,
                           boolean add)
```
    Track the buffer's database. This will increment the TxWrapper.WorkArea.activeDatabases counter when a new buffer is activated, and decrement it when it exists its scope.
    
    Parameters:
    
    buffer - The buffer to track.
    
    add - Flag indicating if the buffer is opening or closing the scope.
    
    Throws:
    
    java.lang.IllegalStateException - If we are removing an active buffer and there is no entry for it in TxWrapper.WorkArea.activeDatabases.
  - isImportantBlockTransition
```
public boolean isImportantBlockTransition()
```
    Indicate whether the current block is "important" from the standpoint of transitioning into or out of its scope. A block is considered "important" in this sense if it is either completely outside of an application transaction, or if it is within a transaction AND has transaction block properties (i.e., is not a NO_TRANSACTION block).
    This notion of importance is used to determine whether the various scoped data structures managed by this class need to add or delete a scope when transitioning into or out of the block, respectively, and whether we need to perform processing (e.g., copying/moving data between scopes) associated with such transitions.
    
    Returns:
    
    true if the block is considered "important" by the above criteria, else false.

Class BufferManager

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

LOG

context

classBufferFields

changeScopes

batchCleaner

pendingBuffers

pendingBufferClasses

allBuffers

byLegacyName

uninitializedOpenBuffers

openBuffers

openStaticTempTables

dataSetRegistry

pendingStaticTempTables

thOutputParameters

activePersistenceContexts

batchModeStack

persistProcScopes

pendingReclaimedKeys

pm

txHelper

txWrapperHelper

changeBroker

convertedNames

nextExtScope

connMgr

queryDepth

unknownMode

nestedQueryError

nc

Constructor Detail

BufferManager

Method Detail

get

registerScopeable

registerPendingScopeable

registerTxScopeable

cleanupPending

registerDirtyBuffer

registerPendingBufferClass

getPendingBufferClass

resolvePendingBufferClasses

getOpenBufferScopes

findNearestExternal

vetoStop

beginTx

endTx

endTxPost

scopeStart

scopeFinished

scopeDeleted

getScopeId

batchNotify

postponeTableHandleDelete

isTransaction

getScopeTransitions

getProcedureHelper

getOpenBuffers

getTransactionCount

getTxWrapperHelper

getTxHelper

registerPersistenceContext

registerDataSet

registerBuffer

registerPending

deregisterDynamicBuffer

deregisterByLegacy

startBatchAssignMode

endBatchAssignMode

isBatchAssignMode

addDirtyBatchBuffer

incrementDepth

decrementDepth