org.tentackle.appworx
Class History

java.lang.Object
  org.tentackle.db.DbObject
      org.tentackle.appworx.AppDbObject
          org.tentackle.appworx.History

All Implemented Interfaces:

Serializable, Cloneable, Comparable<DbObject>, ContextDependable

public abstract class History
extends AppDbObject

Class to read and write history records for a given AppDbObject-class. There are two options to run history-based tables:

1. History-tables are managed by the dbms itself. Usually they are created as triggers like this (postgres):

    # usage: makeHistoryRules.sh 
   
    newtable=h_"$1"
    echo '
    CREATE TABLE' "$newtable" 'AS SELECT * FROM' "$1" 'WHERE ID=-1;
    ALTER TABLE' "$newtable" 'ADD h_time TIMESTAMP;
    ALTER TABLE' "$newtable" 'ADD h_user TEXT;
    ALTER TABLE' "$newtable" 'ADD h_type CHAR(1);
    CREATE INDEX' "$newtable"_id 'ON' "$newtable" '(id, serial, h_time);
    GRANT ALL ON' "$newtable" 'TO PUBLIC;
    CREATE RULE insert_'"$newtable" 'AS ON INSERT TO' "$1" 'DO INSERT INTO' "$newtable" 'VALUES (new.*,current_timestamp,current_user,'"'I'"');
    CREATE RULE update_'"$newtable" 'AS ON UPDATE TO' "$1" 'DO INSERT INTO' "$newtable" 'VALUES (new.*,current_timestamp,current_user,'"'U'"');
    CREATE RULE delete_'"$newtable" 'AS ON DELETE TO' "$1" 'DO INSERT INTO' "$newtable" 'VALUES (old.*,current_timestamp,current_user,'"'D'"');
    

2. Tentacle itself is responsible for creating the history records. In this case AppDbObject.isLoggingHistory() must be overridden to return true. Notice however that tentackle-bases history usually runs slower and not all modifications will be caught, e.g. deleteAll() or editedBy-changes. An AppDbObject that provides access to its history needs to subclass 'History' as follows:

    public class BlaHistory extends History {
   
      public BlaHistory(Blah blah)  {
        super(blah);
      }
   
      public BlaHistory() {
        super();
      }
      
      public AppDbObjectClassVariables getAppDbObjectClassVariables() {
        return classVariables;
      }  
   
     private static AppDbObjectClassVariables classVariables = 
        new AppDbObjectClassVariables(BlaHistory.class, HISTORY_TABLENAME_PREFIX + 
             Bla.TABLENAME, "History Entry", "History Entries");
      }
    

In order to automatically enable the GUI-Features to access the history, the AppDbObject must override two methods: allowsHistory and getHistory() as follows:

   public boolean allowsHistory() {
     return true;
   }
   
   public History getHistory() {
     return new BlaHistory(this);
   }
 

The wurblet "History" does all that automatically.

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

protected AppDbObject	appDbObject
static String	FIELD_TIME database column name for the timestamp when modification took place
static String	FIELD_TYPE database column name for the modification type
static String	FIELD_USER database column name for the user who did the modification
static String	HISTORY_TABLENAME_PREFIX prefix prepended to the table name of history objects

Fields inherited from class org.tentackle.appworx.AppDbObject

FIELD_EDITEDBY, FIELD_EDITEDEXPIRY, FIELD_EDITEDSINCE, FIELD_NORMTEXT, TX_DELETE_ALL_IN_CONTEXT, TX_SAVE_COPY_IN_CONTEXT, TX_TRANSFER_EDITEDBY, VERIFIED_DUPLICATE

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

History()
Creates an empty history object.

History(AppDbObject appDbObject)
Creates a history object.

History(ContextDb db)
Creates an empty history object.

Method Summary

