de.ipcon.db.core

Interface PersistenceHandlerI

All Known Implementing Classes:

CastorPersistenceHandler

public interface PersistenceHandlerI

Defines the core operations for managing persistence within the application.

A `PersistenceHandlerI` acts as an intermediary between the application and the underlying persistence mechanism (e.g., a database). It provides methods to control transactions, create, retrieve, update, and delete objects, and manage the persistence context.

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	$0
static int	DB_LOCKED
static int	EXCLUSIVE
static int	READ_ONLY
static int	SHARED

Method Summary

Modifier and Type	Method and Description
BO	assureClassStability(BO bo, int mode, java.util.Set<java.lang.Long> keepLocked)
void	begin() Convenience method to initiate a transaction using the default lock timeout.
void	begin(int lockTimeout) Initiates a new transaction within the current persistence context.
void	cancelCreate(BO bo)
void	cancelPurge(BO bo) Cancels a previously scheduled purge operation for a BO.
void	commit() Actually creates new BOs and persists changes to the database storage; but is also called when data was just queried...?
void	create(BO bo)
void	dbLock(BO bo)
boolean	exists(java.lang.Class<? extends BOI> classtip, java.lang.Long id)
void	finish()
java.lang.RuntimeException	getFinishedBy()
BOLoaderI	getInjectBOLoader()
java.sql.Connection	getJdbcConnection()
SchemaI	getSchema()
boolean	isActive() Returns true if begin() was already called, false otherwise or if already finish()ed.
boolean	isAutoFinish()
boolean	isFinished() Returns true, if finish() was already called.
boolean	isForSaving() Returns true if the TransactionContext will remember all objects that were loaded with a readonly lock.
boolean	isLoadedReadOnly(java.lang.Long id) Returns true if the BO with the passed id is currently loaded in read-only mode.
boolean	isPersistent(BO bo)
de.ipcon.db.core.QueryResultsI	iterateNativeQuery(java.lang.String s)
de.ipcon.db.core.QueryResultsI	iterateNativeQuery(java.lang.String s, java.lang.Object[] parms)
de.ipcon.db.core.QueryResultsI	iterateNativeQuery(java.lang.String s, java.lang.Object[] parms, short mode)
de.ipcon.db.core.QueryResultsI	iterateNativeQuery(java.lang.String s, java.lang.Object[] parms, short mode, java.lang.String[] prefetchPaths)
de.ipcon.db.core.QueryResultsI	iterateQuery(java.lang.String s)
de.ipcon.db.core.QueryResultsI	iterateQuery(java.lang.String s, java.lang.Object[] parms)
de.ipcon.db.core.QueryResultsI	iterateQuery(java.lang.String s, java.lang.Object[] parms, short mode)
de.ipcon.db.core.QueryResultsI	iterateRelationBOs(java.lang.Class<? extends BOI> classtip, java.lang.Long id, java.lang.String attName)
de.ipcon.db.core.QueryResultsI	iterateRelationBOs(java.lang.Class<? extends BOI> classtip, java.lang.Long id, java.lang.String attName, short mode)
java.util.List	listQuery(java.lang.String s)
java.util.List	listQuery(java.lang.String s, java.lang.Object[] parms)
java.util.List	listQuery(java.lang.String s, java.lang.Object[] parms, short mode)
java.util.List	listRelationBOs(java.lang.Class<? extends BOI> classtip, java.lang.Long id, java.lang.String attName)
java.util.List	listRelationBOs(java.lang.Class<? extends BOI> classtip, java.lang.Long id, java.lang.String attName, short mode)
BO	load(java.lang.Class<? extends BOI> classtip, java.lang.Long id, int mode, java.util.Set<java.lang.Long> keepLocked, BO into, boolean syncModeCheck)
BO	loadReadOnly(java.lang.Class<? extends BOI> classtip, java.lang.Long id)
void	purge(BO bo) Marks a BO for purging from persistent storage upon transaction commit.
void	rollback()
void	setAutoFinish(boolean b)
void	setIgnoreMultipleBegin() Configures the handler to permit multiple calls to begin() without error.
void	setInjectBOLoader(BOLoaderI bol)

Field Detail

$0

static final java.lang.String $0

See Also:

Constant Field Values

READ_ONLY

static final int READ_ONLY

See Also:

Constant Field Values

SHARED

static final int SHARED

See Also:

Constant Field Values

EXCLUSIVE

static final int EXCLUSIVE

See Also:

Constant Field Values

DB_LOCKED

static final int DB_LOCKED

See Also:

Constant Field Values

Method Detail

begin

void begin(int lockTimeout)

Initiates a new transaction within the current persistence context.

Transaction Reuse:
If a transaction is already active, behavior depends on the setIgnoreMultipleBegin() setting:

• If enabled, the existing transaction is quietly reused (idempotent behavior).
• If disabled (default), the concrete implementation determines behavior (typically throwing an exception for nested transactions).

Lifecycle & Error Handling:

• Throws IllegalStateException if the handler is already marked as "finished".
• Handles underlying database locking exceptions, translating them to LockNotGrantedException.

Parameters:

lockTimeout - The time (in seconds) to wait for a database lock if a resource is contended.

• Positive (> 0): Wait up to the specified seconds.
• Zero or Negative (<= 0): Delegate to the underlying JDO configuration (typically defaults to 30 seconds wait).

Defaults to -1.

Throws:

java.lang.IllegalStateException - If the handler has already been finished/closed.

LockNotGrantedException - If a lock cannot be acquired within the timeout period.

PersistenceException - If a general error occurs during transaction initialization.

begin

void begin()

