Persistence.Context (P2J - Progress 4GL to Java Conversion and Runtime)

java.lang.Object
- com.goldencode.p2j.persist.Persistence.Context

All Implemented Interfaces:

TenantChangeListener

Enclosing class:

Persistence
```
class Persistence.Context
extends java.lang.Object
implements TenantChangeListener
```
A storage and work area for context-local variables used by the enclosing class. One instance of this class is created for each client context. It is used to:
- create and cache query objects;
- create, store and close the active database session;
- manage the active database transaction.
Special care is taken to not close a database session while other entities are dependent upon it for services.

Field Summary

Fields
Modifier and Type	Field and Description
`private java.lang.Throwable`	`beginTxTrace` Throwable which holds stack trace where last transaction began
`private BufferManager`	`bufferManager` Context-local buffer manager
`private boolean`	`closingSession` Flag to prevent nested session close attempts
`private Database`	`contextDatabase` The database instance assigned to this context.
`private java.lang.Object`	`dialectData` Optional, dialect-specific, context-local data
`private SessionFactory`	`factory` A factory that allows a session to be reclaimed
`private FastFindCache`	`ffCache` Cache for FIND results.
`private RecordLockContext`	`lockContext` Context-local record lock context
`private RecordNursery`	`nursery` Object which manages newly created records
`private int`	`openSessionCount` Count of open database sessions in this context
`private boolean`	`rereadNoLock` rereadnolock command-line parameter, by default deactivated
`private Session`	`session` Active database session, if any
`private java.util.WeakHashMap<SessionListener,Finalizable>`	`sessionListeners` Session listener objects
`private int`	`sessionUseCount` Reference count of resources dependent upon current session
`private ExpiryCache<Persistence.QueryKey,Query>`	`staticQueryCache` Cache of FQL strings, with or without max results and start offsets, to queries.
`private java.lang.String`	`tenantId` The id of the tenant that was assigned to this context, if any.
`private boolean`	`traceTx` Enable tracing transaction starts
`private boolean`	`unsafe` Flag used to indicate if default exception handling is used.

Constructor Summary

Constructors
Modifier Constructor and Description

private Context()
The default constructor reads rereadNoLock from directory.