boolean	createHistoryLog(char type) Creates a history log for the current object and saves it to the database. The username is taken from the database UserInfo.
AppDbObject	getAppDbObject() Gets the referenced object.
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.
FormTableEntry	getFormTableEntry() Gets the table entry for viewing lists of this object in a FormTable. The default implementation returns an AppDbObjectDefaultTableEntry.
Timestamp	getTime() Gets the modification time.
char	getType() Gets the modification type.
String	getUser() Gets the username.
AppDbObject	newObject() Creates an instance of the same class as this object, initialized in the same contextDb.
int	prepareDeleteStatement() Prepares the delete statement (usually the same for all objects)
int	prepareInsertStatement() Prepares the insert statement.
int	prepareUpdateStatement() Prepare the update statement.
boolean	readFromResultSetWrapper(ResultSetWrapper rs, boolean withLinkedObjects) Reads the values from a result-set into this object.
AppDbObject	restoreObjectForSerial(long objectId, long objectSerial) Restores an object for a given revision, i.e.
List<History>	selectByObjectId(long objectId) Selects all history objects for a given object id, sorted by time. In order not to confuse the user, suppresses changes on the data not visible to the user.
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.
String	toString() Gets the default string value. The default implementation invokes DbObject.toGenericString().
static String	typeToString(char type) Converts a modification type to a localized string.

Methods inherited from class org.tentackle.appworx.AppDbObject

allowsHistory, allowsTreeChildObjects, allowsTreeParentObjects, clearEditedBy, containsPattern, copy, copyCollection, copyLazyValues, countCacheAccess, countModification, createCopyInContextDb, dropTransferable, expireCache, extractTreePath, extractTreePathObjects, filterAppDbObjects, findDuplicate, finishModification, finishNotUpdated, getAppDbObjectClassVariables, getBaseContext, getCache, getCacheAccessCount, getCacheAccessTime, getClassPath, getContextDb, getContextId, getCopiedObject, getDbObjectClassVariables, getEditedBy, getEditedByObject, getEditedExpiry, getEditedSince, getFormTableName, getHistory, getMultiName, getNormText, getPanelObject, getRemoteDelegate, getSecurityManager, getSecurityResult, getSelectAllInContextCursorStatementId, getSelectAllInContextStatementId, getSelectByNormTextCursorStatementId, getSelectByNormTextStatementId, getSelectEditedByStatementId, getSingleName, getSqlContextCondition, getToolTipText, getToolTipText, getTransferable, getTransferEditedByStatementId, getTransientData, getTreeChildObjects, getTreeChildObjects, getTreeExpandMaxDepth, getTreeParentObjects, getTreeParentObjects, getTreeRoot, getTreeText, getTreeText, getUpdateEditedByOnlyStatementId, getUpdateEditedByStatementId, getUpdateEditedByTimeout, initModification, invalidateLazyValues, isCacheable, isCached, isComposite, isEditedLocked, isExpired, isInstantiatable, isLoggingHistory, isPermissionAccepted, isPermissionDefault, isPermissionDenied, isReferenced, isShowable, isShowableLazy, loadClass, loadComposites, loadComposites, logHistory, makeQbfPlugin, makeQbfPlugin, makeValidContext, markCacheAccess, newByClass, newByClassBaseName, newPanel, orderBy, panelExists, permissionType, prepareSelectEditedByStatement, prepareSetFields, prepareTransferEditedByStatement, prepareUpdateEditedByOnlyStatement, prepareUpdateEditedByStatement, presetQbfParameter, resultAllInContext, resultAllInContextCursor, resultByNormText, resultByNormTextCursor, save, saveCopyInContextDb, saveInContextDb, searchQbf, searchQbfCursor, select, select, select, select, selectAll, selectAllInContext, selectAllInContext, selectAllInContextCached, selectAllInContextCursor, selectAllInValidContext, selectAllInValidContext, selectByNormText, selectByNormTextCursor, selectByTemplate, selectCached, selectCached, selectCached, selectInValidContext, selectInValidContext, selectInValidContext, selectInValidContext, selectInValidContext, selectInValidContext, selectLocked, selectLocked, selectLocked, selectLocked, setCacheAccessCount, setCacheAccessTime, setClassPath, setContextDb, setContextId, setDb, setEditedBy, setEditedByObject, setEditedExpiry, setEditedSince, setExpired, setNormText, setSelectAllInContextCursorStatementId, setSelectAllInContextStatementId, setSelectByNormTextCursorStatementId, setSelectByNormTextStatementId, setSelectEditedByStatementId, setTransferEditedByStatementId, setTransientData, setUpdateEditedByOnlyStatementId, setUpdateEditedByStatementId, stopTreeExpansion, transferEditedBy, updateEditedBy, updateEditedBy, updateEditedByOnly, updateObject, verify