Convenience method to initiate a transaction using the default lock timeout.

Equivalent to calling begin(-1). See begin(int) for full details on transaction reuse and error handling.

Throws:

LockNotGrantedException - If a lock cannot be acquired using the default system timeout.

dbLock

void dbLock(BO bo)

create

void create(BO bo)

cancelCreate

void cancelCreate(BO bo)

purge

void purge(BO bo)

Marks a BO for purging from persistent storage upon transaction commit.

This method schedules the specified BO for permanent deletion from the database.

Parameters:

bo - The BO to be purged.

Throws:

java.lang.IllegalArgumentException - if any of the following conditions occur:

• The BO is `null`.
• The BO's Id is `null`.
• The BO was previously already scheduled for purging.

cancelPurge

void cancelPurge(BO bo)

Cancels a previously scheduled purge operation for a BO.

This method removes the specified BO from the internal collection of objects marked for deletion upon transaction commit. It is essential to ensure that the provided BO was indeed scheduled for purging before calling this method.

Parameters:

bo - The BO whose purge operation should be cancelled.

Throws:

java.lang.IllegalArgumentException - if any of the following conditions occur:

• The BO is `null`.
• The BO's Id is `null`.
• The BO was not previously scheduled for purging.

exists

boolean exists(java.lang.Class<? extends BOI> classtip,
               java.lang.Long id)

isLoadedReadOnly

boolean isLoadedReadOnly(java.lang.Long id)

Returns true if the BO with the passed id is currently loaded in read-only mode.

loadReadOnly

BO loadReadOnly(java.lang.Class<? extends BOI> classtip,
                java.lang.Long id)

load

BO load(java.lang.Class<? extends BOI> classtip,
        java.lang.Long id,
        int mode,
        java.util.Set<java.lang.Long> keepLocked,
        BO into,
        boolean syncModeCheck)

isPersistent

boolean isPersistent(BO bo)

isActive

boolean isActive()

Returns true if begin() was already called, false otherwise or if already finish()ed.

isForSaving

boolean isForSaving()

Returns true if the TransactionContext will remember all objects that were loaded with a readonly lock. Needed when saving to keep the tx graph stable, so BOs that are included (and thereby have their lock widened in the persistence framework) will always return the same object instance in their n-1 relation.

rollback

void rollback()

commit

void commit()

Actually creates new BOs and persists changes to the database storage; but is also called when data was just queried...?

finish

void finish()

isFinished

boolean isFinished()

Returns true, if finish() was already called.

getFinishedBy

java.lang.RuntimeException getFinishedBy()

setAutoFinish

void setAutoFinish(boolean b)

isAutoFinish

boolean isAutoFinish()

setIgnoreMultipleBegin

void setIgnoreMultipleBegin()

Configures the handler to permit multiple calls to begin() without error.

When this flag is set, calling begin() while a transaction is already active will effectively do nothing (the existing transaction is reused). This is useful for code paths where the transaction boundaries are not strictly known or may overlap.

Note: This setting usually persists only for the lifetime of this handler instance.

iterateQuery

de.ipcon.db.core.QueryResultsI iterateQuery(java.lang.String s,
                                            java.lang.Object[] parms,
                                            short mode)

iterateQuery

de.ipcon.db.core.QueryResultsI iterateQuery(java.lang.String s,
                                            java.lang.Object[] parms)

iterateQuery

de.ipcon.db.core.QueryResultsI iterateQuery(java.lang.String s)

listQuery

java.util.List listQuery(java.lang.String s,
                         java.lang.Object[] parms,
                         short mode)

listQuery

java.util.List listQuery(java.lang.String s,
                         java.lang.Object[] parms)

listQuery

java.util.List listQuery(java.lang.String s)

iterateRelationBOs

de.ipcon.db.core.QueryResultsI iterateRelationBOs(java.lang.Class<? extends BOI> classtip,
                                                  java.lang.Long id,
                                                  java.lang.String attName,
                                                  short mode)

iterateRelationBOs

de.ipcon.db.core.QueryResultsI iterateRelationBOs(java.lang.Class<? extends BOI> classtip,
                                                  java.lang.Long id,
                                                  java.lang.String attName)

listRelationBOs

java.util.List listRelationBOs(java.lang.Class<? extends BOI> classtip,
                               java.lang.Long id,
                               java.lang.String attName,
                               short mode)

listRelationBOs

java.util.List listRelationBOs(java.lang.Class<? extends BOI> classtip,
                               java.lang.Long id,
                               java.lang.String attName)

getJdbcConnection

java.sql.Connection getJdbcConnection()

assureClassStability

BO assureClassStability(BO bo,
                        int mode,
                        java.util.Set<java.lang.Long> keepLocked)

getSchema

SchemaI getSchema()

getInjectBOLoader

BOLoaderI getInjectBOLoader()

setInjectBOLoader

void setInjectBOLoader(BOLoaderI bol)

iterateNativeQuery

de.ipcon.db.core.QueryResultsI iterateNativeQuery(java.lang.String s,
                                                  java.lang.Object[] parms,
                                                  short mode,
                                                  java.lang.String[] prefetchPaths)

iterateNativeQuery

de.ipcon.db.core.QueryResultsI iterateNativeQuery(java.lang.String s,
                                                  java.lang.Object[] parms,
                                                  short mode)

iterateNativeQuery

de.ipcon.db.core.QueryResultsI iterateNativeQuery(java.lang.String s,
                                                  java.lang.Object[] parms)

iterateNativeQuery

de.ipcon.db.core.QueryResultsI iterateNativeQuery(java.lang.String s)