Constructors
Modifier	Constructor and Description
`private`	`Context()` The default constructor reads rereadNoLock from directory.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`(package private) boolean`	`beginTransaction(SavepointManager savepointManager)` Begin a new database transaction and remember that it is open, for related calls.
`(package private) boolean`	`canCloseSession()` Indicate whether there is an open session and if so, whether it can be closed.
`(package private) void`	`cleanup()` Cleanup hook invoked at the end of the current client context.
`(package private) boolean`	`closeSession(boolean error)` Attempt to close the database session associated with this context, and indicate whether the attempt was successful.
`private boolean`	`closeSessionImpl(boolean error, boolean force)` Attempt to close the database session associated with this context, and indicate whether the attempt was successful.
`(package private) void`	`commit()` Commit the current database transaction.
`(package private) void`	`deregisterSessionListener(SessionListener listener)` Explicitly deregister a global session listener, which represents a dynamic temp-table resource which has been deleted explicitly.
`(package private) void`	`enableTransactionTrace(boolean enable)` Set enable mode for transaction tracing.
`(package private) java.lang.Throwable`	`getBeginTxTrace()` Retrieve trace information about where the current transaction, if any, was started.
`(package private) Database`	`getDatabase()` Get the database information object associated with this persistence context.
`(package private) java.lang.Object`	`getDialectData()` Get the context-local, dialect-specific data object, if any.
`(package private) FastFindCache`	`getFastFindCache()` Getter for the `ffCache` field.
`(package private) RecordNursery`	`getNursery()` Get the record nursery.
`(package private) Persistence`	`getPersistence()` Get the `Persistence` object associated with this context.
`(package private) Query`	`getQuery(java.lang.String fql, int maxResults, int startOffset, DataRelation relation)` Get a cached query for the given combination of FQL query string, maximum result rows, and starting row offset, creating and caching a new query if no such query already is cached.
`(package private) Query`	`getQuery(java.lang.String fql, int maxResults, int startOffset, DataRelation relation, boolean lazyMode)` Get a cached query for the given combination of FQL query string, maximum result rows, and starting row offset, creating and caching a new query if no such query already is cached.
`(package private) RecordLockContext`	`getRecordLockContext()` Get the record lock context associated with the current client session.
`(package private) Session`	`getSession()` Retrieve the ORM `Session` object associated with this context, creating it if necessary.
`(package private) Session`	`getSession(java.lang.String tenantId, java.lang.String ldbName)` Retrieve the ORM `Session` object associated with this context, creating it if necessary.
`(package private) Session`	`getSessionNoCreate()` Retrieve the ORM `Session` object associated with this context, if any.
`(package private) java.lang.String`	`getTenantId()` The id of the tenant that was assigned to this context, if any.
`(package private) boolean`	`isAutoCommit()` Indicate whether auto-commit is needed; this is the case for temp-tables being modified outside of an explicit transaction.
`(package private) boolean`	`isRereadNoLock()` Checks if the rereadnolock 4GL command-line option is active for this client context.
`(package private) boolean`	`isTransactionOpen()` Indicate whether a database-level transaction currently is open.
`(package private) boolean`	`isUnsafe()` Checks whether this persistence context is unsafe or not.
`private void`	`notifySessionEvent(SessionListener.Event event)` Notify all registered session listeners that the current ORM session is about to close or the current, implicit transaction is being committed.
`(package private) void`	`postTransaction(boolean rollback)` Perform post-processing and cleanup after a transaction commit or rollback.
`(package private) void`	`registerSessionListener(SessionListener listener, SessionListener.Scope scope)` Register a `SessionListener` to receive session life cycle event notifications.
`(package private) void`	`releaseSession()` Decrement the session use count, indicating the removal of a dependency on the open session.
`(package private) void`	`rollback(boolean error)` Roll back the current transaction and possibly close the current session.
`(package private) void`	`setTenantDatabase(Database db, boolean skipRegistering)` Set the database that will be used in this context.
`(package private) void`	`setUnsafe(boolean value)` Decide whether this persistence context is unsafe or not.
`void`	`tenantChanged(java.lang.String tenantId, java.lang.String ldbName)` When a tenant id is changed, we need to re-open the session, but taking into account the new tenant's id.
`(package private) void`	`useSession()` Increment the session use count, indicating the addition of a dependency on the open session.

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

- Field Detail
  - staticQueryCache
```
private final ExpiryCache<Persistence.QueryKey,Query> staticQueryCache
```
    Cache of FQL strings, with or without max results and start offsets, to queries.
  - bufferManager
```
private final BufferManager bufferManager
```
    Context-local buffer manager
  - contextDatabase
```
private Database contextDatabase
```
    The database instance assigned to this context.
  - ffCache
```
private FastFindCache ffCache
```
    Cache for FIND results.
  - nursery
```
private RecordNursery nursery
```
    Object which manages newly created records
  - lockContext
```
private final RecordLockContext lockContext
```
    Context-local record lock context
  - sessionListeners
```
private final java.util.WeakHashMap<SessionListener,Finalizable> sessionListeners
```
    Session listener objects
  - session
```
private Session session
```
    Active database session, if any
  - sessionUseCount
```
private int sessionUseCount
```
    Reference count of resources dependent upon current session
  - closingSession
```
private boolean closingSession
```
    Flag to prevent nested session close attempts
  - openSessionCount
```
private volatile int openSessionCount
```
    Count of open database sessions in this context
  - dialectData
```
private final java.lang.Object dialectData
```
    Optional, dialect-specific, context-local data
  - rereadNoLock
```
private boolean rereadNoLock
```
    rereadnolock command-line parameter, by default deactivated
  - traceTx
```
private boolean traceTx
```
    Enable tracing transaction starts
  - beginTxTrace
```
private java.lang.Throwable beginTxTrace
```
    Throwable which holds stack trace where last transaction began
  - factory
```
private SessionFactory factory
```
    A factory that allows a session to be reclaimed
  - tenantId
```
private java.lang.String tenantId
```
    The id of the tenant that was assigned to this context, if any.
  - unsafe
```
private boolean unsafe
```
    Flag used to indicate if default exception handling is used.
- Constructor Detail
  - Context
```
private Context()
```
    The default constructor reads rereadNoLock from directory.
- Method Detail
  - tenantChanged