Methods inherited from class org.tentackle.db.DbObject

_delete, _save, alwaysPrepare, assertLazyNotWithinTX, attributesModified, beginTx, clone, compareTo, copyAllToDb, copyToDb, countModification, createModificationLog, delete, deleteLinkedObjects, deleteList, deleteMissingInList, deleteObject, deletePlain, dummyUpdate, equals, getClassBaseName, getClassName, getDb, getDeleteStatementId, getDummyUpdateStatementId, getExpirationBacklog, getExpiredTableSerials, getFieldCount, getIcon, getId, getIdSource, getInsertStatementId, getMultiName, getRemoteDelegateId, getSelectAllStatementId, getSelectExpiredTableSerials1StatementId, getSelectExpiredTableSerials2StatementId, getSelectLockedStatementId, getSelectSerialStatementId, getSelectStatementId, getSerial, getSingleName, getSqlAllFields, getSqlPrefix, getSqlPrefixWithDot, getSqlSelectAllFields, getTableName, getTableSerial, getUpdateSerialAndTableSerialStatementId, getUpdateSerialStatementId, getUpdateStatementId, getUpdateTableSerialStatementId, hashCode, insert, insertObject, insertPlain, isCountingModification, isDeleted, isEditable, isEditableLazy, isEntity, isGettingFieldCount, isIdValid, isLazyElapsed, isListModified, isLoggingModification, isModified, isNew, isPartial, isReferencedLazy, isRemovable, isRemovableLazy, isSaveable, isTableSerialValid, isTracked, isTxObject, isUpdatingSerialEvenIfNotModified, isVirgin, loadLinkedObjects, logModification, markDeleted, markListDeleted, newByClass, newByClass, newByClassWrapped, newId, prepareDummyUpdateStatement, prepareSelectLockedStatement, prepareSelectSerialStatement, prepareSelectStatement, prepareUpdateSerialAndTableSerialStatement, prepareUpdateSerialStatement, prepareUpdateTableSerialStatement, readFromResultSetWrapper, reload, reloadLocked, reserveId, saveLinkedObjects, saveList, saveList, select, select, selectAll, selectAll, selectAllCursor, selectAllCursor, selectAllResultSet, selectExpiredTableSerials, selectExpiredTableSerials, 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, updatePlain, updateSerial, updateSerialAndTableSerial, updateTableSerial

Methods inherited from class java.lang.Object

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

Field Detail

HISTORY_TABLENAME_PREFIX

public static final String HISTORY_TABLENAME_PREFIX

prefix prepended to the table name of history objects

See Also:

Constant Field Values

FIELD_TIME

public static final String FIELD_TIME

database column name for the timestamp when modification took place

See Also:

Constant Field Values

FIELD_USER

public static final String FIELD_USER

database column name for the user who did the modification

See Also:

Constant Field Values

FIELD_TYPE

public static final String FIELD_TYPE

database column name for the modification type

See Also:

Constant Field Values

appDbObject

protected AppDbObject appDbObject

Constructor Detail

History

public History(AppDbObject appDbObject)

Creates a history object.

Parameters:

appDbObject - the database object

History

public History(ContextDb db)

Creates an empty history object.

Parameters:

db - the database context

History

public History()

Creates an empty history object.

Method Detail

typeToString

public static String typeToString(char type)

Converts a modification type to a localized string.

Parameters:

type - the modification type (INSERT, UPDATE or DELETE)

Returns:

the localized string

getTime

public Timestamp getTime()

Gets the modification time.

Returns:

the modification time

getUser

public String getUser()

Gets the username.

Returns:

the username

getType

public char getType()

Gets the modification type.

Returns:

the modification type.

getAppDbObject

public AppDbObject getAppDbObject()

Gets the referenced object.

Returns:

the database object

newObject

public AppDbObject newObject()

Description copied from class: AppDbObject

Creates an instance of the same class as this object, initialized in the same contextDb.

Overrides:

newObject in class AppDbObject

Returns:

the new object

selectByObjectId

public List<History> selectByObjectId(long objectId)

Selects all history objects for a given object id, sorted by time.
In order not to confuse the user, suppresses changes on the data not visible to the user.

Parameters:

objectId - the object ID

Returns:

the list of History objects

restoreObjectForSerial

public AppDbObject restoreObjectForSerial(long objectId,
                                          long objectSerial)

Restores an object for a given revision, i.e. serial.
For composites this requires that the parent object's methods DbObject.isTxObject() and DbObject.isUpdatingSerialEvenIfNotModified() return true as this will force all updated childs of the composite parent to get the serial of the parent. Important: the method will not load the childs and has to be overwridden to do so (which depends on the application's semantics).

Parameters:

objectId - the object's ID

objectSerial - the object's revision/serial

Returns:

the object at given revision or older, null if none

createHistoryLog

public boolean createHistoryLog(char type)

Creates a history log for the current object and saves it to the database.
The username is taken from the database UserInfo. The time is the current system time.

Parameters:

type - the modification type

Returns:

true if this History object saved

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

readFromResultSetWrapper

public boolean readFromResultSetWrapper(ResultSetWrapper rs,
                                        boolean withLinkedObjects)

Description copied from class: AppDbObject

Reads the values from a result-set into this object.

Overridden due to security check whether reading this object is allowed. If not, false is returned as if reading some values failed.

Overrides:

readFromResultSetWrapper in class AppDbObject

Parameters:

rs - is the result set (wrapper)

withLinkedObjects - is true if load linked objects too

Returns:

true if values read, false if some error

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.

prepareInsertStatement

public int prepareInsertStatement()

Prepares the insert statement.

Overridden to take the sql-string from the AppDbObject and modify it. This method relies on the special format of an insert-statement! Make sure to let the insert-statement be created by the insert-wurblet!!!

Specified by:

prepareInsertStatement in class DbObject

Returns:

the statememt id

prepareUpdateStatement

public int prepareUpdateStatement()

Prepare the update statement.

Invokes the errorhandler because History objects cannot be updated.

Specified by:

prepareUpdateStatement in class DbObject

Returns:

the statememt id

prepareDeleteStatement

public int prepareDeleteStatement()

Prepares the delete statement (usually the same for all objects)

Invokes the errorhandler because History objects cannot be deleted.

Overrides:

prepareDeleteStatement in class DbObject

Returns:

the statememt id

toString

public String toString()

Description copied from class: DbObject

Gets the default string value.
The default implementation invokes DbObject.toGenericString().

Overrides:

toString in class DbObject

Returns:

the string value of this DbObject

getFormTableEntry

public FormTableEntry getFormTableEntry()

Gets the table entry for viewing lists of this object in a FormTable.
The default implementation returns an AppDbObjectDefaultTableEntry. Should be overridden in subclasses.

Returns a HistoryTableEntry.

Overrides:

getFormTableEntry in class AppDbObject

Returns:

the formtable entry

See Also:

AppDbObject.getFormTableName()