com.goldencode.p2j.persist.orm

Class Session

java.lang.Object

com.goldencode.p2j.persist.orm.Session

All Implemented Interfaces:

CacheExpiryListener<RecordIdentifier<java.lang.String>,BaseRecord>, DmoState, java.lang.AutoCloseable

public class Session
extends java.lang.Object
implements DmoState, CacheExpiryListener<RecordIdentifier<java.lang.String>,BaseRecord>, java.lang.AutoCloseable

Session which manages a JDBC connection with a database, optionally maintains a cache of record objects, and provides ORM, CRUD, and transaction services.

The lifetime of a session object and the JDBC connection it uses are the same. Once the JDBC connection which backs a session instance is closed, the session can no longer be used. If a new connection is needed, a new session must be created.

Field Summary

Fields

Modifier and Type	Field and Description
private java.lang.Boolean	batch Lazy flag indicating whether the JDBC data store supports batch operations
private ExpiryCache<RecordIdentifier<java.lang.String>,BaseRecord>	cache Cache of database records associated with this session
private java.util.Map<java.lang.String,java.util.Map<java.lang.Integer,java.util.Set<RecordIdentifier<java.lang.String>>>>	cacheExtension A cache extension allowing the look-up per table/multiplex faster
private java.sql.Connection	conn Active JDBC connection, opened when session is instantiated, closed when it is closed
private Database	database Database with which this session is used
static java.lang.String	DEFAULT_PK The default name of the primary key.
private boolean	inTx Flag indicating whether a transaction currently is open
private Loader	loader Helper used to load records from the database
private static CentralLogger	log Logger
private Persister	persister Helper used to persist records to the database
static java.lang.String	PK The primary key name in use.
private SavepointManager	savepointManager Active savepoint manager, if any
private java.lang.String	tenantId The tenant that uses this session.
private int	txCount Count of transactions opened during this session's lifetime
private DmoVersioning	versioning Object which tracks the current versions of DMOs to enable stale checking

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

Modifier	Constructor and Description
	Session(Database database) Construct the session and check out a pooled JDBC connection to use for its services.
	Session(Database database, DatabaseConfig cfg) Construct the session and check out a pooled JDBC connection to use for its services.
private	Session(Database database, DatabaseConfig cfg, boolean useCache, DmoVersioning versioning, java.lang.String tenantId) Construct the session and check out a pooled JDBC connection to use for its services.
	Session(Database database, DatabaseConfig config, DmoVersioning versioning, java.lang.String tenantId) Construct the session and check out a pooled JDBC connection to use for its services.
	Session(Database database, javax.sql.DataSource ds) Construct the session and check out a JDBC connection from a specified DataSource to use for its services.

Method Summary