```
public void tenantChanged(java.lang.String tenantId,
                          java.lang.String ldbName)
```
    When a tenant id is changed, we need to re-open the session, but taking into account the new tenant's id.
    
    Specified by:
    
    tenantChanged in interface TenantChangeListener
    
    Parameters:
    
    tenantId - The new tenant's id.
    
    ldbName - The logical name of the database that the tenant will use in this context.
  - getDatabase
```
Database getDatabase()
```
    Get the database information object associated with this persistence context.
    
    Returns:
    
    Database information object.
  - getRecordLockContext
```
RecordLockContext getRecordLockContext()
```
    Get the record lock context associated with the current client session.
    
    Returns:
    
    Record lock context for the current session.
  - getPersistence
```
Persistence getPersistence()
```
    Get the Persistence object associated with this context.
    
    Returns:
    
    Persistence object.
  - useSession
```
void useSession()
```
    Increment the session use count, indicating the addition of a dependency on the open session. As long as there are dependencies on the session, it may not close.
  - releaseSession
```
void releaseSession()
```
    Decrement the session use count, indicating the removal of a dependency on the open session. As long as there are dependencies on the session, it may not close.
  - canCloseSession
```
boolean canCloseSession()
```
    Indicate whether there is an open session and if so, whether it can be closed. An open session may only be closed if there are no dependencies on it.
    
    Returns:
    
    true if there is an open session which may be closed; otherwise false.
  - getQuery
```
Query getQuery(java.lang.String fql,
               int maxResults,
               int startOffset,
               DataRelation relation)
        throws PersistenceException
```
    Get a cached query for the given combination of FQL query string, maximum result rows, and starting row offset, creating and caching a new query if no such query already is cached. The cache is fixed size. When it is full and a new query needs to be added, the least recently used query is removed.
    
    Parameters:
    
    fql - FQL query string.
    
    maxResults - The maximum number of results to be returned.
    
    startOffset - Zero-based offset of first result to be returned (undefined results unless fql includes an order by phrase).
    
    relation - The recursive DATA-RELATION the query is to FILL for.
    
    Returns:
    
    A Query object for the requested fql.
    
    Throws:
    
    PersistenceException - if there was an error creating an ORM session.
  - getQuery
```
Query getQuery(java.lang.String fql,
               int maxResults,
               int startOffset,
               DataRelation relation,
               boolean lazyMode)
        throws PersistenceException
```
    Get a cached query for the given combination of FQL query string, maximum result rows, and starting row offset, creating and caching a new query if no such query already is cached. The cache is fixed size. When it is full and a new query needs to be added, the least recently used query is removed.
    
    Parameters:
    
    fql - FQL query string.
    
    maxResults - The maximum number of results to be returned.
    
    startOffset - Zero-based offset of first result to be returned (undefined results unless fql includes an order by phrase).
    
    relation - The recursive DATA-RELATION the query is to FILL for.
    
    lazyMode - Flag that indicates whether the query should be executed in a lazy manner.
    
    Returns:
    
    A Query object for the requested fql.
    
    Throws:
    
    PersistenceException - if there was an error creating an ORM session.
  - commit
```
void commit()
     throws PersistenceException
```
    Commit the current database transaction. If the transaction cannot be committed, roll it back and raise an error.
    
    Throws:
    
    java.lang.IllegalStateException - if no transaction is active in the current session; this represents a programming error.
    
    PersistenceException - if there is an error committing the transaction.
  - rollback
```
void rollback(boolean error)
       throws PersistenceException
```
    Roll back the current transaction and possibly close the current session. If the transaction cannot be rolled back, raise an error.
    
    Parameters:
    
    error - Indicates whether the rollback is due to an error.
    
    Throws:
    
    java.lang.IllegalStateException - if no transaction is active in the current session; this represents a programming error.
    
    PersistenceException - if there is an error rolling back the transaction.
  - enableTransactionTrace
```
void enableTransactionTrace(boolean enable)
```
    Set enable mode for transaction tracing.
    
    Parameters:
    
    enable - true to enable; false to disable.
  - beginTransaction
```
boolean beginTransaction(SavepointManager savepointManager)
                  throws PersistenceException
```
    Begin a new database transaction and remember that it is open, for related calls. If a transaction already exists, return false, and do not begin a new one. A new database session is created if one does not already exist in the current context.
    
    Parameters:
    
    savepointManager - A savepoint manager to install in the session while the transaction is active. May be null for ad-hoc transactions, but must not be null when the databbase transaction is being opened in association with a legacy application transaction.
    
    Returns:
    
    true if a new database transaction was opened successfully; false if a transaction already exists.
    
    Throws:
    
    PersistenceException - if there is an error beginning the new transaction.
  - postTransaction
