org.tentackle.db
Class ModificationLog

java.lang.Object
  org.tentackle.db.DbObject
      org.tentackle.db.ModificationLog

All Implemented Interfaces:

Serializable, Cloneable, Comparable<DbObject>

public class ModificationLog
extends DbObject

Logging for object modifications.
Modifications to DbObjects can be logged to a so-called modification log (aka: modlog).
Most applications will use the modlog for asynchroneous database coupling.

Note: the txId is only valid (> 0) if the db-connection has Db.isLogModificationTxEnabled(), i.e. begin and commit records are logged as well. If the IdSource of the modlog is transaction-based, transactions will not overlap in the modlog because obtaining the id for the modlog is part of the transaction. However, if the idsource is remote (poolkeeper rmi-client, for example), transactions may overlap! In such cases the txid is necessary to separate the modlog sequences into discrete transactions. (see the PoolKeeper project)

See Also:

Serialized Form

Nested Class Summary

Nested classes/interfaces inherited from class org.tentackle.db.DbObject

DbObject.CopyAllToDbLogger, DbObject.IdComparator<T extends DbObject>, DbObject.NameComparator<T extends DbObject>, DbObject.NameIdComparator<T extends DbObject>

Field Summary

static String	FIELD_ERRORCODE database column name for errorCode
static String	FIELD_EXTRAID database column name for extraId
static String	FIELD_MESSAGE database column name for message
static String	FIELD_MODTYPE database column name for modType
static String	FIELD_OBJECTCLASS database column name for objectClass
static String	FIELD_OBJECTID database column name for objectId
static String	FIELD_TXID database column name for txId
static String	FIELD_TXNAME database column name for txName
static String	FIELD_USER database column name for user
static String	FIELD_WHEN database column name for when
protected DbObject	lazyObject The DbObject the log belongs to.
static int	LENGTH_OBJECTCLASS maximum number of characters for objectClass
static int	LENGTH_TXNAME maximum number of characters for txName
static int	LENGTH_USER maximum number of characters for user
static String	modlogClassname The classname of the global modlog.
static String	TABLENAME database tablename

Fields inherited from class org.tentackle.db.DbObject

BEGIN, COMMIT, DELETE, DELETEALL, FIELD_ID, FIELD_SERIAL, FIELD_TABLESERIAL, idComparator, INSERT, lazyMethodInterval, nameComparator, nameIdComparator, TX_DELETE_LIST, TX_DELETE_MISSING_IN_LIST, TX_DELETE_OBJECT, TX_DUMMY_UPDATE, TX_INSERT_OBJECT, TX_INSERT_PLAIN, TX_SAVE, TX_SAVE_LIST, TX_UPDATE_OBJECT, TX_UPDATE_PLAIN, TX_UPDATE_SERIAL, TX_UPDATE_SERIAL_AND_TABLESERIAL, TX_UPDATE_TABLESERIAL, UPDATE

Constructor Summary

ModificationLog()
Creates an empty modlog.

ModificationLog(Db db)
Creates an empty modification log for a given db.

ModificationLog(Db db, char modType)
Creates a modification log for a given db and modification type.

ModificationLog(DbObject object, char modType)
Creates a modification log from an object.

ModificationLog(ModificationLog template, char modType)
Creates a modlog from another modlog, but a different type.

Method Summary