Modifier and Type	Method and Description
private void	addToCacheExtension(RecordIdentifier<java.lang.String> key, BaseRecord dmo) Make sure that the cache extension is consistent.
<T extends BaseRecord> void	associate(RecordIdentifier<java.lang.String> key, T dmo) Associate the given record with the session cache.
<T extends BaseRecord> void	associate(T dmo) Associate the given record with the session cache.
boolean	beginTransaction() Begin a new database transaction, if one does not already exist for this session.
boolean	beginTransaction(SavepointManager savepointManager) Begin a new database transaction, if one does not already exist for this session.
static void	bootstrap() Method called at server bootstrap that initializes values from the directory configuration.
<T extends BaseRecord> int	bulkSave(java.util.List<T> records) Persist a list of records, performing inserts using SQL batching, if supported.
void	cacheExpired(CacheExpiryEvent<RecordIdentifier<java.lang.String>,BaseRecord> event) This method is invoked when the session cache has expired one or more elements.
private void	checkClosed() Test whether the connection is alive (not closed).
private <T extends BaseRecord> void	checkStale(RecordIdentifier<java.lang.String> key, T dmo) If DMO versioning is enabled for this session, check whether the given record is stale.
private void	checkTx() A sanity check to ensure any DML being executed is performed within an active transaction or on an auto-commit connection.
void	clear() Clear the session DMO cache.
void	close() Closes the connection to database and invalidates the local field.
boolean	commit() Commit all work done since the beginning of the current transaction.
private ExpiryCache<RecordIdentifier<java.lang.String>,BaseRecord>	createCache() Create a session expiry cache which disallows DMOs which are referenced by buffers or which are being tracked for UNDO purposes from being expired.
static Query	createQuery(java.util.function.Consumer<Query> cache, java.lang.String fql) Creates and returns a Query based on a FQL statement.
static Query	createQuery(java.lang.String fql) Creates and returns a Query based on a FQL statement.
static SQLQuery	createSQLQuery(java.lang.String sql) Creates and returns a SQLQuery based on a SQL statement (not mandatory a SQL query).
static SQLQuery	createSQLQuery(java.lang.String sql, java.util.List<FQLPreprocessor.SessionAttr> sessionAttrs, int[] parPerm) Creates and returns a SQLQuery based on a SQL statement (not mandatory a SQL query).
boolean	delete(java.lang.String entity, java.lang.Long id) Deletes a record from the database and from internal cache.
<T extends BaseRecord> boolean	delete(T dmo) Delete the DMO's record(s) from the database and remove it from the cache.
private void	deregisterVersioned() Deregister any cached records from DMO version tracking.
void	disableCache() Disables cache for this session.
private void	evict(RecordIdentifier<java.lang.String> key, BaseRecord dmo) Remove a record from the session cache.
<T extends BaseRecord> void	evict(T dmo) Remove a record from the session cache.
(package private) boolean	evictIfExist(java.lang.String dmoImplName, long pk) Evicts a record of a table specified by its DMO class implementation.
<T extends BaseRecord> T	get(java.lang.Class<T> dmoImplClass, java.lang.Long id) Gets a specified record of a table.
<T extends BaseRecord> T	get(java.lang.Class<T> dmoImplClass, java.lang.Long id, java.util.BitSet partialFields) Gets a specified record of a table.
<T extends BaseRecord> T	get(RecordIdentifier<java.lang.String> key) Gets a specified record of a table.
<T extends BaseRecord> T	get(java.lang.String entity, java.lang.Long id) Get a record.
<T extends BaseRecord> T	getCached(java.lang.Class<T> dmoClass, java.lang.Long id) Get the cached DMO of the given type with the given primary key.
private <T extends BaseRecord> T	getCached(RecordIdentifier<java.lang.String> key) Get the cached DMO associated with the given primary key, if any.
java.sql.Connection	getConnection() Convenience method to access this session database connection.
Database	getDatabase() Obtain the FWD database this session serves.
private <T extends BaseRecord> T	getImpl(java.lang.Class<T> dmoImplClass, java.lang.Long id, RecordIdentifier<java.lang.String> key, java.util.BitSet partialFields) Get a record.
static RecordMeta	getMetadata(java.lang.Class<? extends BaseRecord> dmoClass) Get the record metadata for the given DMO implementation class.
(package private) Persister	getPersister() Get the persister for this session.
SavepointManager	getSavepointManager() Get the savepoint manager registered with this session, if any.
java.lang.String	getTenantId() Getter for the tenantId field.
java.lang.Long	getTxNestingId() 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.
boolean	inTransaction() Indicate whether a database transaction currently is in process.
void	invalidateRecords(java.lang.String dmoImplName, java.lang.Integer multiplex) Invalidates all records from cache belonging to a specific table.
boolean	isOpen() Test if the connection to database is active / open.
void	lazilySetSavepoints() Set the savepoint for the current block.
<T extends BaseRecord> T	merge(T dmo)
<T extends BaseRecord> T	refresh(T dmo) Refresh the given DMO with data from the database, bypassing the cache.
void	releaseSavepoint(java.sql.Savepoint savepoint) Release the given savepoint, thereby disabling the ability to roll back to the point at which it was created.
private void	removeFromCacheExtension(RecordIdentifier<java.lang.String> key, BaseRecord dmo) Make sure that the cache extension is consistent.
boolean	rollback() Roll back all work done since the beginning of the current transaction.
boolean	rollbackSavepoint(java.sql.Savepoint savepoint) Roll back all database changes since the given savepoint was set.
<T extends BaseRecord> void	save(T dmo, boolean updateDmoState) Saves a dmo to database.
java.sql.Savepoint	setSavepoint() Set a savepoint to which database changes can be rolled back, if we are currently within an active transaction.
(package private) boolean	supportsBatch() Indicate whether the JDBC driver used by this session supports batch statement operations.
void	trackUndoable(BaseRecord dmo) Begin tracking an undoable record as needing savepoint processing.
void	updateCachedRecords(java.lang.String dmoImplName, java.lang.Integer multiplex, java.util.function.Consumer<BaseRecord> update) Apply the given update to all the cached records.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DEFAULT_PK