```
void postTransaction(boolean rollback)
              throws PersistenceException
```
    Perform post-processing and cleanup after a transaction commit or rollback.
    
    Parameters:
    
    rollback - Indicates whether the transaction is being ended after a rollback (as opposed to a commit).
    
    Throws:
    
    PersistenceException - if an error occurs performing post-transaction processing, if any.
  - getBeginTxTrace
```
java.lang.Throwable getBeginTxTrace()
```
    Retrieve trace information about where the current transaction, if any, was started. FINER level logging must be enabled, or this method always will return null.
    
    Returns:
    
    Throwable containing stack trace from last transaction start, or null.
  - registerSessionListener
```
void registerSessionListener(SessionListener listener,
                             SessionListener.Scope scope)
```
    Register a SessionListener to receive session life cycle event notifications. The listener will be deregistered according to the following rules at the earlier of:
    - the point at which it is collected by the garbage collector (once business logic no longer strongly references it); or
    - the end of the scope indicated by the scope parameter:
      
      ENCLOSING_EXTERNAL_SCOPE
      CURRENT_SCOPE
      NEXT_EXTERNAL_SCOPE
    Parameters:
    
    listener - Session listener to be registered.
    
    scope - SessionListener.Scope enum indicating the scope to which this listener should be registered. When the scope ends, the listener is deregistered as described above.
  - deregisterSessionListener
```
void deregisterSessionListener(SessionListener listener)
```
    Explicitly deregister a global session listener, which represents a dynamic temp-table resource which has been deleted explicitly.
    
    Parameters:
    
    listener - Listener to deregister.
  - getFastFindCache
```
FastFindCache getFastFindCache()
```
    Getter for the ffCache field.
    
    Returns:
    
    An instance of the fast find cache, assigned to this context.
  - getNursery
```
RecordNursery getNursery()
```
    Get the record nursery.
    
    Returns:
    
    Record nursery.
  - getSessionNoCreate
```
Session getSessionNoCreate()
```
    Retrieve the ORM Session object associated with this context, if any.
    If the current session is broken, return null.
    
    Returns:
    
    The session object associated with the current context, or null if none has been created.
  - getSession
```
Session getSession()
            throws PersistenceException
```
    Retrieve the ORM Session object associated with this context, creating it if necessary. The session can be closed by closeSession(boolean).
    
    Returns:
    
    The session object associated with the current context.
    
    Throws:
    
    PersistenceException - if an error occurs associating a detached record with the new session.
    
    java.lang.IllegalArgumentException - if database has not been registered with the persistence service.
  - getSession
```
Session getSession(java.lang.String tenantId,
                   java.lang.String ldbName)
            throws PersistenceException
```
    Retrieve the ORM Session object associated with this context, creating it if necessary. The session can be closed by closeSession(boolean).
    
    Parameters:
    
    tenantId - The new tenant's id.
    
    ldbName - The logical name of the database that the tenant will use in this session.
    
    Returns:
    
    The session object associated with the current context.
    
    Throws:
    
    PersistenceException - if an error occurs associating a detached record with the new session.
    
    java.lang.IllegalArgumentException - if database has not been registered with the persistence service.
  - getTenantId
```
java.lang.String getTenantId()
```
    The id of the tenant that was assigned to this context, if any.
    
    Returns:
    
    String The id of the tenant.
  - setTenantDatabase
```
void setTenantDatabase(Database db,
                       boolean skipRegistering)
```
    Set the database that will be used in this context. Also, if intended, this context can be de-registered as a tenant listener with the old database and registered with the new one.
    
    Parameters:
    
    db - The new database that will be used in this context.
    
    skipRegistering - true if the registering part should be skipped, false otherwise.
  - isTransactionOpen
```
boolean isTransactionOpen()
```
    Indicate whether a database-level transaction currently is open.
    
    Returns:
    
    true if open, else false.
  - getDialectData
```
java.lang.Object getDialectData()
```
    Get the context-local, dialect-specific data object, if any.
    
    Returns:
    
    Dialect specific data object, or null if no such data exists.
  - isAutoCommit