void	clearLazyObject() Clears the lazyObject.
DbObjectClassVariables	getDbObjectClassVariables() Gets the some attributes and variables common to all objects of the same class.
int	getErrorCode() Gets the db attribute errorCode
long	getExtraId() Gets the db attribute extraId
boolean	getFields(ResultSetWrapper rs) Retrieves the values of all fields (all columns of the database table) in the given ResultSetWrapper and stores them in the object's attributes.
String	getMessage() Gets the db attribute message
char	getModType() Gets the db attribute modType
DbObject	getObject() Gets the object referenced by this ModificationLog.
DbObject	getObject(Db db) Gets the object referenced by this ModificationLog. The object is lazily cached if the given db equals the db of this modlog.
String	getObjectClass() Gets the db attribute objectClass
long	getObjectId() Gets the db attribute objectId
long	getTxId() Gets the db attribute txId
String	getTxName() Gets the db attribute txName
String	getUser() Gets the db attribute user
Timestamp	getWhen() Gets the db attribute when
static ModificationLog	instance() Gets the global modification logger object.
static boolean	isReferencingObject(Db db, String objectClass, long objectId) Checks if there are logs for a given object.
boolean	isReferencingObject(String objectClass, long objectId) Checks whether references exist.
static boolean	isReferencingUser(Db db, String user) Checks if there are logs for a given object.
boolean	isReferencingUser(String user) Checks whether references exist.
int	prepareInsertStatement() Prepares the insert statement.
int	prepareUpdateStatement() Prepare the update statement.
long	replay(List<ModificationLog> modList, boolean copyLog, Db toDb) Replays a list of modlogs within a single transaction. It will also create new txId if the modlogs are copied.
boolean	replay(ModificationLog modlog, Db toDb) Applies a modification to another db. The method is not static to allow overriding (e.g.
boolean	save() Saves this object. This is the standard method applications should use to insert or update objects.
List<ModificationLog>	selectByObject(String objectClass, long objectId) Gets the modlogs for a given object.
ModificationLog	selectFirst() Selects the next record to process, i.e.
void	setDb(Db db) Sets the logical db connection for this object.
void	setErrorCode(int errorCode) Sets the db attribute errorCode
void	setExtraId(long extraId) Sets the db attribute extraId
int	setFields(PreparedStatementWrapper st) Sets the values of all fields (all columns of the database table) in the given PreparedStatementWrapper from the object's attributes.
void	setMessage(String message) Sets the db attribute message
void	setTxId(long txId) Sets the db attribute txId
void	setTxName(String txName) Sets the db attribute txName
String	toString() Just for logging.

Methods inherited from class org.tentackle.db.DbObject

_delete, _save, alwaysPrepare, assertLazyNotWithinTX, attributesModified, beginTx, clone, compareTo, copyAllToDb, copyLazyValues, copyToDb, countModification, countModification, createModificationLog, delete, deleteLinkedObjects, deleteList, deleteMissingInList, deleteObject, deletePlain, dummyUpdate, equals, finishModification, finishNotUpdated, getClassBaseName, getClassName, getDb, getDeleteStatementId, getDummyUpdateStatementId, getExpirationBacklog, getExpiredTableSerials, getFieldCount, getIcon, getId, getIdSource, getInsertStatementId, getMultiName, getRemoteDelegate, getRemoteDelegateId, getSelectAllStatementId, getSelectExpiredTableSerials1StatementId, getSelectExpiredTableSerials2StatementId, getSelectLockedStatementId, getSelectSerialStatementId, getSelectStatementId, getSerial, getSingleName, getSqlAllFields, getSqlPrefix, getSqlPrefixWithDot, getSqlSelectAllFields, getTableName, getTableSerial, getUpdateSerialAndTableSerialStatementId, getUpdateSerialStatementId, getUpdateStatementId, getUpdateTableSerialStatementId, hashCode, initModification, insert, insertObject, insertPlain, invalidateLazyValues, isCountingModification, isDeleted, isEditable, isEditableLazy, isEntity, isGettingFieldCount, isIdValid, isLazyElapsed, isListModified, isLoggingModification, isModified, isNew, isPartial, isReferenced, isReferencedLazy, isRemovable, isRemovableLazy, isSaveable, isTableSerialValid, isTracked, isTxObject, isUpdatingSerialEvenIfNotModified, isVirgin, loadLinkedObjects, logModification, markDeleted, markListDeleted, newByClass, newByClass, newByClassWrapped, newId, newObject, prepareDeleteStatement, prepareDummyUpdateStatement, prepareSelectLockedStatement, prepareSelectSerialStatement, prepareSelectStatement, prepareSetFields, prepareUpdateSerialAndTableSerialStatement, prepareUpdateSerialStatement, prepareUpdateTableSerialStatement, readFromResultSetWrapper, readFromResultSetWrapper, reload, reloadLocked, reserveId, saveLinkedObjects, saveList, saveList, select, select, select, select, selectAll, selectAll, selectAll, selectAllCursor, selectAllCursor, selectAllResultSet, selectExpiredTableSerials, selectExpiredTableSerials, selectInValidContext, selectLocked, selectLocked, selectModification, selectNext, selectSerial, selectSerial, setAlwaysPrepare, setDeleteStatementId, setDummyUpdateStatementId, setId, setInsertStatementId, setModified, setSelectAllStatementId, setSelectExpiredTableSerials1StatementId, setSelectExpiredTableSerials2StatementId, setSelectLockedStatementId, setSelectSerialStatementId, setSelectStatementId, setSerial, setTableSerial, setUpdateSerialAndTableSerialStatementId, setUpdateSerialStatementId, setUpdateStatementId, setUpdateTableSerialStatementId, sync, syncObject, toGenericString, update, updateFieldCount, updateFields, updateObject, updatePlain, updateSerial, updateSerialAndTableSerial, updateTableSerial

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

TABLENAME

public static final String TABLENAME

database tablename

See Also:

Constant Field Values

lazyObject

protected DbObject lazyObject

The DbObject the log belongs to. null = unknown. Speeds up getObject(org.tentackle.db.Db) in distributed applications (see the poolkeeper framework).

FIELD_OBJECTID

public static final String FIELD_OBJECTID

database column name for objectId

See Also:

Constant Field Values

FIELD_OBJECTCLASS

public static final String FIELD_OBJECTCLASS

database column name for objectClass

See Also:

Constant Field Values

FIELD_TXID

public static final String FIELD_TXID

database column name for txId

See Also:

Constant Field Values

FIELD_TXNAME

public static final String FIELD_TXNAME

database column name for txName

See Also:

Constant Field Values

FIELD_MODTYPE

public static final String FIELD_MODTYPE

database column name for modType

See Also:

Constant Field Values

FIELD_WHEN

public static final String FIELD_WHEN

database column name for when

See Also:

Constant Field Values

FIELD_USER

public static final String FIELD_USER

database column name for user

See Also:

Constant Field Values

FIELD_ERRORCODE

public static final String FIELD_ERRORCODE

database column name for errorCode

See Also:

Constant Field Values

FIELD_MESSAGE

public static final String FIELD_MESSAGE

database column name for message

See Also:

Constant Field Values

FIELD_EXTRAID

public static final String FIELD_EXTRAID

database column name for extraId

See Also:

Constant Field Values

LENGTH_OBJECTCLASS

public static final int LENGTH_OBJECTCLASS

maximum number of characters for objectClass

See Also:

Constant Field Values

LENGTH_TXNAME

public static final int LENGTH_TXNAME

maximum number of characters for txName

See Also:

Constant Field Values

LENGTH_USER

public static final int LENGTH_USER

maximum number of characters for user

See Also:

Constant Field Values

modlogClassname

public static String modlogClassname

The classname of the global modlog. Change this in your app if you're extending ModificationLog.

Constructor Detail

ModificationLog

public ModificationLog(Db db)

Creates an empty modification log for a given db. Useful for reading the log or as an RMI-proxy.

Parameters:

db - the database connection

ModificationLog

public ModificationLog(Db db,
                       char modType)

Creates a modification log for a given db and modification type.

Parameters:

db - the database connection

modType - is the modification type (BEGIN or COMMIT)

ModificationLog

public ModificationLog(DbObject object,
                       char modType)

Creates a modification log from an object.

Parameters:

object - is the logged object

modType - is the modification type (INSERT, UPDATE...)

ModificationLog

public ModificationLog(ModificationLog template,
                       char modType)

Creates a modlog from another modlog, but a different type.

Parameters:

template - the modlog template

modType - is the modification type (INSERT, UPDATE...)

ModificationLog

public ModificationLog()

Creates an empty modlog. Constructor only provided for Class.newInstance().

Method Detail

setDb

public void setDb(Db db)

Sets the logical db connection for this object..
Overridden to set the db in lazyObject too (if unmarshalled from remote db)

Overrides:

setDb in class DbObject

Parameters:

db - the db connection

clearLazyObject

public void clearLazyObject()

Clears the lazyObject. Necessary for replaying modlogs that should not copy the lazyObject to a remote db.

save

public boolean save()

Saves this object.
This is the standard method applications should use to insert or update objects.

If the ID is 0, a new ID is obtained and this object inserted. Otherwise this object is updated. The modified attribute gets cleared if save() was successful.

Overridden to check for deferred logging.

Overrides:

save in class DbObject

Returns:

true of done, false if duplicate

setFields

public int setFields(PreparedStatementWrapper st)

Description copied from class: DbObject

Sets the values of all fields (all columns of the database table) in the given PreparedStatementWrapper from the object's attributes.

Specified by:

setFields in class DbObject

Parameters:

st - the statement

Returns:

the number of fields set, -1 if error.

getFields

public boolean getFields(ResultSetWrapper rs)

Description copied from class: DbObject

Retrieves the values of all fields (all columns of the database table) in the given ResultSetWrapper and stores them in the object's attributes.

Specified by:

getFields in class DbObject

Parameters:

rs - the result set

Returns:

true if all fields retrieved

prepareInsertStatement

public int prepareInsertStatement()

Description copied from class: DbObject

Prepares the insert statement.

Specified by:

prepareInsertStatement in class DbObject

Returns:

the statememt id

prepareUpdateStatement

public int prepareUpdateStatement()

Description copied from class: DbObject

Prepare the update statement.

Specified by:

prepareUpdateStatement in class DbObject

Returns:

the statememt id

toString

public String toString()

Just for logging.

Overrides:

toString in class DbObject

Returns:

the string value of this DbObject

getObject

public DbObject getObject(Db db)
                   throws ApplicationException

Gets the object referenced by this ModificationLog.
The object is lazily cached if the given db equals the db of this modlog.

Parameters:

db - is the db-connection from which to load the object.

Returns:

the object or null if not found.

Throws:

ApplicationException - if instantiation failed.

getObject

public DbObject getObject()
                   throws ApplicationException

Gets the object referenced by this ModificationLog. The object is lazily cached.

Returns:

the object or null if not found.

Throws:

ApplicationException - if instantiation failed.

selectFirst

public ModificationLog selectFirst()

Selects the next record to process, i.e. the one with the lowest ID and errorCode == 0.
When processed the modlog should be deleted.

Returns:

the modlog, null if no unprocessed log found

Wurblet:

selectFirst DbSelectUnique $mapfile $remote errorCode:=:0 --append="\" ORDER BY \" + FIELD_ID"

selectByObject

public List<ModificationLog> selectByObject(String objectClass,
                                            long objectId)

Gets the modlogs for a given object.

Parameters:

objectClass - the object's class name

objectId - the object's ID

Returns:

the list of modlogs

Wurblet:

selectByObject DbSelectList $mapfile $remote objectClass objectId --append="\" ORDER BY \" + FIELD_ID"

isReferencingUser

public static boolean isReferencingUser(Db db,
                                        String user)

Checks if there are logs for a given object.

Parameters:

db - the db connection

objectClass - the object's classname

objectId - the object's ID

Returns:

true if there are logs

Wurblet:

isReferencingUser DbIsReferencing $mapfile $remote user --static

isReferencingUser

public boolean isReferencingUser(String user)

Checks whether references exist.

Parameters:

user - name of user

Returns:

true if referencing

isReferencingObject

public static boolean isReferencingObject(Db db,
                                          String objectClass,
                                          long objectId)

Checks if there are logs for a given object.

Parameters:

db - the db connection

objectClass - the object's classname

objectId - the object's ID

Returns:

true if there are logs

Wurblet:

isReferencingObject DbIsReferencing $mapfile $remote objectClass objectId --static

isReferencingObject

public boolean isReferencingObject(String objectClass,
                                   long objectId)

Checks whether references exist.

Parameters:

objectClass - object classname

objectId - object id

Returns:

true if referencing

getDbObjectClassVariables

public DbObjectClassVariables getDbObjectClassVariables()

Description copied from class: DbObject

Gets the some attributes and variables common to all objects of the same class. Class variables for classes derived from DbObject are kept in an instance of DbObjectClassVariables.

Specified by:

getDbObjectClassVariables in class DbObject

Returns:

the class variables

getObjectId

public long getObjectId()

Gets the db attribute objectId

Returns:

object id

getObjectClass

public String getObjectClass()

Gets the db attribute objectClass

Returns:

object classname

getTxId

public long getTxId()

Gets the db attribute txId

Returns:

transaction id (optional)

setTxId

public void setTxId(long txId)

Sets the db attribute txId

Parameters:

txId - transaction id (optional)

getTxName

public String getTxName()

Gets the db attribute txName

Returns:

transaction name (optional)

setTxName

public void setTxName(String txName)

Sets the db attribute txName

Parameters:

txName - transaction name (optional)

getModType

public char getModType()

Gets the db attribute modType

Returns:

modification type

getWhen

public Timestamp getWhen()

Gets the db attribute when

Returns:

time of event

getUser

public String getUser()

Gets the db attribute user

Returns:

name of user

getErrorCode

public int getErrorCode()

Gets the db attribute errorCode

Returns:

error number (0=ok)

setErrorCode

public void setErrorCode(int errorCode)

Sets the db attribute errorCode

Parameters:

errorCode - error number (0=ok)

getMessage

public String getMessage()

Gets the db attribute message

Returns:

optional informational or error message

setMessage

public void setMessage(String message)

Sets the db attribute message

Parameters:

message - optional informational or error message

getExtraId

public long getExtraId()

Gets the db attribute extraId

Returns:

some optional id for any purpose

setExtraId

public void setExtraId(long extraId)

Sets the db attribute extraId

Parameters:

extraId - some optional id for any purpose

instance

public static ModificationLog instance()

Gets the global modification logger object. (notice: no singleton hype here, it's just a hook for the methods below)

Returns:

the modlog

replay

public boolean replay(ModificationLog modlog,
                      Db toDb)
               throws ApplicationException

Applies a modification to another db.
The method is not static to allow overriding (e.g. to extend with more transaction types). Method is invoked within a tx, so no begin/commit/rollback necessary

Parameters:

modlog - the modification log to replay

toDb - the db the logs will be applied to

Returns:

true if replayed, false if some db-error

Throws:

ApplicationException - if applied to BEGIN/COMMIT or object does not exist or integrity rules failed

replay

public long replay(List<ModificationLog> modList,
                   boolean copyLog,
                   Db toDb)
            throws ApplicationException

Replays a list of modlogs within a single transaction.
It will also create new txId if the modlogs are copied. The method is not static to allow overriding (e.g. to extend with more transaction types).

Parameters:

modList - the list of log objects from the source db

copyLog - true to copy the logs as well

toDb - the db the logs will be applied to

Returns:

the txId if copyLog was true and a BEGIN log found, 0 otherwise

Throws:

ApplicationException - if replay failed