public static final java.lang.String DEFAULT_PK

The default name of the primary key. The value is the same as the default value of SchemaConfig.primaryKeyName, used at conversion and import time. The default "recid" is a reserved keyword in 4GL, so it cannot conflict with an existing field/column name.

See Also:

Constant Field Values

log

private static final CentralLogger log

Logger

versioning

private final DmoVersioning versioning

Object which tracks the current versions of DMOs to enable stale checking

database

private final Database database

Database with which this session is used

loader

private final Loader loader

Helper used to load records from the database

persister

private final Persister persister

Helper used to persist records to the database

tenantId

private final java.lang.String tenantId

The tenant that uses this session. This will be null when multi-tenancy is not enabled.

PK

public static java.lang.String PK

The primary key name in use. It can be configured in static config file (p2j.cfg.xml) for (conversion and) import process and in directory for normal execution.

cache

private ExpiryCache<RecordIdentifier<java.lang.String>,BaseRecord> cache

Cache of database records associated with this session

cacheExtension

private java.util.Map<java.lang.String,java.util.Map<java.lang.Integer,java.util.Set<RecordIdentifier<java.lang.String>>>> cacheExtension

A cache extension allowing the look-up per table/multiplex faster

conn

private java.sql.Connection conn

Active JDBC connection, opened when session is instantiated, closed when it is closed

inTx

private boolean inTx

Flag indicating whether a transaction currently is open

savepointManager

private SavepointManager savepointManager

Active savepoint manager, if any

batch

private java.lang.Boolean batch

Lazy flag indicating whether the JDBC data store supports batch operations

txCount

private int txCount

Count of transactions opened during this session's lifetime

Constructor Detail

Session

public Session(Database database)
        throws PersistenceException

Construct the session and check out a pooled JDBC connection to use for its services.

This variant will construct a session which does not have a built-in record cache.

Parameters:

database - Database with which to open a session.

Throws:

PersistenceException - if there is an error getting a JDBC connection from the data source.

Session

public Session(Database database,
               DatabaseConfig cfg)
        throws PersistenceException

Construct the session and check out a pooled JDBC connection to use for its services.

This variant will construct a session which does not have a built-in record cache.

Parameters:

database - Database with which to open a session.

cfg - The configuration for the given database.

Throws:

PersistenceException - if there is an error getting a JDBC connection from the data source.

Session

public Session(Database database,
               DatabaseConfig config,
               DmoVersioning versioning,
               java.lang.String tenantId)
        throws PersistenceException

Construct the session and check out a pooled JDBC connection to use for its services.

This variant will construct a session with a built-in record cache.

Parameters:

database - Database with which to open a session.

config - The configuration for the given database.

versioning - Optional object which tracks record versions. May be null to disable versioning.

tenantId - The id of the tenant.

Throws:

PersistenceException - if there is an error getting a JDBC connection from the data source.

Session

public Session(Database database,
               javax.sql.DataSource ds)
        throws PersistenceException

Construct the session and check out a JDBC connection from a specified DataSource to use for its services.

Parameters:

database - Database with which to open a session.

ds - The DataSource that will provide the connection to database.

Throws:

PersistenceException - if there is an error getting a JDBC connection from the data source.

Session

private Session(Database database,
                DatabaseConfig cfg,
                boolean useCache,
                DmoVersioning versioning,
                java.lang.String tenantId)
         throws PersistenceException

Construct the session and check out a pooled JDBC connection to use for its services.

Parameters:

database - Database with which to open a session.

cfg - The configuration for the given database.

useCache - true to enable record caching; false to disable it.

versioning - Optional object which tracks record versions. May be null to disable versioning.

tenantId - The id of the tenant.

Throws:

PersistenceException - if there is an error getting a JDBC connection from the data source.

Method Detail

bootstrap

public static void bootstrap()

Method called at server bootstrap that initializes values from the directory configuration. Until this method is called, default values are used.