```
boolean isAutoCommit()
```
    Indicate whether auto-commit is needed; this is the case for temp-tables being modified outside of an explicit transaction.
    
    Returns:
    
    true if auto-commit is needed, else false.
  - closeSession
```
boolean closeSession(boolean error)
              throws PersistenceException
```
    Attempt to close the database session associated with this context, and indicate whether the attempt was successful. A close attempt will be unsuccessful if this method is called while already in the process of closing the session, or if an attempt is made to close a legacy temp-table database session while temporary tables are still in use.
    This implementation is tolerant of multiple closes on the same session. If the session already was closed or could not be found, the method simply returns false.
    
    Parameters:
    
    error - true to indicate the session is closing due to an error; false to indicate the session is closing in the course of normal processing.
    
    Returns:
    
    true is the session was closed successfully; false if it was not closed because either: (a) this method was invoked in the course of an existing attempt to close the session; or (b) the session is with the legacy temp-table database while temporary tables are still in use.
    
    Throws:
    
    PersistenceException - if an open session was found but the attempt to close it failed with a database error.
  - closeSessionImpl
```
private boolean closeSessionImpl(boolean error,
                                 boolean force)
                          throws PersistenceException
```
    Attempt to close the database session associated with this context, and indicate whether the attempt was successful. A close attempt will be unsuccessful if this method is called while already in the process of closing the session, or if an attempt is made to close a legacy temp-table database session while temporary tables are still in use.
    This implementation is tolerant of multiple closes on the same session. If the session already was closed or could not be found, the method simply returns false.
    
    Parameters:
    
    error - true to indicate the session is closing due to an error; false to indicate the session is closing in the course of normal processing.
    
    force - true to force the session to be closed and all database resources associated with it to be cleaned up.
    
    Returns:
    
    true is the session was closed successfully; false if it was not closed because either: (a) this method was invoked in the course of an existing attempt to close the session; or (b) the session is with the legacy temp-table database while temporary tables are still in use.
    
    Throws:
    
    PersistenceException - if an open session was found but the attempt to close it failed with a database error.
  - notifySessionEvent
```
private void notifySessionEvent(SessionListener.Event event)
```
    Notify all registered session listeners that the current ORM session is about to close or the current, implicit transaction is being committed. Listeners which were set to be deregistered upon an event are deregistered after they are notified. There is no guaranteed order in which listeners are notified.
    All registered listeners are given a chance to process this event, even if one or more raise a PersistenceException (there is no such guarantee for unchecked exceptions). Each exception caught is logged.
    
    Parameters:
    
    event - Session event type.
  - cleanup
```
void cleanup()
```
    Cleanup hook invoked at the end of the current client context. Close the currently open database session, if any.
  - isRereadNoLock
```
boolean isRereadNoLock()
```
    Checks if the rereadnolock 4GL command-line option is active for this client context.
    
    Returns:
    
    true if rereadnolock is specified for this client context
  - setUnsafe
```
void setUnsafe(boolean value)
```
    Decide whether this persistence context is unsafe or not.
    
    Parameters:
    
    value - If true the persistence will run in unsafe mode and in safe mode if false.
  - isUnsafe
```
boolean isUnsafe()
```
    Checks whether this persistence context is unsafe or not.
    
    Returns:
    
    If true the persistence will run in unsafe mode and in safe mode if false.

Class Persistence.Context

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

staticQueryCache

bufferManager

contextDatabase

ffCache

nursery

lockContext

sessionListeners

session

sessionUseCount

closingSession

openSessionCount

dialectData

rereadNoLock

traceTx

beginTxTrace

factory

tenantId

unsafe

Constructor Detail

Context

Method Detail

tenantChanged

getDatabase

getRecordLockContext

getPersistence

useSession

releaseSession

canCloseSession

getQuery

getQuery

commit

rollback

enableTransactionTrace

beginTransaction

postTransaction

getBeginTxTrace

registerSessionListener

deregisterSessionListener

getFastFindCache

getNursery

getSessionNoCreate

getSession

getSession

getTenantId

setTenantDatabase

isTransactionOpen

getDialectData

isAutoCommit

closeSession

closeSessionImpl

notifySessionEvent

cleanup

isRereadNoLock

setUnsafe

isUnsafe