createQuery

public static Query createQuery(java.lang.String fql)

Creates and returns a Query based on a FQL statement. The returned object is not bounded to any session; the Session upon which it will be executed will be provided at the time of execution.

Parameters:

fql - The FQL statement that will be executed by the returned Query.

Returns:

a SQLQuery that can be used to execute the specified SQL statement.

createQuery

public static Query createQuery(java.util.function.Consumer<Query> cache,
                                java.lang.String fql)

Creates and returns a Query based on a FQL statement. The returned object is not bounded to any session; the Session upon which it will be executed will be provided at the time of execution.

Parameters:

cache - caching lambda

fql - The FQL statement that will be executed by the returned Query.

Returns:

a SQLQuery that can be used to execute the specified SQL statement.

createSQLQuery

public static SQLQuery createSQLQuery(java.lang.String sql,
                                      java.util.List<FQLPreprocessor.SessionAttr> sessionAttrs,
                                      int[] parPerm)

Creates and returns a SQLQuery based on a SQL statement (not mandatory a SQL query). The returned object is not bounded to any connection; the Connection upon which it will be executed will be provided at the time of execution.

Parameters:

sql - The SQL statement that will be executed by the returned SQLQuery.

sessionAttrs - Mutable session attributes' values used in the query

parPerm - The permutation function, if any available.

Returns:

a SQLQuery that can be used to execute the specified SQL statement.

createSQLQuery

public static SQLQuery createSQLQuery(java.lang.String sql)

Creates and returns a SQLQuery based on a SQL statement (not mandatory a SQL query). The returned object is not bounded to any connection; the Connection upon which it will be executed will be provided at the time of execution.

Parameters:

sql - The SQL statement that will be executed by the returned SQLQuery.

Returns:

a SQLQuery that can be used to execute the specified SQL statement.

getMetadata

public static RecordMeta getMetadata(java.lang.Class<? extends BaseRecord> dmoClass)

Get the record metadata for the given DMO implementation class.

Parameters:

dmoClass - DMO implementation class.

Returns:

Record metadata information.

Throws:

java.lang.IllegalArgumentException - if the DMO class does not define a record metadata field or if there is an error accessing it.

getCached

public <T extends BaseRecord> T getCached(java.lang.Class<T> dmoClass,
                                          java.lang.Long id)
                                   throws PersistenceException

Get the cached DMO of the given type with the given primary key.

If a record is found in the cache, but it is marked stale, it is removed.

Parameters:

dmoClass - DMO implementation type.

id - Primary key.

Returns:

The cached DMO instance, or null if it was not cached under the given primary key or if it was marked stale.

Throws:

PersistenceException - if a DMO instance is found in the cache which is not of the given DMO type.

get

public <T extends BaseRecord> T get(java.lang.Class<T> dmoImplClass,
                                    java.lang.Long id)
                             throws PersistenceException

Gets a specified record of a table. To lookup the record local cache is analyzed first. If the record is not found in cache, the backing database is queried. If the specified record is not found in database, null is returned. If the record was fetched from the database at this moment, it is kept in cache for further access.

Type Parameters:

T - The type of the record.

Parameters:

dmoImplClass - The class of the entity (class that implements the table's DMO interface).

id - The id/rowid of the record to be returned.

Returns:

The requested record, if found in cache or database and null otherwise.

Throws:

PersistenceException - In case some error occurs in the process.

get

public <T extends BaseRecord> T get(java.lang.Class<T> dmoImplClass,
                                    java.lang.Long id,
                                    java.util.BitSet partialFields)
                             throws PersistenceException

Gets a specified record of a table. To lookup the record local cache is analyzed first. If the record is not found in cache, the backing database is queried. If the specified record is not found in database, null is returned. If the record was fetched from the database at this moment, it is kept in cache for further access.

Type Parameters:

T - The type of the record.

Parameters:

dmoImplClass - The class of the entity (class that implements the table's DMO interface).

id - The id/rowid of the record to be returned.

partialFields - For an incomplete record, read only these fields.

Returns:

The requested record, if found in cache or database and null otherwise.

Throws:

PersistenceException - In case some error occurs in the process.

get

public <T extends BaseRecord> T get(RecordIdentifier<java.lang.String> key)
                             throws PersistenceException

Gets a specified record of a table. To lookup the record local cache is analyzed first. If the record is not found in cache, the backing database is queried. If the specified record is not found in database, null is returned. If the record was fetched from the database at this moment, it is kept in cache for further access.

Type Parameters:

T - The type of the record.

Parameters:

key - The record identifier key with which the DMO is associated in the cache. The table portion of the key must be the fully qualified class name of the DMO.

Returns:

The requested record, if found in cache or database and null otherwise.

Throws:

PersistenceException - In case some error occurs in the process.

get

public <T extends BaseRecord> T get(java.lang.String entity,
                                    java.lang.Long id)
                             throws PersistenceException

Get a record. If found in cache, it is returned immediately, otherwise the database is queried for the specified record. If found, it is saved to cache and returned. Otherwise null is returned.

Type Parameters:

T - The compile type of the record to be returned.

Parameters:

entity - The string representation of the Class of the entity to be returned.

id - The recid of the entity to be returned.

Returns:

The record with requested recid/id if found in cache/database and null otherwise.

Throws:

PersistenceException - if there is an error getting a JDBC connection from the data source.

getImpl

private <T extends BaseRecord> T getImpl(java.lang.Class<T> dmoImplClass,
                                         java.lang.Long id,
                                         RecordIdentifier<java.lang.String> key,
                                         java.util.BitSet partialFields)
                                  throws PersistenceException

Get a record. If found in cache, it is returned immediately, otherwise the database is queried for the specified record. If found, it is saved to cache and returned. Otherwise null is returned.

Type Parameters:

T - The compile type of the record to be returned.

Parameters:

dmoImplClass - The class of the entity (class that implements the table's DMO interface). Optional if a valid key is provided.

id - The recid of the entity to be returned. Optional if a valid key is provided.

key - The cache key of the entity. If null the returned value is null; provided.

partialFields - For an incomplete record, read only these fields.

Returns:

The record with requested recid/id if found in cache/database and null otherwise.

Throws:

PersistenceException - if there is an error getting a JDBC connection from the data source.

save

public <T extends BaseRecord> void save(T dmo,
                                        boolean updateDmoState)
                                 throws PersistenceException

Saves a dmo to database. If so requested, its internal state information is updated.

Type Parameters:

T - The compile type of the record.

Parameters:

dmo - The record to be saved.

updateDmoState - If true its internal state information is updated. This is the standard call. When the method is called for validation, use false as the database operation will be rolled back anyway, so the state must not be altered.

Throws:

PersistenceException - When an exception is encountered. Must be analyzed as the cause might be expected (ex: when validating a record).

StaleRecordException - if the record being saved is stale.

bulkSave

public <T extends BaseRecord> int bulkSave(java.util.List<T> records)
                                    throws PersistenceException

Persist a list of records, performing inserts using SQL batching, if supported. If not supported, perform the inserts one-by-one.

This method is not intended for legacy runtime support. It is meant for bulk inserts and as such, it:

• bypasses the session cache (if any), though it should be used with a cache-less session);
• does not use savepoints;
• does not update DMO state.

Parameters:

records - List of records to be saved. Each record must have a unique, positive primary key assigned.

Returns:

The count of records successfully inserted, which should match the size of the list provided if there were no errors. If SQL batching is not supported, returns -1, without saving records.

Throws:

PersistenceException - if there was an error performing the batch insert. This will wrapper the SQLException thrown by the JDBC layer.

delete

public <T extends BaseRecord> boolean delete(T dmo)
                                      throws PersistenceException

Delete the DMO's record(s) from the database and remove it from the cache.

Type Parameters:

T - DMO type

Parameters:

dmo - DMO to be deleted.

Returns:

true on success

Throws:

PersistenceException - if there is a database error, or if a different DMO instance with the same ID as the given DMO is found in cache.

delete

public boolean delete(java.lang.String entity,
                      java.lang.Long id)
               throws PersistenceException

Deletes a record from the database and from internal cache.

NOTE: Only used by dirty share manager; currently not integrated with the savepoint manager, due to inability to discern between undoable and NO-UNDO records

Parameters:

entity - The string representation of the Class of the record to be deleted. Actually, this represents the table of the record to be deleted.

id - The recid of the record to be deleted.

Returns:

true if the record wa found and deleted and false if the record was not detected in database.

Throws:

PersistenceException - if there is an error accessing the database.

java.lang.IllegalArgumentException - if id is null.

updateCachedRecords

public void updateCachedRecords(java.lang.String dmoImplName,
                                java.lang.Integer multiplex,
                                java.util.function.Consumer<BaseRecord> update)

Apply the given update to all the cached records.

WARNING: this must be called only for temp-tables, and it must be used with a direct SQL on the same temp-table records, so that the cached and the sql table records have the same state.

Parameters:

work - The code to apply on the cached records.

invalidateRecords

public void invalidateRecords(java.lang.String dmoImplName,
                              java.lang.Integer multiplex)

Invalidates all records from cache belonging to a specific table. If provided a multiplex, only those records are affected.

Parameters:

dmoImplName - Name of the DMO implementation class whose associated records are going to be removed from the cache.

multiplex - Optional multiplex used to filter which records are deleted.

evictIfExist

boolean evictIfExist(java.lang.String dmoImplName,
                     long pk)

Evicts a record of a table specified by its DMO class implementation. The record is specified by its primary key.

Parameters:

dmoImplName - Name of the DMO implementation class whose associated records are going to be removed from the cache.

pk - The primary key of the record to be evicted.

Returns:

true if the record was evicted from cache and false is the specified record was not found in cache.

refresh

public <T extends BaseRecord> T refresh(T dmo)
                                 throws PersistenceException

Refresh the given DMO with data from the database, bypassing the cache. The DMO's primary key is assumed to represent a valid identifier. If no record is found with this primary key, the existing DMO (if any) with that identifier is removed from the cache, and null is returned.

Parameters:

dmo - DMO whose data is to be refreshed from the database.

Returns:

The instance passed into this method as dmo, containing refreshed data, or null if a matching record was not found.

Throws:

PersistenceException - if a database error occurs.

merge

public <T extends BaseRecord> T merge(T dmo)
                               throws PersistenceException

Type Parameters:

T - dmo TYPE

Parameters:

dmo - DMO

Returns:

saved record

Throws:

PersistenceException - on error

associate

public <T extends BaseRecord> void associate(T dmo)
                                      throws PersistenceException,
                                             StaleRecordException

Associate the given record with the session cache. It is an error if another record instance with the same primary key already is associated with the cache.

Parameters:

dmo - The record to associate with the cache.

Throws:

PersistenceException - if another record instance already is associated with the session under the same key.

StaleRecordException - if the record being associated with the session is stale.

associate

public <T extends BaseRecord> void associate(RecordIdentifier<java.lang.String> key,
                                             T dmo)
                                      throws PersistenceException,
                                             StaleRecordException

Associate the given record with the session cache. It is an error if another record instance with the same primary key already is associated with the cache.

Parameters:

key - The record identifier key with which to associate the record in the cache. The table portion of the key must be the fully qualified class name of the DMO.

dmo - The record to associate with the cache.

Throws:

PersistenceException - if another record instance already is associated with the session under the same key.

StaleRecordException - if the record being associated with the session is stale.

evict

public <T extends BaseRecord> void evict(T dmo)

Remove a record from the session cache.

Type Parameters:

T - The compile type of the record.

Parameters:

dmo - The record to be evicted.

getConnection

public java.sql.Connection getConnection()
                                  throws PersistenceException

Convenience method to access this session database connection.

Use with caution and do not directly commit, rollback, set or release savepoints, etc.! Definitely do not close this connection directly! This will render the enclosing session inoperable. Use the Session API for these services instead.

Returns:

Pooled JDBC connection. There is no guarantee that the connection is in a valid state.

Throws:

PersistenceException - if the JDBC connection has been closed or there was an error checking its status.

inTransaction

public boolean inTransaction()

Indicate whether a database transaction currently is in process.

Returns:

true if a transaction exists, else false.

beginTransaction

public boolean beginTransaction()
                         throws PersistenceException

Begin a new database transaction, if one does not already exist for this session. Do not install a savepoint manager.

Returns:

true if a new transaction was begun; false if a transaction already exists for this session.

Throws:

PersistenceException - if a database error occurs.

beginTransaction

public boolean beginTransaction(SavepointManager savepointManager)
                         throws PersistenceException

Begin a new database transaction, if one does not already exist for this session.

Parameters:

savepointManager - Optional savepoint manager to install in the session for the duration of the transaction. This should only be installed when the transaction corresponds with a legacy, application-level transaction. It will match database savepoints with application block sub-transactions, and keep in-memory DMO state in sync with the database through commit and rollback processing. Should be null when beginning a database transaction which does not correspond with a legacy application transactions

Returns:

true if a new transaction was begun; false if a transaction already exists for this session.

Throws:

PersistenceException - if a database error occurs.

commit

public boolean commit()
               throws PersistenceException

Commit all work done since the beginning of the current transaction.

The session's current savepoint manager, if any, is discarded after the transaction ends.

Returns:

true if the transaction was committed; false if it there is no active transaction to commit.

Throws:

PersistenceException - if there was a database error committing the transaction.

rollback

public boolean rollback()
                 throws PersistenceException

Roll back all work done since the beginning of the current transaction.

The session's current savepoint manager, if any, is discarded after the transaction ends.

Returns:

true if the transaction was rolled back; false if it there is no active transaction to roll back.

Throws:

PersistenceException - if there was a database error rolling back the transaction.

lazilySetSavepoints

public void lazilySetSavepoints()
                         throws PersistenceException

Set the savepoint for the current block.

Throws:

PersistenceException

setSavepoint

public java.sql.Savepoint setSavepoint()
                                throws PersistenceException

Set a savepoint to which database changes can be rolled back, if we are currently within an active transaction.

Returns:

The savepoint object, if successfully set. null is returned if we are not within an active transaction.

Throws:

PersistenceException - if a database error occurs.

releaseSavepoint

public void releaseSavepoint(java.sql.Savepoint savepoint)
                      throws PersistenceException

Release the given savepoint, thereby disabling the ability to roll back to the point at which it was created. This represents a commit of the unit of work which began when the savepoint was set.

Parameters:

savepoint - The savepoint to be released.

Throws:

PersistenceException - if a database error occurs.

rollbackSavepoint

public boolean rollbackSavepoint(java.sql.Savepoint savepoint)
                          throws PersistenceException

Roll back all database changes since the given savepoint was set.

Parameters:

savepoint - Savepoint to which changes should be rolled back.

Returns:

false if we are not in a transaction when this method is invoked; true if we are in a transaction and the rollback was successful.

Throws:

PersistenceException - if a database error occurs.

isOpen

public boolean isOpen()

Test if the connection to database is active / open.

Returns:

true if the connection to database is usable.

clear

public void clear()
           throws PersistenceException

Clear the session DMO cache.

Throws:

PersistenceException - on error

disableCache

public void disableCache()
                  throws PersistenceException

Disables cache for this session. This affects performance and should not be done unless there are good reasons like when we are sure the records will never be used twice. This is the case of the import process when a lot of records are just saved to database and never retrieved.

Throws:

PersistenceException - on error

getTxNestingId

public java.lang.Long getTxNestingId()

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, or -1 if not currently in an active transaction.

trackUndoable

public void trackUndoable(BaseRecord dmo)
                   throws PersistenceException

Begin tracking an undoable record as needing savepoint processing. This method should only be invoked within the context of an active, application-level transaction. Otherwise, it is a no-op.

Parameters:

dmo - Record to be tracked.

Throws:

PersistenceException - if there is an error lazily setting associated savepoints in the savepoint manager.

See Also:

SavepointManager.trackUndoable(BaseRecord)

close

public void close()
           throws PersistenceException

Closes the connection to database and invalidates the local field. The cache is also dropped as the cached values are no more valid without the active connection.

Specified by:

close in interface java.lang.AutoCloseable

Throws:

PersistenceException - in the event of an error.

getDatabase

public Database getDatabase()

Obtain the FWD database this session serves.

Returns:

the Database this session is attached to.

cacheExpired

public void cacheExpired(CacheExpiryEvent<RecordIdentifier<java.lang.String>,BaseRecord> event)

This method is invoked when the session cache has expired one or more elements. It unsets the CACHED state from each expired DMO and deregisters from DmoVersioning.

Important: Delivery of this event is not asynchronous, so any delay in this method's return will impact the performance of the cache! This implementation should be maintained to return as quickly as possible.

Specified by:

cacheExpired in interface CacheExpiryListener<RecordIdentifier<java.lang.String>,BaseRecord>

Parameters:

event - An object containing information about the event.

supportsBatch

boolean supportsBatch()
               throws PersistenceException

Indicate whether the JDBC driver used by this session supports batch statement operations.

Returns:

true if batch operations are supported, else false.

Throws:

PersistenceException - if database metadata needs to be queried and there is an error doing so.

getCached

private <T extends BaseRecord> T getCached(RecordIdentifier<java.lang.String> key)
                                    throws PersistenceException

Get the cached DMO associated with the given primary key, if any.

If a record is found in the cache, but it is stale, it is removed.

Parameters:

key - The record identifier key with which the DMO is associated in the cache. The table portion of the key must be the fully qualified class name of the DMO.

Returns:

The cached DMO instance, or null if there is no cache, if the record was not cached under the given primary key, or if the record was determined to be stale.

Throws:

PersistenceException - if a DMO instance is found in the cache which is not of the given DMO type.

getPersister

Persister getPersister()

Get the persister for this session.

Returns:

Object used to insert and update records.

getSavepointManager

public SavepointManager getSavepointManager()

Get the savepoint manager registered with this session, if any.

Returns:

Savepoint manager, or null if none is registered.

getTenantId

public java.lang.String getTenantId()

Getter for the tenantId field.

Returns:

The id of the tenant that uses this session.

createCache

private ExpiryCache<RecordIdentifier<java.lang.String>,BaseRecord> createCache()

Create a session expiry cache which disallows DMOs which are referenced by buffers or which are being tracked for UNDO purposes from being expired. The cache uses a lenient capacity policy, so it may grow beyond its set size limit, but attempts will be made to shrink its size back down to its limit.

Returns:

A session cache as described above.

evict

private void evict(RecordIdentifier<java.lang.String> key,
                   BaseRecord dmo)

Remove a record from the session cache.

Parameters:

key - The record identifier key with which the DMO is associated in the cache. The table portion of the key must be the fully qualified class name of the DMO.

dmo - The record to be evicted.

addToCacheExtension

private void addToCacheExtension(RecordIdentifier<java.lang.String> key,
                                 BaseRecord dmo)

Make sure that the cache extension is consistent. Every add in the primary cache should update the cache extension properly. If this is not consistent, the pruning won't cover all targeted cached records.

Parameters:

key - The key which was added to the primary cache.

dmo - The dmo which was added. This is used to retrieve the multiplex.

removeFromCacheExtension

private void removeFromCacheExtension(RecordIdentifier<java.lang.String> key,
                                      BaseRecord dmo)

Make sure that the cache extension is consistent. Every removal from the primary cache (due to eviction or expiration) should update the cache extension properly. If this is not consistent, the extension will leak.

Parameters:

key - The key which is removed from the primary cache.

dmo - The dmo which was removed. This is used to retrieve the multiplex.

deregisterVersioned

private void deregisterVersioned()

Deregister any cached records from DMO version tracking.

checkClosed

private void checkClosed()
                  throws PersistenceException

Test whether the connection is alive (not closed). If the connection is usable the method returns without any side-effects. If the session is not usable, PersistenceException is thrown.

Throws:

PersistenceException - when the connection is not usable because it was closed.

checkTx

private void checkTx()
              throws PersistenceException

A sanity check to ensure any DML being executed is performed within an active transaction or on an auto-commit connection. This method should only be invoked from within methods which perform DML and after it is confirmed that an open connection exists.

TODO: the conditions for which this method checks represent programming errors and as such, we may want to remove this method once the persistence subsystem is well tested. On the other hand, the overhead is quite low: in the common case, there is just the overhead of the method call itself and of an instance field check.

Throws:

PersistenceException - if we are not in an active transaction and the connection is not set to auto-commit.

checkStale

private <T extends BaseRecord> void checkStale(RecordIdentifier<java.lang.String> key,
                                               T dmo)
                                        throws StaleRecordException

If DMO versioning is enabled for this session, check whether the given record is stale. If versioning is disabled, or the record is not stale, return normally.

Parameters:

dmo - Record to be checked.

Throws:

StaleRecordException - if the record is stale.